CODEbase — Project Handover Guide

Repository: https://github.com/mdskerba/CODEbase

This is the complete CODEbase application — a people-and-project directory for CODE University students and alumni. This handover includes all source code, configuration, tests, and documentation needed to operate and maintain the system.

---

📋 Quick Handover Checklist

For the Incoming Owner

1. ✅ Clone the repository: git clone https://github.com/mdskerba/CODEbase.git
2. ✅ Read codebase/docs/HOW-TO.md — complete setup and operation guide
3. ✅ Run the application locally to verify everything works
4. ✅ Review the critical warnings in codebase/README.md (sections "Read this before shipping" and "Things that will bite you")
5. ✅ Check your deployment setup in codebase/config/deploy.yml

Key Responsibilities

• Operational: Keep the application running, monitor performance, handle deployments
• DPO Review: The Data Protection Officer must review codebase/docs/gdpr/ before any launch
• Monitoring: Watch the kill criteria metrics at month 6 (see codebase/README.md)
• Background Jobs: Ensure bin/jobs is running in production for digests and GDPR retention

---

📁 Directory Structure

CODEbase/
├── README.md                    ← You are here
├── codebase/                    ← Main Rails application
│   ├── README.md               ← Detailed project docs
│   ├── docs/
│   │   ├── HOW-TO.md           ← Complete setup & operation guide
│   │   ├── FAQ.md              ← Common questions
│   │   └── gdpr/               ← Data protection documentation (CRITICAL)
│   ├── app/                    ← Rails + React source code
│   ├── spec/                   ← Test suite (536 examples)
│   ├── config/
│   │   ├── deploy.yml          ← Kamal deployment config (needs placeholders filled)
│   │   ├── database.yml        ← Database configuration
│   │   └── credentials.yml.enc ← Encrypted secrets (use Rails credentials)
│   ├── bin/dev                 ← Start dev server (port 3000)
│   ├── bin/jobs                ← Start background job processor
│   └── Gemfile                 ← Ruby dependencies

---

🚀 Getting Started (5 minutes)

# 1. Clone and enter directory
git clone https://github.com/mdskerba/CODEbase.git
cd CODEbase/codebase

# 2. Install dependencies
mise install
bundle install
npm install

# 3. Set up database with seed data
bin/rails db:prepare
bin/rails db:seed
bin/rails db:demo:seed
bin/rails db:demo:accounts

# 4. Start the application
bin/dev
# Opens at http://localhost:3000

# 5. In another terminal, start background jobs
bin/jobs

Demo Accounts (printed by db:demo:accounts):

• member@codebase.test — Regular student
• alumnus@codebase.test — Alumni (sees alumni-only data)
• admin@codebase.test — Admin (audit log, reports)

---

⚠️ Critical Before Shipping

Read these three sections in codebase/README.md before any production deployment:

1. "Read this before shipping it" (DPO review required, outstanding questions, validation)
2. "Kill criteria" (month 6 metrics to decide if the feature stays)
3. "Things that will bite you" (gotchas in dependencies and configuration)

GDPR / Data Protection (🔴 BLOCKING ISSUE)

The Data Protection Officer must review:

• codebase/docs/gdpr/privacy-notice.en.md & .de.md
• codebase/docs/gdpr/art30-record.md (GDPR Article 30)
• codebase/docs/gdpr/dpia-screening.md (Data Protection Impact Assessment)
• codebase/docs/gdpr/processors.md (Data processor checklist)

Note: Investor ratings feature has unique GDPR considerations — see the "Read this before shipping" section in codebase/README.md.

---

🛠️ Key Files for Operations

File	Purpose
codebase/docs/HOW-TO.md	Complete operations manual
codebase/docs/FAQ.md	Troubleshooting and common issues
codebase/config/deploy.yml	Production deployment (Kamal)
codebase/config/database.yml	Database connection settings
codebase/bin/dev	Start development server
codebase/bin/jobs	Start background job processor
.ruby-version	Ruby version requirement
codebase/package.json	Node.js dependencies

---

📊 Running Tests

