ProjectBrain API Backend

This is the dedicated Fastify TypeScript backend for ProjectBrain.

It currently provides fixture-backed API endpoints matching the frontend/API contract while the persistent PostgreSQL/Prisma transition is being prepared.

Current Status

Implemented backend phases:

R1: Fastify skeleton, health endpoint, envelopes, request IDs, error handling.
R2: Projects, Workspace, and Project DNA read endpoints.
R3: Feature Groups, Features, and Evidence read endpoints.
R4: Context Packs and deterministic Prompt generation.
R5: Checks and Review Board actions with idempotency.
R6: Builds, Regressions, and Snapshots.
R7: Knowledge, Memory Rules, Relationships, and Insights.
R8: Capture Center, Review Queue, and AI Actions.
P1: Prisma/PostgreSQL scaffold.
P2: Project/Workspace/DNA database repository path prepared behind a data-source flag, pending local DB smoke verification.

Fixture mode remains available for deterministic previews. Database mode provides production persistence, owner/member authentication, Microsoft Entra login, Gitea integration, remote MCP and the durable portfolio control plane. ProjectBrain intentionally delegates model reasoning to ChatGPT through MCP and therefore has no embedded AI provider by default.

Run

cd backend
pnpm install
pnpm run dev

The default server listens on 0.0.0.0:4000.

Scripts

pnpm run dev starts the backend with tsx watch.
pnpm run build compiles TypeScript to dist/.
pnpm run start runs the compiled server.
pnpm run typecheck runs TypeScript without emitting files.
pnpm run lint currently aliases typecheck.
pnpm run prisma:validate validates the Prisma schema.
pnpm run prisma:generate generates Prisma Client.
pnpm run db:migrate:dev runs local development migrations when DATABASE_URL is available.
pnpm run db:seed runs the local seed when DATABASE_URL is available.
pnpm run smoke:p2 verifies Project/Workspace/DNA database-mode behavior when the backend is running in database mode.

Health

GET /api/health

{
  "data": {
    "status": "ok",
    "service": "projectbrain-api",
    "version": "0.1.0",
    "environment": "development"
  },
  "meta": {
    "requestId": "req-...",
    "timestamp": "2026-06-06T00:00:00.000Z"
  }
}

Incoming x-request-id headers are respected and echoed in both the response header and envelope metadata.

Response Envelope

Success:

{
  "data": {},
  "meta": {
    "requestId": "req-...",
    "timestamp": "..."
  }
}

Error:

{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project not found",
    "validation": []
  },
  "meta": {
    "requestId": "req-...",
    "timestamp": "..."
  }
}

Data Source Mode

PROJECTBRAIN_DATA_SOURCE=fixture | database

Default is fixture.

When database is used, DATABASE_URL is required. The database-backed path is currently prepared for Project/Workspace/DNA parity only. Other endpoint families remain fixture-backed.

Local Postgres

See:

../docs/PERSISTENCE_LOCAL_POSTGRES_SETUP.md
../docs/P2_LOCAL_RUNTIME_VERIFICATION.md

Endpoint Index

See ../docs/REAL_BACKEND_ENDPOINT_INDEX.md for the current R1-R8 endpoint overview.

Not Included Yet

Authenticated private-network deployment is supported; public multi-tenant SaaS operation is not.
No real AI calls.
No upload/import pipeline.
No Redis/BullMQ worker.
No full database-backed replacement for R3-R8.
No frontend client switch by default.

3.5 KiB Raw Blame History