# shieldersoftops/healthapishield architecture

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

- Interactive diagram: https://gitdiagram.com/shieldersoftops/healthapishield
- Repository: https://github.com/shieldersoftops/healthapishield

## Overview

##### Project Type and Purpose
- This is a backend API-gateway/microservice (no UI) built with FastAPI.
- Purpose: secure, monitor, and process healthcare data requests. It exposes three routes—main gateway (`/medx/{path}`), a health check (`/health`), and a webhook (`/webhook/alerts`)—and implements IP-validation, authentication, payload inspection, PII sanitization, rate limiting, analytics logging, and alerting.

##### File Structure
- Top-level:
- `main.py` – application entry point
- `init_db.py` – one-time DB initializer
- `app/` – code modules
- app/core: configuration loader (env, settings)
- app/db: database connection (`database.py`) and ORM models (`models.py`)
- app/middleware: FastAPI middleware chain (auth, rate limiter, payload inspector, PII shredder, IP validator, analytics logger)
- app/routers: route definitions (gateway/API, health, webhook)
- app/services: business logic services that each middleware or router calls
- app/models: Pydantic request/response schemas
- Requirements: FastAPI, SQLAlchemy, Pydantic, SQLite

##### README for Insights
- Confirms layered architecture: routers → middleware → services → database
- Lists features (IP validation, OAuth2/OpenID, payload security, rate limiting, PII sanitization, analytics, security alerts)
- SQLite DB persisted at `./healthshield.db`

##### Main Components
a. External Clients
- API consumers (mobile/web apps, other services)
- OAuth/OpenID Provider (external authentication)
- Monitoring/Alerting system (webhook receiver)
b. API Gateway (FastAPI Server)
- Routers (API, Health, Webhook)
- Middleware chain (Auth, Rate Limiter, Validator, Payload Inspector, PII Shredder, Analytics Logger)
c. Service Layer
- Auth Service
- Rate Limiter Service
- IP Validation Service
- Payload Inspection Service
- PII Shredder Service
- Analytics Service
- Alerts Service
- Client Handler (for proxying/forwarding requests)
d. Data Layer
- SQLite Database (via SQLAlchemy)
e. Configuration
- Config module (env loading)

##### Relationships and Interactions
- Within Gateway: request flows through middleware chain in configured order
- After passing middleware, Router → calls appropriate Service(s)
- Service(s) → read/write to Database (for rate-limit counters, audit logs, alerts, etc.)
- Auth Service ↔ External OAuth/OpenID Provider
- Alerts Service → sends to Webhook endpoint or external monitoring
- Analytics Service → writes logs/metrics (could be DB or external)

##### Key Architectural Patterns and Design Principles
- Layered Architecture: clear separation of concerns (API, middleware, services, data)
- Chain of Responsibility: middleware components process or short-circuit requests
- Dependency Injection: FastAPI’s DI for injecting config, DB session, services
- Single Responsibility: each module handles one concern (e.g., `pii_shredder.py` only scrubs PII)

