How arunkumar237/fastapi-marketplace works
What this project is (type + purpose inferred)
From the structure, this is a Python FastAPI backend service intended to power a “marketplace” API (the README is minimal, so the “marketplace” domain isn’t described, but the technical architecture is clear).
Key indicators:
• app/main.py, app/routers/*, app/router/*: typical FastAPI app entrypoint + route modules.
• app/models/*, app/database.py, alembic/*: SQLAlchemy-style persistence with Alembic migrations.
• docker-compose.yml: local/deploy composition likely including an RDBMS container + API container.
• .env.example, app/config.py: environment-based configuration.
• HTTP API layer (FastAPI)
• Application modules (routers, exception handling, config)
• Persistence layer (SQLAlchemy + DB)
• Migration workflow (Alembic)
• Deployment topology (Docker Compose)
Top-level runtime + packaging
• main.py (root) and app/main.py
• pyproject.toml, uv.lock, .python-version
Configuration
• .env.example, app/config.py
• This suggests an env-driven configuration layer (likely Pydantic settings).
Database + migrations
• app/database.py
• DB engine/session creation (SQLAlchemy).
• app/models/base.py, app/models/__init__.py
• ORM base + model registration.
• alembic.ini, alembic/env.py, alembic/versions/*
• Migration tooling and version scripts.
Routing / API surface
• app/routers/health.py and also app/router/health.py (plus app/router vs app/routers)
• app/exception_handler.py, app/exceptions.py
• Centralized exception types + handlers, likely registered on FastAPI app startup. Represent as middleware/handler layer inside the API.
Client(s)
• Browser, mobile app, other service, curl, etc.
FastAPI Application (API Service)
• Entry: app/main.py (and/or root main.py)
• Routers: app/routers/* (health endpoint etc.)
• Exception Handling: app/exception_handler.py, app/exceptions.py
• Config loader: app/config.py
Database Access Layer
• app/database.py (engine/session/connection pool)
• ORM models: app/models/*
Relational Database (RDBMS)
• Not shown in tree, but implied by Alembic + docker-compose (commonly Postgres). Confirm via docker-compose.yml.
• Client → FastAPI (HTTP request)
• FastAPI Routers → Database layer (CRUD/query)
• Database layer ↔ RDBMS (SQL)
• FastAPI → Client (HTTP response)
• FastAPI ↔ Exception handlers (error path)
Alembic Migration Workflow
• “Developer/CI runs alembic upgrade head” (or container entrypoint runs it)
• Alembic → RDBMS (DDL migrations)
• Alembic reads ORM metadata / model base via alembic/env.py integration (common pattern)
• Operator/CI → Alembic CLI
• Alembic → DB (apply migrations)
• Alembic ↔ Models metadata (imports from app/models and DB config)
Docker Compose Topology
• API container (FastAPI app)
• DB container (Postgres/MySQL/etc.)
• Optional: migration job container (sometimes same as API image, different command)
• Layered architecture:
• Presentation/API layer: FastAPI routers
• Domain/data layer: ORM models
• Infrastructure: DB connection management, config, exception handling
• Configuration via environment:
• .env.example → actual .env → app/config.py
• Schema migration as first-class:
• Alembic versioned migrations (alembic/versions/*)
• Modular routing:
• app/routers suggests endpoints are organized by feature/module.
A structural oddity worth annotating:
• Both app/router and app/routers exist, with health.py in both.
Logical Architecture (C4 Container-level)
• Client
• FastAPI API Service
• Database
• (Optional) External services (none visible in tree)
FastAPI Service Internal View (C4 Component-level)
• main.py / app creation
• Routers (app/routers/*)
• Exception handling (app/exception_handler.py, app/exceptions.py)
• Config (app/config.py)
• DB module (app/database.py)
• Models (app/models/*)
Deployment / Ops View
• Docker Compose: API container + DB container
• Migration execution path (Alembic job/command)
• Env vars injection
• Clear labels:
• “FastAPI API Service (ASGI)”
• “Routers: health + others”
• “DB Session/Engine (SQLAlchemy)”
• “RDBMS (e.g., Postgres)”
• “Alembic migrations”
• Rectangles: runtime services (API, DB)
• Rounded rectangles: internal modules/components (routers, db.py, config.py)
• Hexagon/parallelogram: tooling/ops (Alembic, CI)
• API Entrypoint / App Composition
• app/main.py
• main.py (root) (runner/alias—confirm)
• Routing Layer
• app/routers/__init__.py
• app/routers/health.py
• (Potential duplicate) app/router/health.py
• Error Handling
• app/exceptions.py
• app/exception_handler.py
• Configuration
• app/config.py
• .env.example
• Persistence
• app/database.py
• app/models/base.py
• app/models/__init__.py
• Schema Migration
• alembic.ini
• alembic/env.py
• alembic/versions/bd59657022d3_initial_migration.py
• Deployment
• docker-compose.yml
Practical advice to “separate into as many components as possible” (without overthinking)
Within the FastAPI service boundary, break components into:
• App bootstrap (creates FastAPI instance, registers routers/handlers)
• Router modules (one per file: health, future marketplace endpoints)
• Config module (settings object + env resolution)
• DB module (engine/session factory)
• Models (Base + entity models)
Outside the service boundary, break into:
• Database service
• Migration toolchain (Alembic)
• Execution environment (Docker Compose / containers)