Initial curated projectbrain source from 8a7b1e0651dbdab97d744cbd2e653ab3970ac6c5

backend/README.md

@@ -0,0 +1,126 @@
+# 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
+
+```bash
+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`
+
+```json
+{
+  "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:
+
+```json
+{
+  "data": {},
+  "meta": {
+    "requestId": "req-...",
+    "timestamp": "..."
+  }
+}
+```
+
+Error:
+
+```json
+{
+  "error": {
+    "code": "PROJECT_NOT_FOUND",
+    "message": "Project not found",
+    "validation": []
+  },
+  "meta": {
+    "requestId": "req-...",
+    "timestamp": "..."
+  }
+}
+```
+
+## Data Source Mode
+
+```text
+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.