##### Technologies and Frameworks
- FastAPI (ASGI, routers, DI)
- SQLAlchemy (DB models, session management)
- Pydantic (request/response schemas)
- Uvicorn (server)
- SQLite (embedded DB)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Dependencies" 
        direction TB
        Client["External Clients"]:::external
        OAuth["OAuth/OpenID Provider"]:::external
        Monitoring["Monitoring/Alerting System"]:::external
    end

    %% Configuration
    Config["Configuration Module"]:::config
    click Config "https://github.com/shieldersoftops/healthapishield/blob/master/app/core/config.py"

    %% API Gateway Layer
    subgraph "API Gateway (FastAPI)" 
        direction TB
        Entry["main.py"]:::api
        click Entry "https://github.com/shieldersoftops/healthapishield/blob/master/main.py"
        API_Router["API Router (/medx/{path})"]:::api
        click API_Router "https://github.com/shieldersoftops/healthapishield/blob/master/app/routers/api.py"
        Health_Router["Health Router (/health)"]:::api
        click Health_Router "https://github.com/shieldersoftops/healthapishield/blob/master/app/routers/health.py"
        Webhook_Router["Webhook Router (/webhook/alerts)"]:::api
        click Webhook_Router "https://github.com/shieldersoftops/healthapishield/blob/master/app/routers/webhook.py"
    end

    %% Middleware Chain
    subgraph "Middleware Chain" 
        direction TB
        Auth_MW["Auth Middleware"]:::middleware
        click Auth_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/auth.py"
        Rate_MW["Rate Limiter Middleware"]:::middleware
        click Rate_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/rate_limiter.py"
        IP_MW["IP Validator Middleware"]:::middleware
        click IP_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/validator.py"
        Inspect_MW["Payload Inspector Middleware"]:::middleware
        click Inspect_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/payload_inspector.py"
        PII_MW["PII Shredder Middleware"]:::middleware
        click PII_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/pii_shredder.py"
        Analytics_MW["Analytics Logger Middleware"]:::middleware
        click Analytics_MW "https://github.com/shieldersoftops/healthapishield/blob/master/app/middleware/analytics_logger.py"
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        Auth_Svc["Authentication Service"]:::service
        click Auth_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/auth.py"
        Rate_Svc["Rate Limiter Service"]:::service
        click Rate_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/rate_limiter.py"
        IP_Svc["IP Validation Service"]:::service
        click IP_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/validator.py"
        Inspect_Svc["Payload Inspection Service"]:::service
        click Inspect_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/payload_inspector.py"
        PII_Svc["PII Shredder Service"]:::service
        click PII_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/pii_shredder.py"
        Analytics_Svc["Analytics Service"]:::service
        click Analytics_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/analytics.py"
        Alerts_Svc["Alerts Service"]:::service
        click Alerts_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/alerts.py"
        Client_Svc["Client Handler Service"]:::service
        click Client_Svc "https://github.com/shieldersoftops/healthapishield/blob/master/app/services/client_handler.py"
    end

    %% Pydantic Schemas
    subgraph "Pydantic Schemas" 
        direction TB
        Auth_Schema["auth.py"]:::models
        click Auth_Schema "https://github.com/shieldersoftops/healthapishield/blob/master/app/models/auth.py"
        Validation_Schema["validation.py"]:::models
        click Validation_Schema "https://github.com/shieldersoftops/healthapishield/blob/master/app/models/validation.py"
        Inspection_Schema["inspection.py"]:::models
        click Inspection_Schema "https://github.com/shieldersoftops/healthapishield/blob/master/app/models/inspection.py"
        RateLimit_Schema["rate_limit.py"]:::models
        click RateLimit_Schema "https://github.com/shieldersoftops/healthapishield/blob/master/app/models/rate_limit.py"
        Alert_Schema["alert.py"]:::models
        click Alert_Schema "https://github.com/shieldersoftops/healthapishield/blob/master/app/models/alert.py"
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        DB_Init["Database Initializer (init_db.py)"]:::data
        click DB_Init "https://github.com/shieldersoftops/healthapishield/blob/master/init_db.py"
        DB_Conn["Database Connection"]:::data
        click DB_Conn "https://github.com/shieldersoftops/healthapishield/blob/master/app/db/database.py"
        ORM["ORM Models"]:::data
        click ORM "https://github.com/shieldersoftops/healthapishield/blob/master/app/db/models.py"
        SQLiteDB["SQLite Database"]:::data
    end

    %% Flow Connections
    Client --> Entry
    Entry --> Config
    Entry --> API_Router
    Entry --> Health_Router
    Entry --> Webhook_Router

    %% Router to Middleware
    API_Router --> Auth_MW
    Health_Router --> Auth_MW
    Webhook_Router --> Auth_MW

    Auth_MW --> Rate_MW
    Rate_MW --> IP_MW
    IP_MW --> Inspect_MW
    Inspect_MW --> PII_MW
    PII_MW --> Analytics_MW

    %% Middleware to Services
    Auth_MW --> Auth_Svc
    Auth_Svc --> OAuth
    Rate_MW --> Rate_Svc
    Rate_Svc --> DB_Conn
    IP_MW --> IP_Svc
    Inspect_MW --> Inspect_Svc
    PII_MW --> PII_Svc
    Analytics_MW --> Analytics_Svc

    %% Routers call Services and DB
    API_Router --> Client_Svc
    Client_Svc --> DB_Conn
    Webhook_Router --> Alerts_Svc
    Alerts_Svc --> Monitoring

    %% Services use Data Layer
    Auth_Svc --> DB_Conn
    Rate_Svc --> DB_Conn
    IP_Svc --> DB_Conn
    Inspect_Svc --> DB_Conn
    PII_Svc --> DB_Conn
    Analytics_Svc --> DB_Conn
    Alerts_Svc --> DB_Conn

    %% Schemas usage
    API_Router --> Auth_Schema
    API_Router --> Validation_Schema
    API_Router --> Inspection_Schema
    API_Router --> RateLimit_Schema
    API_Router --> Alert_Schema

    %% Database Initializer
    DB_Init --> DB_Conn
    DB_Init --> ORM

    %% Styles
    classDef external fill:#e1bee7,stroke:#000
    classDef api fill:#cce5ff,stroke:#000
    classDef middleware fill:#ffe5b4,stroke:#000
    classDef service fill:#d4edda,stroke:#000
    classDef data fill:#e2e3e5,stroke:#000
    classDef config fill:#f0fff0,stroke:#000
    classDef models fill:#f8f9fa,stroke:#000
```
