# naveenraj-g/fhir-server architecture

> Architecture diagram of the GitHub repository naveenraj-g/fhir-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naveenraj-g/fhir-server
- Repository: https://github.com/naveenraj-g/fhir-server

## Overview

This is a FastAPI FHIR R4 healthcare API. A client sends an authenticated resource request; the router resolves dependencies, invokes resource services and repositories, and returns either FHIR or plain JSON. Coverage excerpts show that path directly, while README documentation establishes broader resource support, JWT permissions, tenant scoping, Redis-backed middleware, terminology, vitals, and health probes. Several broader branches are documented but their implementation wiring was not sampled, so those links are marked unverified.

Main entry points: [`app/main.py`](https://github.com/naveenraj-g/fhir-server/blob/main/app/main.py) (Application entry), [`app/routers/coverage.py`](https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/coverage.py) (Resource routes), [`app/services/coverage_service.py`](https://github.com/naveenraj-g/fhir-server/blob/main/app/services/coverage_service.py) (Coverage service), [`app/repository/coverage_repository.py`](https://github.com/naveenraj-g/fhir-server/blob/main/app/repository/coverage_repository.py) (Coverage repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Application entry<br/>[main.py]"]
  node_auth["JWT authorization<br/>[dependencies.py]"]
  node_router["Resource routes<br/>[coverage.py]"]
  node_schemas["Input schemas<br/>[input.py]"]
  node_negotiation["Format negotiation"]
end

subgraph group_domain["FHIR resource workflow"]
  node_service["Coverage service"]
  node_repository["Coverage repository"]
  node_models["FHIR resource models<br/>[coverage.py]"]
  node_mapper["FHIR/plain mappers<br/>[__init__.py]"]
end

subgraph group_platform["Runtime platform"]
  node_postgres[("PostgreSQL")]
  node_database["Async database layer<br/>[database.py]"]
  node_redis["Redis sessions and limits<br/>[redis.py]"]
  node_middleware["Request middleware<br/>[request_context.py]"]
end

subgraph group_capabilities["Additional capabilities"]
  node_terminology["Terminology API<br/>[terminology.py]"]
  node_vitals["Vitals API<br/>[vitals.py]"]
  node_health["Health probes<br/>[main.py]"]
end

node_client(("API client"))
node_fhir_client(("FHIR client"))

node_client -.->|"sends request"| node_app
node_app -->|"requires JWT"| node_auth
node_app -->|"mounts routes"| node_router
node_router -->|"validates input"| node_schemas
node_router -->|"invokes"| node_service
node_service -->|"delegates CRUD"| node_repository
node_repository -->|"queries and writes"| node_models
node_repository -.->|"uses sessions"| node_database
node_database -->|"stores records"| node_postgres
node_service -->|"maps resources"| node_mapper
node_router -->|"formats response"| node_negotiation
node_app -.->|"configures middleware"| node_middleware
node_middleware -.->|"uses Redis"| node_redis
node_app -->|"mounts capability"| node_terminology
node_app -->|"mounts capability"| node_vitals
node_app -->|"serves probes"| node_health
node_fhir_client -.->|"requests resources"| node_router

click node_app "https://github.com/naveenraj-g/fhir-server/blob/main/app/main.py"
click node_auth "https://github.com/naveenraj-g/fhir-server/blob/main/app/auth/dependencies.py"
click node_router "https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/coverage.py"
click node_schemas "https://github.com/naveenraj-g/fhir-server/blob/main/app/schemas/coverage/input.py"
click node_negotiation "https://github.com/naveenraj-g/fhir-server/blob/main/app/core/content_negotiation.py"
click node_service "https://github.com/naveenraj-g/fhir-server/blob/main/app/services/coverage_service.py"
click node_repository "https://github.com/naveenraj-g/fhir-server/blob/main/app/repository/coverage_repository.py"
click node_models "https://github.com/naveenraj-g/fhir-server/blob/main/app/models/coverage/coverage.py"
click node_mapper "https://github.com/naveenraj-g/fhir-server/blob/main/app/fhir/mappers/coverage/__init__.py"
click node_database "https://github.com/naveenraj-g/fhir-server/blob/main/app/core/database.py"
click node_redis "https://github.com/naveenraj-g/fhir-server/blob/main/app/core/redis.py"
click node_middleware "https://github.com/naveenraj-g/fhir-server/blob/main/app/middleware/request_context.py"
click node_terminology "https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/terminology.py"
click node_vitals "https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/vitals.py"
click node_health "https://github.com/naveenraj-g/fhir-server/blob/main/app/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_auth,node_router,node_schemas,node_negotiation,node_client,node_fhir_client toneBlue
class node_service,node_repository,node_models,node_mapper toneAmber
class node_postgres,node_database,node_redis,node_middleware toneMint
class node_terminology,node_vitals,node_health toneRose
```

## Components

### API and access

- [Application entry](https://github.com/naveenraj-g/fhir-server/blob/main/app/main.py): `app/main.py`
- [JWT authorization](https://github.com/naveenraj-g/fhir-server/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`
- [Resource routes](https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/coverage.py): `app/routers/coverage.py`
- [Input schemas](https://github.com/naveenraj-g/fhir-server/blob/main/app/schemas/coverage/input.py): `app/schemas/coverage/input.py`
- [Format negotiation](https://github.com/naveenraj-g/fhir-server/blob/main/app/core/content_negotiation.py): `app/core/content_negotiation.py`

### FHIR resource workflow

- [Coverage service](https://github.com/naveenraj-g/fhir-server/blob/main/app/services/coverage_service.py): `app/services/coverage_service.py`
- [Coverage repository](https://github.com/naveenraj-g/fhir-server/blob/main/app/repository/coverage_repository.py): `app/repository/coverage_repository.py`
- [FHIR resource models](https://github.com/naveenraj-g/fhir-server/blob/main/app/models/coverage/coverage.py): `app/models/coverage/coverage.py`
- [FHIR/plain mappers](https://github.com/naveenraj-g/fhir-server/blob/main/app/fhir/mappers/coverage/__init__.py): `app/fhir/mappers/coverage/__init__.py`

### Runtime platform

- **PostgreSQL**
- [Async database layer](https://github.com/naveenraj-g/fhir-server/blob/main/app/core/database.py): `app/core/database.py`
- [Redis sessions and limits](https://github.com/naveenraj-g/fhir-server/blob/main/app/core/redis.py): `app/core/redis.py`
- [Request middleware](https://github.com/naveenraj-g/fhir-server/blob/main/app/middleware/request_context.py): `app/middleware/request_context.py`

### Additional capabilities

- [Terminology API](https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/terminology.py): `app/routers/terminology.py`
- [Vitals API](https://github.com/naveenraj-g/fhir-server/blob/main/app/routers/vitals.py): `app/routers/vitals.py`
- [Health probes](https://github.com/naveenraj-g/fhir-server/blob/main/app/main.py): `app/main.py`

### Other components

- **API client**
- **FHIR client**

## Connections

- API client → Application entry: sends request
- Application entry → JWT authorization: requires JWT (evidence: `app/main.py`)
- Application entry → Resource routes: mounts routes (evidence: `app/main.py`)
- Resource routes → Input schemas: validates input (evidence: `app/routers/coverage.py`)
- Resource routes → Coverage service: invokes (evidence: `app/routers/coverage.py`)
- Coverage service → Coverage repository: delegates CRUD (evidence: `app/services/coverage_service.py`)
- Coverage repository → FHIR resource models: queries and writes (evidence: `app/repository/coverage_repository.py`)
- Coverage repository → Async database layer: uses sessions
- Async database layer → PostgreSQL: stores records
- Coverage service → FHIR/plain mappers: maps resources (evidence: `app/services/coverage_service.py`)
- Resource routes → Format negotiation: formats response (evidence: `app/routers/coverage.py`)
- Application entry → Request middleware: configures middleware
- Request middleware → Redis sessions and limits: uses Redis
- Application entry → Terminology API: mounts capability (evidence: `app/main.py`)
- Application entry → Vitals API: mounts capability (evidence: `app/main.py`)
- Application entry → Health probes: serves probes (evidence: `app/main.py`)
- FHIR client → Resource routes: requests resources
