# davejfranco/python-fastapi-demo architecture

> Architecture diagram of the GitHub repository davejfranco/python-fastapi-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davejfranco/python-fastapi-demo
- Repository: https://github.com/davejfranco/python-fastapi-demo

## Overview

##### Project Type and Purpose
- This is a backend microservice/demo written in Python using FastAPI.
- It exposes a simple REST API, backed by a light-weight persistence layer (data loaded from JSON or a local database file).
- It is containerized (Dockerfile) and packaged for Kubernetes deployment via a Helm chart.
- It also includes GitHub Actions workflows for CI/CD (build, test, push, deploy).

##### File Structure Analysis
─ .github/workflows              : CI/CD pipelines (cicd.yaml, pr.yaml)
─ Dockerfile                     : Container image build definition
─ README.md                      : Project overview & startup instructions
─ app/
├─ main.py                     : UVicorn/FastAPI application entrypoint
├─ api/api.py                  : Route definitions / request handlers
└─ db/
├─ database.py              : Data-access layer (session/connection)
└─ models.py                : ORM/data models
─ chart/                          : Helm chart for on-cluster deployment
├─ Chart.yaml                  : Chart metadata
├─ values.yaml, *-values.yaml  : Environment-specific settings (local, EKS)
└─ templates/                  : Kubernetes manifests (Deployment, Service, Ingress, HPA, ServiceAccount, tests)
─ k8s/app.yaml                   : Raw Kubernetes manifest example
─ data/                          : Static JSON data (products.json, stores.json)
─ test/                          : Unit test suite (pytest)
─ requirements.txt               : Python dependencies

##### Additional Insights from README
- It’s a demonstration of FastAPI, containerization, and CI/CD rather than a production-grade system.
- Startup is via `uvicorn app.main:app --reload`, tests via `pytest`.

a. Main Components
- Client (e.g. browser, curl, Postman)
- API Service Pods (FastAPI app in Docker)
- Data Layer (in-pod JSON or lightweight DB)
- Kubernetes Cluster Resources: Ingress, Service, Deployment, HPA
- Container Registry (Docker Hub/ECR)
- CI/CD Pipeline (GitHub Actions)
- Helm Chart (packaging & configuration)

b. Relationships & Interactions
1. Client → Ingress (via HTTP/HTTPS)
2. Ingress → Service → Deployment pods (FastAPI)
3. FastAPI handlers ↔ Data Layer (JSON files or DB session)
4. GitHub Actions on push: run tests, build Docker image, push to registry, trigger Helm-based deploy to Kubernetes
5. Helm Chart parameters drive the Deployment, Service, Ingress, HPA manifests

c. Architectural Patterns & Principles
– 12-factor app: config via environment/values.yaml
– Infrastructure as code: Kubernetes manifest templates + Helm
– Continuous delivery: automated workflows for build/test/deploy
– Clear separation: API logic vs. data-access layer vs. deployment artifacts

