# ishihab/fastapi_project architecture

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

- Interactive diagram: https://gitdiagram.com/ishihab/fastapi_project
- Repository: https://github.com/ishihab/fastapi_project

## Overview

1. **Repository shape**
   - This repo contains two runtime applications plus infrastructure code:
     - `backend/` — FastAPI API
     - `web/` — Streamlit UI
     - `terraform/` — AWS + Kubernetes provisioning
     - `k8s/` — standalone Kubernetes manifests kept as reference, but the README says Terraform is the source of truth for cluster deployment

2. **User-facing system boundary**
   - The main product boundary is a browser-based social app.
   - The browser talks only to the Streamlit frontend.
   - The Streamlit app talks to the FastAPI backend over HTTP.
   - The backend is the system of record for users, posts, and auth state; the frontend is a thin presentation and session-management layer.

3. **Backend application structure**
   - `backend/main.py` is the container/app entry point.
   - `backend/app/app.py` is the main FastAPI application and route wiring.
   - `backend/app/schemas.py` defines request/response shapes.
   - `backend/app/db.py` holds database/session/ORM setup.
   - `backend/app/users.py` encapsulates authentication and user management.
   - `backend/app/images.py` handles media upload and ImageKit integration.
   - `backend/test.py` provides backend-level test coverage.

4. **Backend responsibilities**
   - The API provides registration, login, JWT auth, current-user lookup, post upload, feed retrieval, and post deletion.
   - Authorization is enforced server-side, especially for “delete your own post” behavior.
   - Media handling is not local file storage; the backend delegates image/video storage to ImageKit and stores metadata in MySQL.

5. **Backend data flow**
   - A client authenticates through FastAPI Users/JWT.
   - Authenticated requests carry the token back to the backend.
   - For uploads, the backend accepts post content, sends media to ImageKit, and writes the resulting post record to the database.
   - For feed reads, the backend queries MySQL and returns posts ordered by creation time.
   - For deletion, the backend validates ownership before removing the post and associated media reference.

6. **Frontend application structure**
   - `web/frontend.py` is the Streamlit UI implementation.
   - `web/main.py` is the frontend entry point.
   - The frontend depends on the backend API URL supplied through configuration, rather than embedding backend logic locally.
   - It uses HTTP requests to drive login, registration, upload, feed display, and deletion actions.

7. **Frontend data flow**
   - The user interacts with Streamlit forms and controls.
   - Streamlit sends API requests to the backend using the configured `API_URL`.
   - Backend responses are rendered into the feed and user session state.
   - This separation means the UI is stateless aside from browser/session-level state; business logic stays in FastAPI.

8. **Persistence and external services**
   - Primary persistent datastore: MySQL.
   - Media storage/external asset hosting: ImageKit.
   - Database access is async according to the README, using SQLAlchemy with an async MySQL driver.
   - The backend therefore depends on both a relational database for application state and a third-party media service for binary content.

9. **Cloud infrastructure boundary**
   - Terraform in `terraform/` provisions the runtime environment on AWS.
   - The stack includes VPC networking, EKS for Kubernetes workload execution, and RDS MySQL for the database.
   - The deployment is cloud-native rather than VM-based: app containers run as Kubernetes workloads inside EKS.

10. **Kubernetes deployment model**
   - Terraform also manages Kubernetes objects, not just AWS infrastructure.
   - The app is deployed as two services:
     - backend API deployment/service
     - frontend Streamlit deployment/service
   - An ingress exposes the frontend/API through an AWS load balancer controller.
   - Secrets and ConfigMaps are used to inject database credentials and backend URL into the pods.

11. **Operational automation**
   - `terraform/cleaner.tf` and the README indicate an automated cleanup path using Lambda and S3.
   - This suggests some media- or artifact-cleanup workflow outside the main request path.
   - The infrastructure layer is responsible for generating credentials, wiring services together, and exposing the application endpoint.

12. **Reference manifests vs deployed source of truth**
   - The `k8s/` directory contains YAML manifests for API, web, ingress, MySQL service, and MySQL statefulset.
   - However, the README explicitly says Terraform manages Kubernetes resources in practice.
   - For architecture diagrams, treat `k8s/` as reference material and `terraform/` as the actual deployment orchestrator.

13. **End-to-end runtime picture**
   - Browser → Streamlit frontend → FastAPI backend → MySQL / ImageKit
   - Terraform → AWS EKS/RDS/VPC/IAM/Lambda → Kubernetes deployments/services/ingress
   - This separation cleanly divides presentation, application logic, persistence, and infrastructure provisioning.

