⚠️ NOT FOR CLINICAL USE. Asclepius is a reference implementation that demonstrates the architecture of a FHIR-native clinical data platform. It is not HIPAA-certified, not a regulated medical device, and its drug-interaction knowledge base is intentionally incomplete. Do not store, process, or base clinical decisions on real patient data with this software. See the regulatory disclaimer below.
A from-scratch, layered implementation of the pillars of a clinical data platform, built to be correct and testable rather than feature-complete. Every architectural choice is documented with first-principles reasoning and an honest "better tool for production" callout in Architecture Decision Records.
This is a partial implementation — the foundation is real and tested; most pillars are planned. The status column is the source of truth for what exists today.
| Pillar | Implementation | Status |
|---|---|---|
| FHIR R4 resource model | Hand-authored zod schemas (single source of truth → inferred TS types); 9 resources, primitives, datatypes, Bundle, OperationOutcome | ✅ Built |
| Storage | ResourceRepository port + in-memory versioned adapter (immutable snapshots, history, soft delete) |
✅ Built |
| Storage (persistent) | SQLite adapter via better-sqlite3 |
🚧 Planned (ADR 0004) |
| FHIR search | Hand-built query-plan compiler (param types, modifiers, prefixes) + executor (path extraction, per-type matching, reference chaining, _sort/_count/_page) |
✅ Built |
| REST API | Hono HTTP adapter: create/read/vread/update(+create-on-update)/delete, ETag/Location/versioning, instance + type history Bundles, search (GET ?params + POST _search → searchset Bundle, incl. reference chaining + self/next/prev pagination links), OperationOutcome errors | ✅ Built (ADR 0005) |
| Validation | zod runtime validation against authored FHIR profiles | 🚧 Planned |
| Clinical Decision Support | Composable rule DSL → CDS Hooks "cards" | 🚧 Planned (ADR 0007) |
| Drug–drug interactions | Structured JSON knowledge base + graph-aware checker (severity + mechanism) | 🚧 Planned |
| AuthN/AuthZ | JWT (HS256, jose) + SMART-style scope middleware (system/Patient.read, user/*.write); dev-only /auth/token issuer (prod-disabled). Patient-compartment filtering + role-based overrides deferred |
✅ Built (ADR 0008) |
| Audit | Hash-chained, append-only, tamper-evident log | 🚧 Planned (ADR 0009) |
┌─────────────────────── HTTP / CLI (entry) ────────────────────────┐
│ adapter/http · adapter/auth · adapter/audit │
└───────────────────────────────┼───────────────────────────────────┘
│ depends on ports only
┌───────────────────────────────▼───────────────────────────────────┐
│ service: search · validation · cds · ddi (application logic) │
└───────────────────────────────┼───────────────────────────────────┘
│ depends on domain only
┌───────────────────────────────▼───────────────────────────────────┐
│ domain: fhir resources · value objects · OperationOutcome │
└───────────────────────────────┼───────────────────────────────────┘
│ port interfaces
┌───────────────────────────────▼───────────────────────────────────┐
│ adapter/storage: in-memory · sqlite (port implementations) │
└───────────────────────────────────────────────────────────────────┘
Target architecture — see the Status table above for what is implemented today (e.g. SQLite/HTTP/auth/audit adapters are not yet built).
Dependencies point inward: domain depends on nothing; service depends on
domain + port; adapters depend on port + domain. src/app.ts is the
single composition root that wires adapters to services.
Requires Node.js ≥ 22 (see .nvmrc for the dev version).
npm install # dependencies (builds better-sqlite3's native module)
npm run dev # run via tsx (no compile step), hot reload
npm test # run the test suite
npm run gate # format:check → lint → typecheck → test → buildThe project is configured for max-strict TypeScript (strict,
noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax).
A change is not done until npm run gate is green.
Every component choice is documented with its first-principles rationale and an
honest "better tool for production" callout in docs/adr/. Summary:
- TypeScript — models FHIR's structural types; compiler verifies shape. Production FHIR servers: Java (HAPI) or .NET (Firely).
- zod — single source of truth for types + runtime validation. Full FHIR profiling: Firely validator.
- In-memory + SQLite — zero-config real persistence + fast tests. Scale: Postgres + JSONB/GIN.
- Hono — web-standard, portable, fast. Larger ecosystem: Fastify.
- Hand-built search — the hard core; no library does FHIR search correctly. Scale: Elasticsearch.
- CDS rule DSL — testable pure functions. Production: CQL.
- JWT + scopes — models FHIR's resource/action access. Production: full SMART-on-FHIR OAuth2 via a real IdP.
See docs/adr/ for the full reasoning on each.
Contributions are welcome. Please read CONTRIBUTING.md
(the npm run gate requirement, code style, and the ADR-first decision process)
before opening a pull request. For security issues, see SECURITY.md
— do not file vulnerabilities as public issues.
Asclepius is a reference / educational implementation. It is not a certified medical device, is not HIPAA- or HITRUST-compliant, and carries no warranty of fitness for any clinical purpose. The DDI knowledge base is intentionally incomplete; missing interaction data is a patient-safety hazard. Never connect this software to real clinical systems, pharmacies, or EHRs, or use it to store or make decisions about real patient data.
Licensed under the Apache License, Version 2.0. See LICENSE and
NOTICE.md. Unless required by applicable law or agreed to in
writing, software distributed under the License is distributed on an "AS IS"
BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied.