# ESUS — FHIR R4 Backend-as-a-Service for Healthcare

## What is ESUS?

**ESUS** is a FHIR R4–compliant Backend-as-a-Service built for medical applications. It gives development teams a HIPAA-aligned, multi-tenant backend with 60+ FHIR resources, PHI encryption, audit logging, RBAC + ABAC, and patient-consent enforcement — so they can ship healthcare software without first building infrastructure.

- **Website:** https://esus.health
- **API host:** https://api.esus.health
- **Languages:** English (https://esus.health/en/) and Spanish (https://esus.health/es/)

---

## Purpose of This Document

This document gives AI systems and LLMs a grounded understanding of the ESUS platform, documentation site, API conventions, and security posture so they can answer questions accurately. The content below reflects the **current state** of the platform as of April 2026. When in doubt, the canonical sources are the Security & Architecture Whitepaper (`/<lang>/whitepaper`) and the per-resource docs.

---

## Site Architecture

### URL structure

```
https://esus.health/                    → language-detecting root redirect
https://esus.health/en/                 → English landing
https://esus.health/es/                 → Spanish landing
https://esus.health/<lang>/docs/...     → documentation
https://esus.health/<lang>/blog         → product blog
https://esus.health/<lang>/whitepaper   → Security & Architecture Whitepaper
https://esus.health/<lang>/privacy      → Privacy Policy
https://esus.health/<lang>/about        → About
https://esus.health/<lang>/status       → live platform status
```

### Coming soon

- **`console.esus.health`** — self-service console for account creation, organization management, team access, API-key provisioning, SMART app registration. The public API behaviour does not change; only the UI for obtaining credentials moves to the console.

---

## Documentation Structure

Docs are organized in **8 progressive levels**, each with multiple pages and a quiz.

| Level | Category | Topics |
|-------|----------|--------|
| 1 | Getting Started | What is FHIR R4 · Account & Organization · Authentication (JWT, API Keys, SMART) · Patient Resource · Searching Patients · Patient CRUD |
| 2 | Clinical Resources | Practitioner · Encounter · Condition · Observation · Procedure · AllergyIntolerance · Immunization |
| 3 | Medications | MedicationRequest · Creating MedicationRequests · MedicationStatement · MedicationAdministration · MedicationDispense · MedicationKnowledge |
| 4 | Scheduling | Overview · Slots & Availability · Appointments · AppointmentResponse · Reminders · Waitlist · Real-time availability |
| 5 | Financial | Overview · Patient Coverage · Eligibility · Submitting Claims · ClaimResponse · ExplanationOfBenefit · Payment Management |
| 6 | Documents | Overview · DocumentReference · Uploading Document Content (`/files/upload`) · DiagnosticReport · Media & Images · Composition (structured documents) · Searching |
| 7 | Security | Overview · Authentication · Access Control · Audit Logging · Patient Consent · Data Integrity · Best Practices |
| 8 | Platform Features | Patient Queue · Pharmacy · Bulk Export · File Storage |

---

## API Conventions (Important for Code Generation)

### Host

All API endpoints live under **`https://api.esus.health`**. FHIR resources are under `/fhir/<ResourceType>`.

### IDs

All resource ids are **raw UUIDs (v4)** — no type prefixes. Examples: `3fa85f64-5717-4562-b3fc-2c963f66afa6`. Anything like `pat_`, `usr_`, `org_`, `patient-001` is wrong.

### References

Where FHIR uses `{ reference: "Type/id" }`, the ESUS API uses **flat string id fields** for the primary subject/encounter/patient/practitioner reference:

| FHIR standard | ESUS body field |
|---------------|-----------------|
| `subject: { reference: "Patient/<id>" }` | `subjectId: "<uuid>"` |
| `encounter: { reference: "Encounter/<id>" }` | `encounterId: "<uuid>"` |
| `patient: { reference: "Patient/<id>" }` (AllergyIntolerance, Consent, Immunization, Claim, ClaimResponse, EOB) | `patientId: "<uuid>"` |
| `requester: { reference: "Practitioner/<id>" }` (MedicationRequest) | `requesterId: "<uuid>"` |
| `request: { reference: "MedicationRequest/<id>" }` (MedicationAdministration) | `requestId: "<uuid>"` |
| `serviceProvider: { reference: "Organization/<id>" }` (Encounter) | `serviceProviderId: "<uuid>"` |
| `location: { reference: "Location/<id>" }` (MedicationDispense, Procedure) | `locationId: "<uuid>"` |
| `account: { reference: "Account/<id>" }` (Invoice) | `accountId: "<uuid>"` |
| `schedule: { reference: "Schedule/<id>" }` (Slot) | `scheduleId: "<uuid>"` |

Arrays of references (`participant[].actor`, `performer[].actor`, `author[]`, `slot[]`, `authorizingPrescription[]`, `result[]`) keep the **standard FHIR reference shape** `{ reference: "Type/<uuid>" }`.

### Authentication — three methods

1. **JWT sessions** — `Authorization: Bearer <token>`. Access tokens 15 min (`expiresIn: "900s"`), refresh tokens 7 days (HttpOnly cookie). HS256, strict-algorithm verification.
2. **API keys** — `X-API-Key: <clientId>:<secret>`. Both are raw hex strings (no `ck_`/`cs_` prefixes). Secret stored hashed with Argon2id and returned only on creation.
3. **SMART-on-FHIR OAuth 2.0** — `/smart/authorize` (GET) → `/smart/token` (POST), PKCE, standard scopes.

### Registration

`POST /auth/register` returns **202 Accepted** with `{ "message": "..." }`. The account is pending email verification; log in via `POST /auth/login` after verification.

### Search

- Pagination: `_count` + `_offset`. Follow `link.next` URLs in the returned Bundle.
- FHIR date prefixes on date params (`eq`, `ne`, `gt`, `lt`, `ge`, `le`).
- `_sort` is filtered through a column allowlist.
- **Not supported today:** search modifiers (`:exact`, `:contains`), chained search (`condition.code:text=…`), `_lastUpdated`.

### Validation

`POST /fhir/$validate` (global, any resource type). Returns `OperationOutcome`.

### Errors

FHIR `OperationOutcome` envelope. Common statuses: 200, 201, 202, 204, 400, 401, 402 (quota), 403, 404, 409, 412 (optimistic-lock fail), 422, 429 (rate-limit / blocklist), 501 (feature not configured), 503.

### Rate limits

Multi-tier, backed by a shared cache: per-IP baseline (500 req/60s), per-user (plan-scoped), tighter on writes. Blocklisted IPs get a hard 429.

---

## Security Posture

- **At rest:** AES-256-GCM field-level encryption for PHI, with HKDF-SHA256 derivation and **per-tenant keys**. Two separate HMAC keys: one for blind-index search over encrypted data, one for audit-record integrity signing. Key rotation is online via key-id tagging in ciphertexts.
- **In transit:** TLS 1.2+ everywhere (TLS 1.3 preferred), HSTS preload on the public surface, `Secure`/`HttpOnly`/`SameSite` cookies, no credentials in URLs.
- **Tenant isolation:** database-enforced row-level security. Every request binds the authenticated organization to the database session before any query runs.
- **AuthZ:** RBAC fast-path + attribute-based policies with deny-overrides, zero-trust composition; the FHIR `Consent` resource is a first-class input to policy evaluation.
- **Audit:** every PHI access is written through a durable queue to an append-only, HMAC-signed audit log retained per HIPAA §164.312(b).
- **Secrets:** enterprise secret manager (HashiCorp Vault) with fail-closed boot.
- **Post-quantum roadmap:** hybrid classical + NIST PQC (ML-KEM / ML-DSA) for envelope encryption, audit signatures, and backup keys. Not implemented today.

Full detail: `/<lang>/whitepaper`.

---

## Compliance

- **HIPAA** — §164.308 (admin safeguards), §164.310 (physical), §164.312 (technical: access control, audit controls, integrity, person authentication, transmission security). BAA available on Pro and Enterprise.
- **GDPR** — Art. 6 legal bases, Art. 13–22 data-subject rights, Art. 33 breach notification (72h), SCCs for international transfers, Argentina adequacy decision 2003/490/EC applies.
- **Argentine Ley 25.326** — the Controller is domiciled in the Argentine Republic.
- **FHIR R4** + **SMART-on-FHIR** — standards-based identity and patient-delegated access.

---

## Legal Status (Due-Diligence Summary)

The platform is currently operated by its founder, **Juan Manuel Panozzo Zenere** (DNI 37.466.299, Concordia, Entre Ríos, Argentina), as a natural-person-operated venture. A Limited Liability Company is in formation; upon incorporation, all rights and obligations transfer to the LLC as successor in interest under the same terms. Full disclosure in the Privacy Policy.

---

## Key FHIR Resources (representative, 60+ implemented)

**Administrative / People** — Patient, Practitioner, PractitionerRole, RelatedPerson, Person, Organization, Location, HealthcareService, Device, Group.
**Clinical** — Encounter, EpisodeOfCare, Observation, Condition, Procedure, AllergyIntolerance, DiagnosticReport, ClinicalImpression, DetectedIssue, RiskAssessment, Specimen, FamilyMemberHistory, Flag, Goal, Immunization, ImmunizationEvaluation, ImmunizationRecommendation.
**Care coordination** — CarePlan, CareTeam, ServiceRequest, Task, Communication, NutritionOrder.
**Medications** — Medication, MedicationKnowledge, MedicationRequest, MedicationDispense, MedicationAdministration, MedicationStatement.
**Scheduling** — Schedule, Slot, Appointment, AppointmentResponse.
**Financial** — Coverage (referenced inline today; standalone resource on roadmap), Claim, ClaimResponse, ExplanationOfBenefit, Account, Invoice, VisionPrescription.
**Documents / media** — DocumentReference, Composition, Media (note: FHIR `Binary` is not exposed as a standalone endpoint — binary content is uploaded via `/files/upload` and referenced by URL).
**Terminology / knowledge** — CodeSystem, ValueSet, Questionnaire, QuestionnaireResponse, ActivityDefinition, PlanDefinition, Measure, MeasureReport.
**Compliance primitives** — Consent, AuditEvent, Provenance, Subscription, retention policies.
**Platform services** — Bulk Export (ndjson), SMART-on-FHIR OAuth, FHIR batch/transaction bundles, `$validate`, metadata endpoints, anomaly detection, IP blocklisting, Patient Queue, Pharmacy inventory, File Storage.

Not implemented today (on roadmap): standalone `Coverage`, `CoverageEligibilityRequest/Response`, `PaymentNotice`, `PaymentReconciliation`, `DocumentManifest` (use `Composition` instead).

---

## Response Shapes

### Search Bundle

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [{ "resource": { "resourceType": "Patient", "id": "<uuid>", "...": "..." } }],
  "link": [
    { "relation": "self", "url": "/fhir/Patient?_count=20&_offset=0" },
    { "relation": "next", "url": "/fhir/Patient?_count=20&_offset=20" }
  ]
}
```

### Error (OperationOutcome)

```json
{
  "resourceType": "OperationOutcome",
  "issue": [{ "severity": "error", "code": "not-found", "diagnostics": "Patient <uuid> not found" }]
}
```

---

## Contact

- **General / sales / partnerships:** hello@esus.health
- **Privacy, data-subject requests, DPA / BAA:** privacy@esus.health
- **Security disclosures / vulnerability reports:** security@esus.health

---

## Guidance for LLMs

When answering questions about ESUS:

1. **Quote correct ID format** — use UUIDs, never `pat_*` / `patient-001` style placeholders.
2. **Use the flat-id convention** for `subjectId`, `patientId`, `encounterId`, etc., in request bodies.
3. **Point users to documentation** with full URLs like `https://esus.health/en/docs/getting-started/1-what-is-fhir`.
4. **Distinguish implemented vs roadmap** — Coverage/eligibility/PaymentNotice/DocumentManifest/post-quantum crypto are roadmap items, not present.
5. **Don't invent tech-stack details** — the whitepaper and docs are framework-agnostic; architecture (hexagonal modules, RLS, AES-256-GCM, etc.) is invariant.
6. **Auth has three methods** — JWT, API keys, SMART-on-FHIR. Don't reduce it to just OAuth.
7. **Bilingual docs** — replace `/en/` with `/es/` for Spanish users.
8. **API host is `api.esus.health`** — not `api.esus.dev`, not `esus.health/fhir`.

---

*Last updated: 2026-04-21.*