d. Key Technologies & Libraries
- FastAPI + Uvicorn
- SQLAlchemy or Pydantic models (depending on implementation in models.py)
- Docker
- Kubernetes + Helm
- GitHub Actions
- pytest

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and CI/CD
    subgraph "Development & CI/CD"
        GH["GitHub Actions\n(.github/workflows)"]:::devtools
        PR["PR Workflow\n(pr.yaml)"]:::devtools
        CICD["CI/CD Workflow\n(cicd.yaml)"]:::devtools
    end

    %% Local Development
    LocalDev["Local Dev\nuvicorn app.main:app"]:::devtools
    Req["Python Dependencies\nrequirements.txt"]:::devtools
    Test["Unit Tests\n(test/test.py)"]:::devtools

    %% Build & Package
    subgraph "Build & Packaging"
        DF["Dockerfile"]:::devtools
        Build["Docker Build"]:::devtools
        Registry["Container Registry\n(Docker Hub/ECR)"]:::infra
        Helm["Helm Chart\n(chart/)"]:::infra
        ChartMeta["Chart Meta & Values"]:::infra
        Templates["K8s Manifests Templates"]:::infra
    end

    %% Kubernetes Cluster Runtime
    subgraph "Kubernetes Cluster"
        Ingress["Ingress"]:::runtime
        Service["Service"]:::runtime
        Deployment["Deployment"]:::runtime
        HPA["HPA"]:::runtime
        subgraph "FastAPI Pod"
            Main["FastAPI App\n(app/main.py)"]:::runtime
            API["API Handlers\n(app/api/api.py)"]:::runtime
            DB["Data Access\n(app/db/database.py)"]:::runtime
            Models["Data Models\n(app/db/models.py)"]:::runtime
            subgraph "Static JSON Store"
                ProdData["products.json"]:::data
                StoreData["stores.json"]:::data
            end
        end
    end

    %% External Client
    Client["Client\n(Postman, Browser)"]:::external

    %% Raw K8s Example
    RawK8s["Raw K8s Manifest\n(k8s/app.yaml)"]:::infra

    %% Connections
    Client -->|HTTP/HTTPS| Ingress
    Ingress --> Service
    Service --> Deployment
    Deployment --> HPA
    Deployment --> Main
    Main --> API
    API --> DB
    DB --> Models
    Models --> ProdData
    Models --> StoreData

    %% CI/CD Flow
    GH --> CICD
    PR --> CICD
    CICD --> Test
    CICD --> Build
    Build --> DF
    Build --> Registry
    CICD --> Registry
    CICD --> Helm
    Helm --> ChartMeta
    Helm --> Templates
    Templates -->|renders| RawK8s
    CICD -->|deploy| RawK8s

    %% Local Dev Flow
    LocalDev --> Main
    Req --> LocalDev
    Test --> LocalDev

    %% Click Events
    click Main "https://github.com/davejfranco/python-fastapi-demo/blob/master/app/main.py"
    click API "https://github.com/davejfranco/python-fastapi-demo/blob/master/app/api/api.py"
    click DB "https://github.com/davejfranco/python-fastapi-demo/blob/master/app/db/database.py"
    click Models "https://github.com/davejfranco/python-fastapi-demo/blob/master/app/db/models.py"
    click ProdData "https://github.com/davejfranco/python-fastapi-demo/blob/master/data/products.json"
    click StoreData "https://github.com/davejfranco/python-fastapi-demo/blob/master/data/stores.json"
    click DF "https://github.com/davejfranco/python-fastapi-demo/tree/master/Dockerfile"
    click GH "https://github.com/davejfranco/python-fastapi-demo/blob/master/.github/workflows/cicd.yaml"
    click PR "https://github.com/davejfranco/python-fastapi-demo/blob/master/.github/workflows/pr.yaml"
    click Test "https://github.com/davejfranco/python-fastapi-demo/blob/master/test/test.py"
    click Req "https://github.com/davejfranco/python-fastapi-demo/blob/master/requirements.txt"
    click ChartMeta "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/Chart.yaml"
    click ChartMeta "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/values.yaml"
    click ChartMeta "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/local-values.yaml"
    click ChartMeta "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/eks-values.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/deployment.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/service.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/ingress.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/hpa.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/serviceaccount.yaml"
    click Templates "https://github.com/davejfranco/python-fastapi-demo/blob/master/chart/templates/tests/test-connection.yaml"
    click RawK8s "https://github.com/davejfranco/python-fastapi-demo/blob/master/k8s/app.yaml"

    %% Styles
    classDef runtime fill:#add8e6,stroke:#000
    classDef devtools fill:#90ee90,stroke:#000
    classDef infra fill:#ffcc99,stroke:#000
    classDef data fill:#f4c2c2,stroke:#000
    classDef external fill:#cccccc,stroke:#000,stroke-dasharray: 5 5
```
