# ashishpatel26/fastapi-ci-cd architecture

> Architecture diagram of the GitHub repository ashishpatel26/fastapi-ci-cd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashishpatel26/fastapi-ci-cd
- Repository: https://github.com/ashishpatel26/fastapi-ci-cd

## Overview

1. **Repository purpose**
   - This repo is primarily a **FastAPI service plus delivery pipeline**. The application itself is very small; most of the architecture is around how it is **built, tested, containerized, published, and deployed**.

2. **Application runtime boundary**
   - `main.py` is the runtime entrypoint for the service.
   - It exposes three HTTP endpoints:
     - `/` for the greeting response
     - `/health` for liveness/readiness-style checks
     - `/version` for release identification
   - This is a **stateless API service** with no database, queue, cache, or internal service dependencies visible in the repo.

3. **Test boundary**
   - `tests/test_main.py` contains the unit/integration-style checks for the FastAPI app.
   - The test suite is small and directly validates the contract of the public endpoints.
   - In the architecture diagram, this is the **quality gate before container build and release**.

4. **Dependency and build management**
   - `pyproject.toml` and `uv.lock` define the Python environment and pinned dependencies.
   - `uv` is the package manager/runtime coordinator used in local development and CI.
   - This matters architecturally because the repo is designed for **reproducible builds** rather than ad hoc dependency resolution.

5. **Containerization layer**
   - `Dockerfile` packages the FastAPI app into a runnable container image.
   - The README indicates Podman is the container engine used in the workflow, though the image artifact itself is standard OCI-compatible.
   - This container is the **handoff point between application build and cluster deployment**.

6. **Continuous integration flow**
   - `.github/workflows/ci.yml` runs on pushes/PRs as the validation pipeline.
   - The documented sequence is:
     - `uv sync --frozen`
     - `pytest`
     - `podman build`
   - The CI boundary verifies both **code correctness** and **container buildability** before release.

7. **Continuous delivery / release flow**
   - `.github/workflows/cd.yml` handles publishing to **GHCR** (`ghcr.io`).
   - The release flow logs in with a GitHub token, builds images tagged with both commit SHA and `latest`, and pushes them to the registry.
   - In the diagram, GHCR is the **artifact registry** between CI and Kubernetes.

8. **Kubernetes deployment layer**
   - `fastapi-chart/` is a Helm chart that defines the cluster-side deployment.
   - The chart templates include:
     - `deployment.yaml` for the pod workload
     - `service.yaml` for network exposure
   - `values.yaml` provides the configurable image/service parameters, making the deployment reusable across environments.

9. **Deployment dependency chain**
   - Kubernetes does not build the app; it **pulls the image from GHCR** and runs the container created by the pipeline.
   - A GHCR image pull secret is required for private registry access.
   - The main runtime path is therefore:
     - source code → CI tests → container image → GHCR → Helm release → Kubernetes pod/service

10. **Local development and verification**
   - The README and supporting files (`command.md`, `steps.md`) show the intended local workflow:
     - run the app with Uvicorn
     - validate with tests
     - build and run the container
     - optionally deploy to Minikube
   - This is a **developer-facing path** that mirrors the production pipeline but stays local.

11. **Infrastructure assumptions**
   - The deployment target is Kubernetes, with Minikube used for local cluster testing.
   - Podman is the container runtime/tooling emphasized in CI/CD.
   - GHCR is the external infrastructure service used to store deployable artifacts.
   - There are no other external backend services evident in the repo.

12. **What to draw in an architecture diagram**
   - Show a small FastAPI application box with three routes.
   - Add a testing gate connected to the source code.
   - Add a build/publish pipeline that produces container images and pushes them to GHCR.
   - Add a Kubernetes/Helm deployment that pulls from GHCR and exposes the app via a Service.
   - Keep docs/assets out of the runtime path; they support the project but do not participate in execution.

