AGENTS.md

1# apps/server — Agent Instructions
2 
3Express 5 REST API + WebSocket server for the knowledge graph.
4 
5## Entry Point
6 
7`src/index.ts` → Express 5 app. Port **7430** (`BRAIN_API_PORT` env var).
8 
9## Key Files
10 
11| File | Purpose |
12|------|---------|
13| `src/app.ts` | Express app setup (middleware, error handling) |
14| `src/brain-instance.ts` | Singleton Brain instance |
15| `src/routes/` | Route modules |
16| `src/schemas.ts` | Zod request/response schemas |
17| `src/middleware/` | Auth, validation, error middleware |
18| `src/services/` | Business logic services |
19| `src/ws/` | WebSocket broadcast setup |
20| `src/hooks/` | Lifecycle hooks |
21 
22## Routes
23 
24Wired in `src/routes/index.ts` via `registerRoutes(app, brain, options)`. Each
25module is mounted with `app.use(...)` and declares its own full `/api/...`
26paths — there is no prefix mounting. `GET /health` is defined directly in
27`src/app.ts`.
28 
29| Route module | Key paths | Purpose |
30|--------------|-----------|---------|
31| `auth.ts` | `/api/auth/{redeem-invite,login,logout,whoami,rotate}` | Identity & session auth |
32| `admin.ts` | `/api/admin/{invites,tokens}`, `/api/{reindex,embeddings/status,export,import,rebuild-embeddings}`, `POST /api/query` | Admin ops, pipeline triggers, NL query (`requireAdmin`) |
33| `entities.ts` | `/api/entities*` (+ `/observations`, `/neighbors`) | Entity CRUD |
34| `relations.ts` | `/api/relations*` | Relation CRUD |
35| `search.ts` | `/api/search`, `/api/stats` | FTS + vector search, graph stats |
36| `query.ts` | `/api/query/{ownership,ownership-tree,parallel-work}` | Code-intelligence queries |
37| `observe.ts` | `/api/observe/*` | Hook + forge event ingestion |
38| `sync.ts` | `/api/sync/*` | Sync state management |
39| `temporal.ts` | `/api/{timeline,contradictions,stale,decisions,temporal/entities}` | Bitemporal queries |
40 
41## Adding a New REST Endpoint
42 
431. Create a route module in `src/routes/` returning a router with full `/api/...` paths
442. Mount it in `src/routes/index.ts` (`registerRoutes`) — not `src/index.ts`
453. Add Zod schemas in `src/schemas.ts` for request validation
46 
47## Conventions
48 
49- WebSocket broadcast after mutations (real-time UI updates)
50- Use `brain-instance.ts` singleton — never construct Brain directly
51- Zod validation middleware on all routes
52