How arctikant/fastapi-modular-monolith-starter-kit works
Project type and purpose
• This is a modular-monolith REST API starter kit built on FastAPI.
• It follows a layered architecture (presentation → service → repository) and a modular approach (each feature/module under its own app/<module>).
Main components
a. Clients & Entry Points
• External HTTP clients (browsers, mobile apps, services)
• docker-compose environment (app container)
b. API Layer (Presentation)
• FastAPI Application (app/main.py)
• Core router (app/core/routers.py)
• Module routers (e.g. app/auth/routes/v1/...)
• Rate Limiter (fastapi-limiter + Redis)
c. Business Logic Layer
• Services in each module (app/auth/services, app/core/services/...)
• Policies & Gateways (sync cross-module calls, e.g. AuthGateway)
• Event dispatch & listeners (fastapi-events)
d. Data Access Layer
• Repositories (app/auth/repositories, app/core/db/base_repository.py)
• SQLAlchemy AsyncSession (app/core/db/session.py)
• Migrations (Alembic: alembic.ini, migrations/)
e. Shared Core Services
• CacheService (aiocache + Redis)
• QueueService (Taskiq + Redis broker)
• MailService (aiosmtplib + MailHog)
• LogService (structlog)
• EventService (fastapi-events)
f. Persistence & External Systems
• PostgreSQL (app container → docker/db/init_scripts)
• Redis (cache, rate limiter, queue)
• SMTP server (MailHog)
g. Infrastructure & Tooling
• Docker / docker-compose
• .env / config system
• CI/testing tools (pytest, factories, coverage)
Relationships and interactions
• HTTP Request → FastAPI App → Core Router → Module Router
• Router → Service (via FastAPI DI)
• Service → Repository + AsyncSession → PostgreSQL
• Service ↔ Core Services:
• CacheService (get/set/delete) → Redis
• QueueService.push(...) → Redis broker → Worker
• MailService.send/queue → aiosmtplib → MailHog or Queue
• EventService.dispatch(...) → Event Bus → Listeners
• Gateway dependencies provide sync cross-module calls (e.g. other modules inject AuthGateway).
• Rate Limiter applied at router level (ConfigurableRateLimiter → Redis).
• All database models feed into Alembic for migrations.
Architectural patterns and design principles
• Layered Architecture: Presentation → Service → Repository → Database
• Modular Monolith: features are self-contained modules under app/<module>
• Dependency Injection: FastAPI’s DI system resolves services, session, gateways
• Asynchronous I/O: all external comms (DB, Redis, SMTP) use async libraries
• Separation of Concerns: each core cross-cutting concern (cache, queue, mail, events, logging) lives in its own provider under app/core/services
• Gateways & Events: allow easy transition to microservices in the future
Emphasize
• Detail each major class or folder as a component.
• Essential interactions (DB, cache, queue, mail, events, rate-limiter).
• Keep the modular boundaries explicit: core vs module vs external infra.