Architecture Overview
The SMART on FHIR Client is a five-layer Spring Boot application. Each layer has a single responsibility and communicates only with adjacent layers.
System diagram
Epic EHR :443 SMART Client :8080 HAPI FHIR
│ │ │
│ 1. Clinician clicks │ │
│ "Launch App" │ │
│ │ │
│── GET /launch?iss=...&launch= ────►│ │
│ SmartLaunchController │
│ SmartDiscoveryService ──GET /.well─────► │
│ (cache ISS, 10 min TTL) known/smart │
│ PkceHelper (96-byte S256 verifier) │
│ │ │
│◄── 302 /oauth2/authorize? ─────────│ │
│ code_challenge=... │ │
│ │ │
│ 2. Patient/clinician approves │ │
│── GET /callback?code=... ─────────►│ │
│ SmartCallbackController │
│ SmartTokenService ───POST /token────► │
│ SmartContextExtractor │
│ IdTokenValidator │
│ (RS256, iss, aud, nonce, JWKS) │
│◄── 302 /dashboard ─────────────────│ │
│ │ │
│ 3. App makes FHIR requests │ │
│ UiController / PatientDataController │
│ FhirClientFactory │
│ BearerTokenInterceptor │
│ │──GET /fhir/Patient/{id}───────►│
│ │◄─ Patient JSON ────────────────│
│ │──GET /fhir/Condition?patient──►│
│ │◄─ Bundle (Conditions) ─────────│
│ │ │
│ 4. Background token refresh │ │
│ TokenRefreshFilter │
│ (fires 120 s before exp on /api/**) │
│ TokenRefreshService ───POST /token─► │
Five layers
| Layer | Components | Responsibility |
|---|---|---|
| 5 — UI / API | UiController, PatientDataController, Thymeleaf templates | Render views and return JSON |
| 4 — Business Logic | SmartLaunchController, SmartCallbackController, SmartTokenService, SmartContextExtractor, IdTokenValidator | SMART handshake, token exchange, OIDC validation |
| 3 — Security | SecurityConfig, SmartSecurityFilter, TokenRefreshFilter, PkceHelper | Filter chain, CSRF, PKCE, proactive refresh |
| 2 — FHIR Client | FhirClientFactory, BearerTokenInterceptor | HAPI R4 client per ISS |
| 1 — Session State | SmartLaunchContext, SmartLaunchSession, PkceParameters, UserProfile | Typed, serializable session objects |
Request lifecycle
Every EHR launch follows this exact 4-phase sequence:
Phase 1 — Launch (GET /launch?iss=...&launch=...)
SmartLaunchController receives iss (the FHIR server URL) and launch (Epic's opaque context token). It calls SmartDiscoveryService.discover(iss) to fetch /.well-known/smart-configuration (cached per ISS for 10 minutes in Caffeine), generates a 96-byte PKCE code verifier with S256 challenge, stores PkceParameters in the HTTP session, and issues a 302 redirect to Epic's authorization endpoint.
Phase 2 — Callback (GET /callback?code=...&state=...)
SmartCallbackController validates the CSRF state in constant time, exchanges the authorization code for tokens via SmartTokenService.exchangeCode(), validates the id_token RS256 signature and claims via IdTokenValidator, extracts SmartLaunchContext including patient ID, encounter ID, and needPatientBanner flag via SmartContextExtractor, and stores the context in the HTTP session. 302 redirect to /dashboard.
Phase 3 — FHIR requests
FhirClientFactory.forContext(ctx) returns a HAPI IGenericClient configured with a BearerTokenInterceptor carrying the current access token and pointing at the patient's FHIR server. Every controller endpoint uses this client to make typed FHIR calls.
Phase 4 — Token refresh
TokenRefreshFilter intercepts every /api/** request. TokenRefreshService.refreshIfNeeded() checks the remaining token lifetime and triggers a proactive refresh if less than 120 seconds remain. This runs before the controller method executes, so FHIR calls always use a valid token.
Next: Package Structure →