Mastermind/DEVELOPMENT.md

DEVELOPMENT — Mastermind MVP

Web app

• Entry point: web/src/index.js
• Views: web/src/views/*.ejs

Database

Schema is created/altered on startup (MVP style) in ensureSchema().

Tables of interest:

• users, identities — auth + multi-provider identities
• audit_logs — append-only audit trail
• projects, project_members — project profiles + membership
• ingested_emails — unified inbox store (upload now, OAuth later)
• email_connectors — gmail/microsoft status rows
• email_rules — sorting/assignment rules

Audit logging convention

Use:

await audit(req, 'namespace.action', { targetType, targetId, metadata })

Examples:

• auth.login_success
• admin.user_created
• project.created
• inbox.email_imported

Adding a new feature (pattern)

1. Add DB table/column in ensureSchema()
2. Add routes in web/src/index.js
3. Add views in web/src/views/
4. Log all state changes to audit_logs

Worker

• worker/src/worker.js is a placeholder loop.
• Later it will pull from connectors, OCR, classify, and run rule assignment.

Local runbook

Preferred path:

cd /root/clawd/mastermind-mvp
cp .env.example .env

Set at least:

SESSION_SECRET=replace-with-a-long-random-string
BASE_URL=http://localhost:3005
BOOTSTRAP_OWNER_EMAIL=owner@local
BOOTSTRAP_OWNER_PASSWORD=ChangeMe12345

Start the full stack with Postgres:

docker compose up -d --build

Alternative direct Node.js mode with the in-memory DB:

npm ci --prefix web
npm ci --prefix worker
DATABASE_URL=memory://local SESSION_SECRET=replace-with-a-long-random-string BASE_URL=http://localhost:3005 BOOTSTRAP_OWNER_EMAIL=owner@local BOOTSTRAP_OWNER_PASSWORD=ChangeMe12345 npm run start:web
DATABASE_URL=memory://local npm run start:worker

Run tests:

npm test