# cmsgov/bcda-app architecture

> Architecture diagram of the GitHub repository cmsgov/bcda-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cmsgov/bcda-app
- Repository: https://github.com/cmsgov/bcda-app

## Overview

##### Main Components

a) API Layer Components:
- BCDA API Service (main API application)
- BCDA Worker Service (background job processor)
- SSAS (Security/Authentication Service)
- API Gateway/Router

b) Data Storage:
- PostgreSQL Database (primary data store)
- S3 Storage (for CCLF files and suppressions)

c) External Services:
- Blue Button API Integration
- AWS Services Integration

##### Key Architectural Elements

a) Service Boundaries:
- Authentication/authorization flow
- Job queue system between API and Worker

b) Data Flow Patterns:
- Claims data ingestion flow
- Authentication flow
- Job processing flow
- File storage and retrieval flow

##### Detailed Component Breakdown

API Service Components:
- Authentication (auth/)
- API Endpoints (api/v1/, api/v2/)
- FHIR Models (models/fhir/)
- Database Layer (models/postgres/)
- File Processors (cclf/)

Worker Service Components:
- Queue Management (queueing/)
- Job Processing (worker/)
- File Generation
- Data Export

##### Key Workflows to Highlight

a) Claims Data Processing:
**CCLF Import → Database Storage → Job Queue → Worker Processing → File Generation → S3 Storage**

b) API Request Flow:
**Client → API Gateway → Auth Service → API Service → Database/Storage → Response**

##### Deployment Context

- Container boundaries (using Docker)
- AWS service integration points
- Development vs. production components

This architecture reflects a modern, cloud-native application with clear separation of concerns, robust security, and scalable processing capabilities for handling Medicare claims data.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef api fill:#4169E1,stroke:#fff,stroke-width:2px,color:#fff
    classDef service fill:#2E8B57,stroke:#fff,stroke-width:2px,color:#fff
    classDef data fill:#663399,stroke:#fff,stroke-width:2px,color:#fff
    classDef worker fill:#FFA500,stroke:#fff,stroke-width:2px,color:#fff
    classDef external fill:#008080,stroke:#fff,stroke-width:2px,color:#fff
    
    %% API Layer
    subgraph API
        API_V1["HTTP /v1"]:::api
        API_V2["HTTP /v2"]:::api
        AUTH["Authentication"]:::api
        RATE["Rate Limiting"]:::api
        HEALTH["Health Checks"]:::api
        RESP["Request/Response"]:::api
    end

    %% Service Layer
    subgraph Services
        BIZ["Business Logic"]:::service
        ALR["ALR Processing"]:::service
        FHIR["FHIR Resources"]:::service
        CLAIMS["Claims Processing"]:::service
    end

    %% Data Layer
    subgraph Data
        DB["PostgreSQL"]:::data
        REPO["Repository"]:::data
        MODELS["Data Models"]:::data
        MIGRATIONS["Migrations"]:::data
    end

    %% Worker System
    subgraph Workers
        QUEUE["Queue Management"]:::worker
        JOBS["Job Processing"]:::worker
        TASKS["Background Tasks"]:::worker
        FILES["File Processing"]:::worker
    end

    %% External Integrations
    subgraph External
        BB["Blue Button"]:::external
        SSAS["SSAS"]:::external
        AWS["AWS Services"]:::external
        S3["S3 Storage"]:::external
    end

    %% Connections
    API_V1 & API_V2 --> AUTH
    AUTH --> BIZ
    BIZ --> FHIR
    BIZ --> CLAIMS
    BIZ --> ALR
    CLAIMS --> QUEUE
    QUEUE --> JOBS
    JOBS --> FILES
    FILES --> S3
    BIZ --> REPO
    REPO --> DB
    BIZ --> BB
    AUTH --> SSAS
    FILES --> AWS

    %% Click events
    click API_V1 "https://github.com/CMSgov/bcda-app/blob/main/bcda/api/v1/api.go"
    click API_V2 "https://github.com/CMSgov/bcda-app/blob/main/bcda/api/v2/api.go"
    click AUTH "https://github.com/CMSgov/bcda-app/blob/main/bcda/auth/middleware.go"
    click RATE "https://github.com/CMSgov/bcda-app/blob/main/bcda/web/middleware/ratelimit.go"
    click HEALTH "https://github.com/CMSgov/bcda-app/blob/main/bcda/health/health.go"
    click RESP "https://github.com/CMSgov/bcda-app/blob/main/bcda/responseutils/writer.go"
    click BIZ "https://github.com/CMSgov/bcda-app/blob/main/bcda/service/service.go"
    click ALR "https://github.com/CMSgov/bcda-app/blob/main/bcda/alr/alr.go"
    click FHIR "https://github.com/CMSgov/bcda-app/blob/main/bcda/models/fhir/models.go"
    click CLAIMS "https://github.com/CMSgov/bcda-app/blob/main/bcda/cclf/cclf.go"
    click DB "https://github.com/CMSgov/bcda-app/blob/main/bcda/database/config.go"
    click REPO "https://github.com/CMSgov/bcda-app/blob/main/bcda/models/repository.go"
    click MODELS "https://github.com/CMSgov/bcda-app/blob/main/bcda/models/models.go"
    click MIGRATIONS "https://github.com/CMSgov/bcda-app/tree/main/db/migrations/bcda/"
    click QUEUE "https://github.com/CMSgov/bcda-app/blob/main/bcdaworker/queueing/manager.go"
    click JOBS "https://github.com/CMSgov/bcda-app/blob/main/bcdaworker/worker/worker.go"
    click TASKS "https://github.com/CMSgov/bcda-app/blob/main/bcdaworker/main.go"
    click FILES "https://github.com/CMSgov/bcda-app/blob/main/bcda/cclf/file_handler.go"
    click BB "https://github.com/CMSgov/bcda-app/blob/main/bcda/client/bluebutton.go"
    click SSAS "https://github.com/CMSgov/bcda-app/blob/main/bcda/auth/client/ssas.go"
    click AWS "https://github.com/CMSgov/bcda-app/blob/main/bcda/aws/session.go"
    click S3 "https://github.com/CMSgov/bcda-app/blob/main/bcda/cclf/s3_fileprocessor.go"
```