# All tests
bundle exec rspec        # 536 examples
npx vitest run           # React component tests
npx tsc --noEmit         # Type checking

# Performance tests (optional, seeds 2,000-person corpus)
RUN_PERFORMANCE_SPECS=1 bundle exec rspec spec/performance

Critical specs to understand before making changes:

• spec/presenters/person_presenter_spec.rb — Visibility control (exhaustive matrix)
• spec/services/search/document_builder_spec.rb — Hidden fields are unsearchable
• spec/requests/auth_wall_spec.rb — Public routes are explicitly declared
• spec/models/admin_audit_event_spec.rb — Audit log is immutable

---

🔑 Important Design Decisions

Search & Visibility

• Search documents are partitioned by visibility (member vs. alumni)
• Hidden fields are removed from the search index (not just rendering)
• Changing visibility requires re-indexing

Investor Ratings

• Only organizations can be rated (enforced at database level via composite FK)
• Individual angels are listed but not rateable
• No aggregate appears below 3 ratings (prevents authority of single opinions)

Erasure (GDPR Right to Erasure)

• Deletes ratings but anonymises project credits (intentional asymmetry)
• Projects are joint work — one person's erasure doesn't delete shared records
• See privacy notices for the full explanation

Background Jobs (⚠️ CRITICAL)

• Digest emails, freshness prompts, saved-search alerts, automatic erasure
• Must run in production or GDPR retention obligations stop being met
• In production: separate host via bin/jobs

---

📞 Who to Contact

For This Project

• Original Author: Markus Skerba (markuss.skerba@code.berlin)
• Code Repository: https://github.com/mdskerba/CODEbase
• Issues/PRs: Use GitHub issues on the repository

Before Production Launch

• Data Protection Officer: Must review docs/gdpr/
• University IT: Resolve OQ-1 through OQ-4 (see codebase/README.md)
• Legal/Compliance: Privacy notices and processors checklist

---

📈 Maintenance & Monitoring

Month 6 Evaluation (Kill Criteria)

Run at 6 months post-launch to decide if feature continues:

bin/rails metrics:kill_criteria ELIGIBLE_STUDENTS=457

Kill criteria: If any are met, stop feature work and either pivot or shut down:

• Profile creation < 20%
• 90-day return rate < 15%
• Contact-relay send rate < 3%

For investor ratings: Fewer than 15 investors with 3+ publishable ratings → remove feature.

Regular Operations

• Monitor bin/jobs is running (digests, alerts, erasure)
• Rotate config/credentials.yml.enc periodically
• Check deployment logs in config/deploy.yml (Kamal setup)
• Review codebase/docs/HOW-TO.md for troubleshooting

---

🔐 Configuration & Secrets

All secrets are encrypted in codebase/config/credentials.yml.enc. Decrypt with:

bin/rails credentials:edit

Required environment variables for production:

• RAILS_ENV=production
• DATABASE_URL=postgres://...
• GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET (for OAuth)
• MODERATION_EMAIL (who receives reports)
• [CONTROLLER] (your organization name, for privacy notices)

---

🚢 Deployment (Kamal)

codebase/config/deploy.yml is ready but requires:

1. Fill in actual host IPs/domains (currently placeholders)
2. Review docs/gdpr/processors.md first (data hosting is a compliance decision)
3. Run: bin/kamal deploy

See Kamal docs: https://kamal-deploy.org

---

🤝 Handover Complete

This repository contains everything needed to:

• ✅ Understand the codebase (annotated specs, design docs)
• ✅ Run it locally (bin/dev and bin/jobs)
• ✅ Test it (536+ examples)
• ✅ Deploy it (Kamal configuration ready)
• ✅ Operate it (HOW-TO.md, FAQ.md, metrics)
• ✅ Comply with GDPR (privacy notices, audit log, erasure, retention)

Next steps:

1. Read codebase/docs/HOW-TO.md
2. Run the application locally
3. Schedule DPO review of docs/gdpr/
4. Set up deployment infrastructure

---

Good luck! Questions? Start with codebase/docs/FAQ.md.