Architecture

System Overview

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│              │     │                  │     │  HAPI FHIR R4    │
│   Next.js    │────▶│  Spring Boot     │────▶│  (port 8092)     │
│  (frontend)  │     │  (port 8091)     │     │  Clinical data   │
│              │     │                  │     └──────────────────┘
└──────────────┘     │                  │     ┌──────────────────┐
                     │                  │────▶│  PostgreSQL 15   │
                     │                  │     │  (port 5433)     │
                     └──────────────────┘     │  Lookup tables   │
                                              └──────────────────┘

The frontend talks exclusively to the Spring Boot backend. The backend routes clinical data operations to the HAPI FHIR server and lookup/reference queries to Postgres.

Data Store Responsibilities

HAPI FHIR Server (Clinical Data)

All clinical records are stored as FHIR R4 resources:

Domain	FHIR Resource
Patients	Patient
Encounters	Encounter
Diagnoses	Condition
Procedures	Procedure
Notes	DocumentReference

PostgreSQL (Lookup & Mapping Data)

Table	Purpose
`users`	Physicians and staff
`icd10_codes`	ICD-10 diagnosis code catalog
`cpt_codes`	CPT procedure code catalog
`fhir_id_mapping`	Bridges frontend Long IDs ↔ FHIR UUIDs

Backend (Spring Boot + Kotlin)

Package Layout

com.ehr.controller — REST controllers
com.ehr.service — Business logic
com.ehr.fhir — FHIR resource mappers (FhirPatientMapper, FhirEncounterMapper, FhirNoteMapper)
com.ehr.model — JPA entities (User, Icd10Code, CptCode, FhirIdMapping)
com.ehr.repository — Spring Data JPA repositories
com.ehr.dto — Request/response DTOs
com.ehr.config — Configuration (FHIR client, CORS)

Key Dependencies

Spring Boot 3.5.0
Kotlin 1.9.25
HAPI FHIR 7.6.0 (base, client, structures-r4)
Spring Data JPA + PostgreSQL driver

Frontend (Next.js + TypeScript)

Pages (App Router)

Route	Purpose
`/`	Home / Dashboard
`/patients/new`	Create patient
`/patients/[id]`	Patient workspace
`/patients/[id]/edit`	Edit patient
`/patients/[id]/encounters/new`	Create encounter
`/patients/[id]/encounters/[encounterId]`	View encounter
`/patients/[id]/encounters/[encounterId]/edit`	Edit encounter

Key Components

AppShell — Main application container
TabBar — Multi-patient tab switcher with search dropdown
PatientWorkspace — Central workspace showing encounters and notes
PatientSidebar — Demographic details sidebar
CodeSearch — ICD-10 / CPT code lookup
LoginScreen — User selection / authentication

State Management (React Context)

AuthContext — Current user session; persists user ID to localStorage
TabContext — Open patient tabs; persists per-user to localStorage

Docker Compose Services

Service	Image	Host Port	Container Port	Database
`postgres`	`postgres:15`	5433	5432	`ehr`, `hapi`
`hapi-fhir`	`hapiproject/hapi:v7.6.0`	8092	8080	`hapi`

Both services share the same Postgres instance. An init script (init-hapi-db.sql) creates the hapi database for the FHIR server on first run.

The backend Spring Boot application runs outside Docker on port 8091.