How ishihab/fastapi_project works
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: app.py API app · k8s.tf K8s stack · main.tf Terraform · main.py Web entry
Components 18
Client
Browser-side entry point and user interaction layer
- Browser · User-facing entry point
Frontend
Streamlit presentation layer
Backend
FastAPI application and domain logic
- API entry · Backend container and application entrypoint
backend/main.py - API app · Main FastAPI application and route wiring
backend/app/app.py - Auth & users · Registration, login, JWT auth, and user management
backend/app/users.py - Media service · Upload handling and ImageKit integration
backend/app/images.py - Data layer · Async database and ORM/session setup
backend/app/db.py - Schemas · Request and response models
backend/app/schemas.py
Infrastructure
Terraform-managed cloud and deployment stack
- Terraform · Source of truth for AWS and Kubernetes deployment
terraform/main.tf - K8s stack · Terraform-managed Kubernetes workloads, services, and ingress
terraform/k8s.tf - Cleaner · Automated cleanup workflow and supporting resources
terraform/cleaner.tf - K8s manifests · Reference manifests kept alongside Terraform-managed deployment
k8s/ingress.yaml - EKS · Execution environment for application containers
- VPC · Cloud network boundary for the stack
External
Managed services used by the system
- MySQL · Primary relational datastore for app state
- ImageKit · External media hosting and asset delivery
- Load balancer · Ingress exposure for the cluster
Connections 22
- 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