Main entry points: [`README.md`](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/README.md) (Workflow docs), [`fastapi-chart`](https://github.com/ashishpatel26/fastapi-ci-cd/tree/main/fastapi-chart) (Helm chart), [`main.py`](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/main.py) (Service API), [`.github/workflows/ci.yml`](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/.github/workflows/ci.yml) (CI pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["Service API<br/>FastAPI app<br/>[main.py]"]
end

subgraph group_quality["Quality"]
  node_tests_main["Endpoint tests<br/>pytest<br/>[test_main.py]"]
  node_pyproject["Python deps<br/>build config<br/>[pyproject.toml]"]
  node_uv_lock["Locked deps<br/>lockfile<br/>[uv.lock]"]
end

subgraph group_delivery["Delivery"]
  node_ci_workflow["CI pipeline<br/>GitHub Actions<br/>[ci.yml]"]
  node_cd_workflow["Release pipeline<br/>GitHub Actions<br/>[cd.yml]"]
  node_dockerfile["Container build<br/>Dockerfile"]
  node_podman{{"Podman build<br/>container tool"}}
  node_ghcr[("GHCR<br/>registry")]
end

subgraph group_deploy["Deployment"]
  node_chart["Helm chart<br/>k8s package"]
  node_chart_deploy["Workload<br/>Deployment template<br/>[deployment.yaml]"]
  node_chart_service["Service<br/>[service.yaml]"]
  node_chart_values["Chart values<br/>configuration<br/>[values.yaml]"]
  node_kubernetes[("Kubernetes<br/>cluster")]
end

subgraph group_dev["Local Dev"]
  node_minikube[("Minikube<br/>local cluster")]
  node_readme["Workflow docs<br/>[README.md]"]
  node_steps["Steps guide<br/>docs<br/>[steps.md]"]
  node_command["Commands<br/>docs<br/>[command.md]"]
end

node_pyproject -->|"pins"| node_uv_lock
node_pyproject -->|"supports"| node_main_py
node_uv_lock -->|"syncs"| node_ci_workflow
node_main_py -->|"verified by"| node_tests_main
node_tests_main -->|"gate"| node_ci_workflow
node_main_py -->|"baked into"| node_dockerfile
node_dockerfile -->|"built with"| node_podman
node_ci_workflow -->|"builds"| node_podman
node_podman -->|"pushes"| node_ghcr
node_cd_workflow -->|"publishes"| node_ghcr
node_ghcr -->|"pulled by"| node_chart_deploy
node_chart_values -->|"configures"| node_chart_deploy
node_chart_values -->|"configures"| node_chart_service
node_chart -->|"includes"| node_chart_deploy
node_chart -->|"includes"| node_chart_service
node_chart -->|"parameterized by"| node_chart_values
node_chart_deploy -->|"runs on"| node_kubernetes
node_chart_service -->|"exposes"| node_kubernetes
node_minikube -->|"local target"| node_kubernetes
node_readme -.->|"documents"| node_main_py
node_readme -.->|"documents"| node_tests_main
node_readme -.->|"documents"| node_ci_workflow
node_readme -.->|"documents"| node_cd_workflow
node_readme -.->|"documents"| node_chart
node_steps -.->|"supports"| node_readme
node_command -.->|"supports"| node_readme

click node_main_py "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/main.py"
click node_tests_main "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/tests/test_main.py"
click node_pyproject "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/pyproject.toml"
click node_uv_lock "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/uv.lock"
click node_ci_workflow "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/.github/workflows/ci.yml"
click node_cd_workflow "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/.github/workflows/cd.yml"
click node_dockerfile "https://github.com/ashishpatel26/fastapi-ci-cd/tree/main/Dockerfile"
click node_chart "https://github.com/ashishpatel26/fastapi-ci-cd/tree/main/fastapi-chart"
click node_chart_deploy "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/templates/deployment.yaml"
click node_chart_service "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/templates/service.yaml"
click node_chart_values "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/values.yaml"
click node_readme "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/README.md"
click node_steps "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/steps.md"
click node_command "https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/command.md"

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_main_py toneBlue
class node_tests_main,node_pyproject,node_uv_lock toneAmber
class node_ci_workflow,node_cd_workflow,node_dockerfile,node_podman,node_ghcr toneMint
class node_chart,node_chart_deploy,node_chart_service,node_chart_values,node_kubernetes toneRose
class node_minikube,node_readme,node_steps,node_command toneIndigo
```

## Components

### Runtime

FastAPI service entrypoint and request handling

- [Service API](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/main.py): FastAPI app · Runtime entrypoint exposing /, /health, and /version · `main.py`

### Quality

Tests and reproducible Python environment

- [Endpoint tests](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/tests/test_main.py): pytest · Validates the public HTTP contract for the service · `tests/test_main.py`
- [Python deps](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/pyproject.toml): build config · Declares the Python environment and project metadata · `pyproject.toml`
- [Locked deps](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/uv.lock): lockfile · Pinned dependency set for reproducible installs · `uv.lock`

### Delivery

Container build and registry publication

- [CI pipeline](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/.github/workflows/ci.yml): GitHub Actions · Runs sync, tests, and container build on PRs and pushes · `.github/workflows/ci.yml`
- [Release pipeline](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/.github/workflows/cd.yml): GitHub Actions · Builds and pushes release images to GHCR · `.github/workflows/cd.yml`
- [Container build](https://github.com/ashishpatel26/fastapi-ci-cd/tree/main/Dockerfile): Dockerfile · Packages the FastAPI app into an OCI image · `Dockerfile`
- **Podman build**: container tool · Runtime used to build the image in local and CI workflows
- **GHCR**: registry · Artifact registry holding release images

### Deployment

Helm chart and Kubernetes release

- [Helm chart](https://github.com/ashishpatel26/fastapi-ci-cd/tree/main/fastapi-chart): k8s package · Reusable Kubernetes deployment package · `fastapi-chart`
- [Workload](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/templates/deployment.yaml): Deployment template · Defines the pod spec that runs the container image · `fastapi-chart/templates/deployment.yaml`
- [Service](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/templates/service.yaml): Service template · Exposes the running pod inside the cluster · `fastapi-chart/templates/service.yaml`
- [Chart values](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/fastapi-chart/values.yaml): configuration · Configures image and service parameters for releases · `fastapi-chart/values.yaml`
- **Kubernetes**: cluster · Executes the deployed container and service

### Local Dev

Developer-facing workflow docs and setup

- **Minikube**: local cluster · Local Kubernetes environment for verification
- [Workflow docs](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/README.md): docs · Describes local run, test, build, and deploy steps · `README.md`
- [Steps guide](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/steps.md): docs · Supporting process notes for the developer workflow · `steps.md`
- [Commands](https://github.com/ashishpatel26/fastapi-ci-cd/blob/main/command.md): docs · Quick command reference for local development · `command.md`

## Connections

- Python deps → Locked deps: pins · Project metadata and locked dependencies define the reproducible environment
- Python deps → Service API: supports · Application code runs within the declared Python environment
- Locked deps → CI pipeline: syncs · CI installs the frozen dependency set before validation
- Service API → Endpoint tests: verified by · Endpoint tests exercise the FastAPI contract
- Endpoint tests → CI pipeline: gate · Tests are the quality gate in CI
- Service API → Container build: baked into · The service source is packaged into the container image
- Container build → Podman build: built with · Podman performs the image build step
- CI pipeline → Podman build: builds · CI uses Podman to verify the image can be built
- Podman build → GHCR: pushes · Release builds are published as registry images
- Release pipeline → GHCR: publishes · CD tags and pushes images to the registry
- GHCR → Workload: pulled by · Kubernetes pulls the published image for deployment
- Chart values → Workload: configures · Values supply the image and runtime settings
- Chart values → Service: configures · Values also shape service exposure
- Helm chart → Workload: includes · The Helm chart renders the deployment template
- Helm chart → Service: includes · The Helm chart renders the service template
- Helm chart → Chart values: parameterized by · Chart defaults and overrides control the release
- Workload → Kubernetes: runs on · Deployment manifests create pods in the cluster
- Service → Kubernetes: exposes · Service manifests route traffic to the workload
- Minikube → Kubernetes: local target · Minikube is the local cluster used for verification
- Workflow docs → Service API: documents · README explains how to run the service locally
- Workflow docs → Endpoint tests: documents · README covers the validation workflow
- Workflow docs → CI pipeline: documents · README summarizes CI behavior
- Workflow docs → Release pipeline: documents · README summarizes release behavior
- Workflow docs → Helm chart: documents · README explains Kubernetes deployment
- Steps guide → Workflow docs: supports · Supporting notes expand the documented workflow
- Commands → Workflow docs: supports · Command reference complements the main workflow docs