# cdcgov/recordlinker architecture

> Architecture diagram of the GitHub repository cdcgov/recordlinker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cdcgov/recordlinker
- Repository: https://github.com/cdcgov/recordlinker

## Overview

##### Main Components

a. API Layer
- FastAPI application (evident from the main.py and routes structure)
- Route handlers for algorithms, linking, patients, and seeding
- OpenAPI/Swagger documentation endpoint

b. Core Services
- Record Linking Engine (src/recordlinker/linking)
- Algorithm Service
- MPI (Master Patient Index) Service
- HL7/FHIR Integration Service

c. Data Layer
- Database Services
- Data Models
- Schema Validators

d. External Integrations
- Splunk logging
- Docker containerization
- Kubernetes deployment

**┌─────────────────────────────────────────────────────────┐**
- Client Applications                   │
- ┘
- ↓ HTTP/REST
**┌─────────────────────────────────────────────────────────┐**
- API Gateway                        │
- ┌─────────────┐  ┌──────────┐  ┌────────────────┐     │
- Patient   │  │   Link   │  │   Algorithm    │     │
- Router    │  │  Router  │  │    Router      │     │
- ┘  └──────────┘  └────────────────┘     │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- Service Layer                        │
- ┌─────────────┐  ┌──────────┐  ┌────────────────┐     │
- MPI      │  │  Record  │  │   Algorithm    │     │
- Service    │  │  Linker  │  │    Service     │     │
- ┘  └──────────┘  └────────────────┘     │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- Data Layer                           │
- ┌─────────────┐  ┌──────────┐  ┌────────────────┐     │
- MPI      │  │ Algorithm │  │     FHIR      │     │
- Models    │  │  Models   │  │    Models     │     │
- ┘  └──────────┘  └────────────────┘     │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- Infrastructure Layer                      │
- ┌─────────────┐  ┌──────────┐  ┌────────────────┐     │
- Docker    │  │ Database │  │     Splunk     │     │
- Containers  │  │          │  │    Logging     │     │
- ┘  └──────────┘  └────────────────┘     │
- ┘

##### Important Details to Highlight

a. Integration Points
- HL7/FHIR integration points
- Database connections
- Logging and monitoring touchpoints

b. Key Workflows
- Record linking process flow
- Algorithm configuration flow
- Patient data ingestion flow

##### Deployment View

- Docker container organization
- Kubernetes deployment structure (based on ops/manifests)
- Network boundaries and security zones
- Load balancing and scaling points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        C[Client Applications]
    end

    subgraph API
        API["FastAPI Application"]:::api
        AR["Algorithm Router"]:::api
        LR["Link Router"]:::api
        PR["Patient Router"]:::api
        SR["Seed Router"]:::api
        API --> AR
        API --> LR
        API --> PR
        API --> SR
    end

    subgraph Services
        RLE["Record Linking Engine"]:::service
        AS["Algorithm Service"]:::service
        MPS["MPI Service"]:::service
        FHIR["HL7/FHIR Integration"]:::service
    end

    subgraph Data
        DM["Data Models"]:::data
        SV["Schema Validators"]:::data
        DB["Database"]:::data
    end

    subgraph Infrastructure
        DC["Docker Container"]:::infra
        KD["Kubernetes Deployment"]:::infra
        SL["Splunk Logging"]:::infra
        CF["Configuration Files"]:::infra
    end

    C --> API
    
    AR --> AS
    LR --> RLE
    PR --> MPS
    SR --> DB

    RLE --> DM
    AS --> DB
    MPS --> DB
    FHIR --> DM

    DM --> DB
    SV --> DB

    API --> SL
    RLE --> SL
    
    classDef api fill:#2374ab
    classDef service fill:#47ab6c
    classDef data fill:#f2b705
    classDef infra fill:#808080

    click API "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/main.py"
    click AR "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/routes/algorithm_router.py"
    click LR "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/routes/link_router.py"
    click PR "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/routes/patient_router.py"
    click SR "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/routes/seed_router.py"
    click RLE "https://github.com/CDCgov/RecordLinker/tree/main/src/recordlinker/linking/"
    click AS "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/database/algorithm_service.py"
    click MPS "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/database/mpi_service.py"
    click FHIR "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/hl7/fhir.py"
    click DM "https://github.com/CDCgov/RecordLinker/tree/main/src/recordlinker/models/"
    click SV "https://github.com/CDCgov/RecordLinker/tree/main/src/recordlinker/schemas/"
    click DB "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/database/__init__.py"
    click SL "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/splunk.py"
    click DC "https://github.com/CDCgov/RecordLinker/tree/main/Dockerfile"
    click KD "https://github.com/CDCgov/RecordLinker/blob/main/ops/manifests/record-linkage.yml"
    click CF "https://github.com/CDCgov/RecordLinker/blob/main/src/recordlinker/config.py"
```
