Architecture
OncoBrain is the product where clinicians review sources, maintain a patient chart, and decide what becomes part of care. The application checks access, stores the record, captures the exact inputs for each AI request, verifies citations, and presents review actions. The AI service, Eve, can produce a draft from those inputs. It cannot read the chart database or take clinical actions.
Three services work together: the app, a Celld gateway that stores records and tracks background work, and Eve, which executes the AI tasks accepted by the app. The optional monitoring service, OpenObserve, stores technical diagnostics separately from the clinical and audit records.
Celld's bucket preserves database and runtime state. The separate Files store holds immutable documents. Eve reads a verified local copy of permitted files and has no direct database or object-store access. Explore the diagram.
The browser never connects to Eve directly. The app's same-origin proxy removes prompts, hidden reasoning, raw tool payloads, authorization details, and model identity from Eve events. It can still show allowed draft text and source-derived citations.
Why Celld
A cell combines application code with its own SQLite database. Celld replicates that database to object storage and supplies durable workflows, queues, and timers through the same runtime. This removes much of the service wiring a conventional database, Redis, and workflow stack would need. Why Celld introduces the model, its scaling boundary, and the parts OncoBrain uses.
User journeys
The main paths are case preparation, review of clinical options, referral assessment or summary export, and Copilot questions. Each starts with a clinician's task and ends in its own saved result. User journeys maps the steps and review points.
What is saved
The fixed OrganizationCell("primary") stores the relational record through Drizzle; Celld replicates its database history to the fleet bucket. Files SDK stores immutable source, managed-document, workspace, and export bytes in a separate S3-compatible store with separate credentials. Prepared local files are verified caches that can be recreated.
A patient can have many cases. Each case connects original sources, confirmed chart versions, encounters, drafts, and clinician decisions. Domain relationships shows these records and the links from each result to its producing run and evidence.
How a draft gets its inputs
Before an AI task starts, the app checks the actor's organization and case access, then records an immutable input list for that run. Standard drafts and Copilot receive a read-only workspace that names the permitted patient sources, shared guidance and trials, licensed release members, prior artifacts, and the relevant confirmed patient state. A workflow can explicitly allow no confirmed state. A later upload or confirmation appears only in a later run.
Clinical extraction is the deliberate exception. The app puts an app-built packet, its source-version metadata, and any observed state identity in the message. It does not materialize a workspace. Extraction has zero model-visible tools, so it cannot browse, use files, delegate, or access the database. It returns structured findings, source references, unresolved items, and warnings. Parsing trouble must not discard the original or prevent a useful partial review.
For standard runs, search helps locate material but is never evidence. An exact workspace or internal-evidence read is checked by the app and can create an evidence receipt with its passage, locator, digest, and source version. Internal product-label evidence comes from ETL-owned LanceDB tables. The app pins an exact native table version for a read, but the original full source remains reopenable only while ETL retains that version.
Review remains a clinician action
An extraction result is a draft until a clinician reviews it. Add and confirm appends the selected findings to the chart and can confirm the resulting patient-state version in the same transaction. Confirmation rechecks the review and chart revisions before saving an immutable snapshot. Direct clinician edits also save a confirmed snapshot; Confirm changes handles any remaining unconfirmed chart revisions. An AI draft, source upload, search result, or cache entry does not establish patient truth.
The same boundary applies elsewhere. Treatment drafts, referral assessments, trial matches, exports, and FHIR output are advisory and review-bound. A marked-reviewed artifact is not a signature, order, prescription, enrollment, EHR write, or referral transmission. FHIR R4 is generate-only and domain code does not import FHIR types.
Documents, plans, and imports
Files SDK handles private storage, staged uploads, and file validation. OncoBrain controls document access, metadata, immutable versions, hashes, lifecycle, and clinical meaning. Managed document policies decide whether each kind can be previewed, downloaded, replaced as a new version, archived, restored, or inspected in history. Permanent purge is unavailable for confirmed material.
Treatment has one source of truth: the saved Markdown artifact. Comparison and Flowchart are derived views with their own settlement state. A clinician must review the current basis before choosing a plan; the choice freezes one option and schedule, while later matrix edits append plan versions. A failed projection never changes the saved prose or becomes a new evidence source.
Connected-EHR import stores selected original records byte-for-byte after access and identity checks. A foreign identifier rejects the preparation; mixed known and new identifiers require clinician confirmation. HIE import is separate and requires reviewed legal demographics plus explicit identity and treatment-relationship attestations. It never guesses or auto-links a patient. Both import paths create patient sources, not chart facts or EHR writes.
Who may do what
| Membership | Clinical decisions | Workflow operations | Copilot | Library | Referral disposition |
|---|---|---|---|---|---|
clinician | Yes | All admitted workflows | Yes | Read; manage with global admin | Yes |
library_manager | Yes | All admitted workflows | Yes | Read and manage | Yes |
care_coordinator | No | referral-readiness only | No | Patient-source pages; global admin may add management | Yes |
The global admin role can add same-organization document-management authority. It never grants chart confirmation, plan selection, artifact review, export, EHR confirmation, Copilot, or extra workflows. The same membership gate applies to browser, MCP, and evaluation entry points.
External agents use the OAuth-protected app endpoint at /api/mcp, never Eve. They can read permitted case context and documents and start, wait for, or cancel retry-safe advisory work. They cannot take clinical decision actions. See Agent-native MCP.
Where to look
apps/oncobrain/src/routes/ TanStack product and API routes
apps/oncobrain/src/lib/server/ authenticated orchestration
apps/oncobrain/src/lib/db/ Cell-owned Drizzle schema and persistence
apps/oncobrain/src/lib/persistence/ capability-oriented persistence contracts
apps/oncobrain/server/routes/ Nitro service and health endpoints
apps/eve/agent/ skills, tools, channel, and AI execution
apps/celld-gateway/src/ private Worker, primary Cell, and native workflow
packages/prepared-files/ workspace-manifest and cache primitives- admission and workspace:
apps/oncobrain/src/lib/server/cases/case-workflow.server.ts,apps/oncobrain/src/lib/server/cases/workflow-authorization.server.ts, andapps/oncobrain/src/lib/server/cases/run-workspace.server.ts - extraction and confirmation:
apps/oncobrain/src/lib/server/clinical-extraction/,apps/oncobrain/src/lib/db/sqlite-clinical-extraction.ts, andapps/oncobrain/src/lib/db/schema/patient-state.ts - evidence and safe streaming:
apps/oncobrain/src/lib/server/evidence/andapps/oncobrain/src/lib/server/eve/eve-stream-proxy.server.ts - documents and plans:
apps/oncobrain/src/lib/server/documents/,apps/oncobrain/src/lib/server/treatment/, andapps/oncobrain/src/lib/db/schema/artifacts.ts - Cell and gateway:
apps/celld-gateway/src/persistence-command-handler.tsandapps/oncobrain/src/lib/db/application-persistence-service.ts
Next: follow an Eve workflow.