How alamarnissi/fastapi-saas-template works
Project type and purpose
• This is a full-stack (API-only) SaaS template built with FastAPI. Its primary goal is to provide a Subscription-as-a-Service scaffold with user authentication, multi-organization support, invitation flows, and permission checks (including freemium limits).
File structure
• Top level:
• Dockerfile, .env example, Alembic config, requirements, migrations directory
• src/app: app entrypoint (main.py), config, database setup, Celery jobs, utilities
• src/auth: authentication routers, services, repositories, OAuth logic, schemas
• src/organization: organization routers, services, repositories, pipes (dependencies), schemas
• src/permissions: reusable permission dependencies (e.g. freemium checks)
• src/templates: HTML email templates
• src/tests: pytest test suites for auth and organization flows
• Patterns:
• Layered (Router → Service → Repository → Database)
• Dependency injection via FastAPI’s Depends
• Background job queue (Celery) for async tasks (e.g., sending emails)
• Alembic for migrations
Key insights from README
• Core modules: User Auth and Organizations (teams, invites)
• Permissions enforce admin vs. member vs. freemium limits
• Uses Postgres (via SQLAlchemy), Alembic, Celery (with a broker), mailer, OAuth
Main components and relationships
a. Components
• Client (e.g. Postman, Web Frontend)
• API Server (Uvicorn + FastAPI)
– Routers: auth_router, org_router
– Services: auth_service, org_service
– Repositories: auth_repository, org_repository
– Utils: token, slugger, mailer_util, db_utils, schemas_utils, models_utils
• Database (PostgreSQL) + Alembic migrations
• Background Worker (Celery) + Message Broker (e.g. Redis/RabbitMQ)
• External Services: SMTP/Email, OAuth Providers (Google/GitHub, etc.)
b. Interactions
1. Client → HTTP request → FastAPI Uvicorn server
2. Router receives request → calls Service → queries/updates DB via Repository
3. Service may push tasks to Celery (e.g. send invite email)
4. Celery worker consumes task, uses mailer_util or other utils → sends email/external calls
5. Alembic handles schema migrations at deploy time
6. OAuth endpoints redirect to external providers → callback → auth flow
c. Architectural patterns
• Layered Clean Architecture (Router/Controller → Service/Use-case → Repository/DB)
• Dependency-injection for config, database, permissions
• Asynchronous background processing (Celery) for non-blocking tasks
• DB Schema versioning with Alembic
d. Technologies & frameworks
• FastAPI/Uvicorn (HTTP server)
• SQLAlchemy + Alembic (ORM & migrations)
• Celery + Broker (Redis/RabbitMQ)
• Pydantic schemas for request/response validation
• OAuth integration
• pytest for tests