Main entry points: [`backend/app/app.py`](https://github.com/ishihab/fastapi_project/blob/main/backend/app/app.py) (API app), [`terraform/k8s.tf`](https://github.com/ishihab/fastapi_project/blob/main/terraform/k8s.tf) (K8s stack), [`terraform/main.tf`](https://github.com/ishihab/fastapi_project/blob/main/terraform/main.tf) (Terraform), [`web/main.py`](https://github.com/ishihab/fastapi_project/blob/main/web/main.py) (Web entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>user client"))
end

subgraph group_frontend["Frontend"]
  node_web_main["Web entry<br/>streamlit app<br/>[main.py]"]
  node_web_frontend["UI logic<br/>streamlit ui<br/>[frontend.py]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API entry<br/>[main.py]"]
  node_backend_app["API app<br/>[app.py]"]
  node_backend_users["Auth & users<br/>auth service<br/>[users.py]"]
  node_backend_images["Media service<br/>image integration<br/>[images.py]"]
  node_backend_db[("Data layer<br/>async mysql orm<br/>[db.py]")]
  node_backend_schemas["Schemas<br/>api contracts<br/>[schemas.py]"]
end

subgraph group_infra["Infrastructure"]
  node_terraform_root["Terraform<br/>infra orchestrator<br/>[main.tf]"]
  node_terraform_k8s["K8s stack<br/>kubernetes deploy<br/>[k8s.tf]"]
  node_terraform_cleaner["Cleaner<br/>lambda workflow<br/>[cleaner.tf]"]
  node_k8s_reference["K8s manifests<br/>reference yaml<br/>[ingress.yaml]"]
  node_eks{{"EKS<br/>kubernetes cluster"}}
  node_vpc{{"VPC<br/>networking"}}
end

subgraph group_external["External"]
  node_rds[("MySQL<br/>managed database")]
  node_imagekit(("ImageKit<br/>media storage"))
  node_aws_lb{{"Load balancer<br/>aws ingress"}}
end

node_browser -->|"uses"| node_web_main
node_web_main -->|"renders"| node_web_frontend
node_web_frontend -->|"HTTP API"| node_backend_app
node_backend_main -->|"starts"| node_backend_app
node_backend_app -->|"auth"| node_backend_users
node_backend_app -->|"media"| node_backend_images
node_backend_app -->|"persistence"| node_backend_db
node_backend_app -->|"contracts"| node_backend_schemas
node_backend_users -->|"stores"| node_backend_db
node_backend_images -->|"uploads"| node_imagekit
node_backend_db -->|"connects"| node_rds
node_terraform_root -->|"provisions"| node_vpc
node_terraform_root -->|"provisions"| node_eks
node_terraform_root -->|"provisions"| node_rds
node_terraform_root -->|"orchestrates"| node_terraform_k8s
node_terraform_root -->|"orchestrates"| node_terraform_cleaner
node_terraform_k8s -->|"deploys to"| node_eks
node_terraform_k8s -->|"exposes"| node_aws_lb
node_terraform_k8s -->|"runs"| node_backend_main
node_terraform_k8s -->|"runs"| node_web_main
node_k8s_reference -.->|"reference"| node_terraform_k8s
node_aws_lb -->|"routes"| node_web_main

click node_web_main "https://github.com/ishihab/fastapi_project/blob/main/web/main.py"
click node_web_frontend "https://github.com/ishihab/fastapi_project/blob/main/web/frontend.py"
click node_backend_main "https://github.com/ishihab/fastapi_project/blob/main/backend/main.py"
click node_backend_app "https://github.com/ishihab/fastapi_project/blob/main/backend/app/app.py"
click node_backend_users "https://github.com/ishihab/fastapi_project/blob/main/backend/app/users.py"
click node_backend_images "https://github.com/ishihab/fastapi_project/blob/main/backend/app/images.py"
click node_backend_db "https://github.com/ishihab/fastapi_project/blob/main/backend/app/db.py"
click node_backend_schemas "https://github.com/ishihab/fastapi_project/blob/main/backend/app/schemas.py"
click node_terraform_root "https://github.com/ishihab/fastapi_project/blob/main/terraform/main.tf"
click node_terraform_k8s "https://github.com/ishihab/fastapi_project/blob/main/terraform/k8s.tf"
click node_terraform_cleaner "https://github.com/ishihab/fastapi_project/blob/main/terraform/cleaner.tf"
click node_k8s_reference "https://github.com/ishihab/fastapi_project/blob/main/k8s/ingress.yaml"

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_browser toneBlue
class node_web_main,node_web_frontend toneAmber
class node_backend_main,node_backend_app,node_backend_users,node_backend_images,node_backend_db,node_backend_schemas toneMint
class node_terraform_root,node_terraform_k8s,node_terraform_cleaner,node_k8s_reference,node_eks,node_vpc toneRose
class node_rds,node_imagekit,node_aws_lb toneIndigo
```

## Components

### Client

Browser-side entry point and user interaction layer

- **Browser**: user client · User-facing entry point

### Frontend

Streamlit presentation layer

- [Web entry](https://github.com/ishihab/fastapi_project/blob/main/web/main.py): streamlit app · Streamlit application entrypoint · `web/main.py`
- [UI logic](https://github.com/ishihab/fastapi_project/blob/main/web/frontend.py): streamlit ui · Forms, session state, and API-driven rendering · `web/frontend.py`

### Backend

FastAPI application and domain logic

- [API entry](https://github.com/ishihab/fastapi_project/blob/main/backend/main.py): fastapi entry · Backend container and application entrypoint · `backend/main.py`
- [API app](https://github.com/ishihab/fastapi_project/blob/main/backend/app/app.py): fastapi app · Main FastAPI application and route wiring · `backend/app/app.py`
- [Auth & users](https://github.com/ishihab/fastapi_project/blob/main/backend/app/users.py): auth service · Registration, login, JWT auth, and user management · `backend/app/users.py`
- [Media service](https://github.com/ishihab/fastapi_project/blob/main/backend/app/images.py): image integration · Upload handling and ImageKit integration · `backend/app/images.py`
- [Data layer](https://github.com/ishihab/fastapi_project/blob/main/backend/app/db.py): async mysql orm · Async database and ORM/session setup · `backend/app/db.py`
- [Schemas](https://github.com/ishihab/fastapi_project/blob/main/backend/app/schemas.py): api contracts · Request and response models · `backend/app/schemas.py`

### Infrastructure

Terraform-managed cloud and deployment stack

- [Terraform](https://github.com/ishihab/fastapi_project/blob/main/terraform/main.tf): infra orchestrator · Source of truth for AWS and Kubernetes deployment · `terraform/main.tf`
- [K8s stack](https://github.com/ishihab/fastapi_project/blob/main/terraform/k8s.tf): kubernetes deploy · Terraform-managed Kubernetes workloads, services, and ingress · `terraform/k8s.tf`
- [Cleaner](https://github.com/ishihab/fastapi_project/blob/main/terraform/cleaner.tf): lambda workflow · Automated cleanup workflow and supporting resources · `terraform/cleaner.tf`
- [K8s manifests](https://github.com/ishihab/fastapi_project/blob/main/k8s/ingress.yaml): reference yaml · Reference manifests kept alongside Terraform-managed deployment · `k8s/ingress.yaml`
- **EKS**: kubernetes cluster · Execution environment for application containers
- **VPC**: networking · Cloud network boundary for the stack

### External

Managed services used by the system

- **MySQL**: managed database · Primary relational datastore for app state
- **ImageKit**: media storage · External media hosting and asset delivery
- **Load balancer**: aws ingress · Ingress exposure for the cluster

## Connections

- Browser → Web entry: uses · User accesses the Streamlit app
- Web entry → UI logic: renders · Entrypoint loads the UI layer
- UI logic → API app: HTTP API · UI drives login, feed, upload, and delete actions through the backend
- API entry → API app: starts · Container entrypoint launches the FastAPI application
- API app → Auth & users: auth · Routes delegate authentication and user management
- API app → Media service: media · Routes delegate upload and media handling
- API app → Data layer: persistence · Routes read and write application state through the data layer
- API app → Schemas: contracts · API layer uses request and response models
- Auth & users → Data layer: stores · User and auth state is persisted in the database
- Media service → ImageKit: uploads · Binary media is delegated to ImageKit
- Data layer → MySQL: connects · Async SQLAlchemy/MySQL access targets the managed database
- Terraform → VPC: provisions · Terraform creates the network boundary
- Terraform → EKS: provisions · Terraform creates the Kubernetes cluster
- Terraform → MySQL: provisions · Terraform provisions the MySQL database
- Terraform → K8s stack: orchestrates · Terraform manages application Kubernetes resources
- Terraform → Cleaner: orchestrates · Terraform also manages cleanup automation
- K8s stack → EKS: deploys to · Application workloads run inside the cluster
- K8s stack → Load balancer: exposes · Ingress is published through the AWS load balancer controller
- K8s stack → API entry: runs · Backend is deployed as a Kubernetes workload
- K8s stack → Web entry: runs · Frontend is deployed as a Kubernetes workload
- K8s manifests → K8s stack: reference · Standalone manifests mirror the Terraform-managed deployment
- Load balancer → Web entry: routes · External traffic reaches the Streamlit frontend through ingress