Skip to main content

Architecture overview

The platform is a universal, multi-tenant healthcare/EHR operating foundation — Java 21, Spring Boot 3.5.6 — designed as an OpenMRS-style platform: small deployments activate fewer engines, large ones activate more, but the data model, API shape, and boundaries stay stable.

Engines coupled in core; domain modules decoupled via Feign​

  • core is the platform. The platform engines — metadata, tenant, facility, module, platform-config, demographic, identity-access, access-control, concept, form, clinical, program, workflow, queue, billing, notification — live as packages inside core (com.alienworkspace.ehr.api.core.engines.<engine>). They are tightly coupled: they call each other in-process (direct service calls, full ACID), share one database, and ship as one deployable serving one merged Swagger UI. core owns the platform's business tables.
  • common (cross-cutting infra: audit/soft-delete base classes, security, crypto, utils) and exchange (public contracts: DTOs + Feign client interfaces) are standalone modules importable by anything. exchange must never depend on core.
  • Future domain modules (e.g. publichealth, pharmacy, lab) are separate Maven modules that import only common + exchange and call the platform only via Feign (exchange.client.*) — so they can be extracted to microservices later without changing their callers. Feign is for the domain-module boundary only, never between engines.

Cross-cutting rules every engine follows​

  • Audit & soft delete are foundational. Business entities extend common.audit.AuditTrail (audit columns + voided flag + generated uuid) with @SQLRestriction("voided = false") hiding soft-deleted rows; soft delete uses one vocabulary: markAsVoid(String reason).
  • UUID primary keys for business/transactional entities (globally unique across distributed/ offline nodes); stable centrally-seeded reference data (country/state/…) may use numeric keys.
  • JSONB discipline: JSONB is for flexible config/schemas/payloads; core relational fields (identifiers, names, dates, status, FKs, concept ids, financial totals) never live only in JSONB.
  • Logical cross-engine references: an engine references another engine's rows by id — no foreign key across engines — so engines stay independently extractable.
  • Object-level access control: patient/person/clinical reads filter by access scope server-side; the unified access decision combines local roles/scopes + identity-access visibility/consent/grants
    • feature flags + optional OPA.

Where to go next​

Authoritative source: core/CORE_PLAN.md and the per-milestone core/MILESTONE*.md notes, being migrated into these pages.