Libraries
Start with the existing library boundary before adding code. This page covers the architectural dependencies in active use, not every package in the lockfile.
| Library | What it does here | Use it for |
|---|---|---|
| TanStack Start and Router | The full-stack React product | Routes, SSR, navigation, API handlers, and authenticated server functions |
| TanStack Query | Selected client-side server-data views | Library reference capture and details, and Operations screens with local Query clients |
| Better Auth | Sign-in, sessions, and OAuth | Application identity in the primary Cell and MCP consent |
| Drizzle ORM and Kit | Typed SQLite access | Schema, queries, transactions, and checked-in migrations inside the primary Cell |
| Eve | AI task execution | Folder-native skills, allowed tools, streamed drafts, and model selection |
| MCP SDK | External agent protocol | The OAuth-protected application endpoint at /api/mcp |
| Files SDK | Private immutable bytes | Patient sources, managed documents, exports, and workspace manifests |
| LiteParse | Source preparation | PDF text and geometry, OCR retry, Office parsing, and derived artifacts |
| AI SDK | Small structured model calls | Metadata suggestions and views derived from saved prose |
| shadcn-style UI and Base UI | Product interface primitives | Shared accessible components and tokens in packages/ui |
| OpenTelemetry and OpenObserve | Technical diagnostics | Allowlisted traces, RUM, and masked production replay, never clinical authority |
| Zod | Runtime validation | Inputs, evidence receipts, tool payloads, and structured outputs |
Use the right owner
TanStack Start routes belong in apps/oncobrain/src/routes/; authenticated orchestration belongs in src/lib/server/. TanStack Query is deliberately narrow. It does not replace server authorization or the persistence boundary. Never edit src/routeTree.gen.ts.
Drizzle runs inside OrganizationCell("primary"). Product services call appPersistence capability contracts, which return application values and outcomes rather than query builders, SQL, rows, or transaction handles. Generate and check in a migration after a schema change. Direct bun:sqlite is only for fixtures and migration tooling.
Eve owns skill text, prompts, allowed tools, and per-workflow model selection. The app records inputs, checks access, validates evidence, saves results, and exposes clinician actions. Standard drafts get a verified workspace. Clinical extraction gets an app-built packet and zero model-visible tools.
Files SDK provides private storage and staged upload support. OncoBrain still owns document authorization, metadata, immutable versions, hashes, lifecycle, and provenance. Use the managed-document file factory rather than creating another object-store path. Eve reads a manifest-verified local copy only for the task and never treats it as durable storage.
LiteParse makes a useful derived view while preserving the original. Cache derived data by source identity. A parsing failure produces a warning; it must not erase a source or prevent every draft.
AI SDK is for narrow structured helpers. Its suggestions and views cannot establish patient truth, evidence, or clinical authority, and it must not become a second general-purpose agent system beside Eve.
Where to look
| Boundary | Starting point |
|---|---|
| Product routes | apps/oncobrain/src/router.tsx, apps/oncobrain/src/routes/, and apps/oncobrain/vite.config.ts |
| Query usage | apps/oncobrain/src/features/library/components/ and apps/oncobrain/src/features/admin/components/ |
| Identity | apps/celld-gateway/src/auth.ts |
| Persistence | apps/oncobrain/src/lib/persistence/, apps/oncobrain/src/lib/db/, and apps/celld-gateway/src/ |
| Eve | apps/eve/agent/ and apps/oncobrain/src/lib/server/eve/ |
| MCP | apps/oncobrain/src/routes/api/mcp.ts and apps/oncobrain/src/lib/server/mcp/ |
| Documents | apps/oncobrain/src/lib/server/documents/managed-document-files.server.ts and the domain file modules |
| LiteParse | apps/oncobrain/src/lib/server/documents/document-preparation.server.ts |
| Inference | packages/inference/, apps/oncobrain/src/lib/server/inference/, and apps/eve/agent/agent.ts |