# alamarnissi/fastapi-saas-template architecture

> Architecture diagram of the GitHub repository alamarnissi/fastapi-saas-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alamarnissi/fastapi-saas-template
- Repository: https://github.com/alamarnissi/fastapi-saas-template

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (e.g. Postman, Web Frontend)"]:::http

    subgraph "Web Server\n(Uvicorn + FastAPI)"
        Main["src/app/main.py"]:::http
        Config["src/app/config.py"]:::http
        CeleryJobs["src/app/celery_jobs.py"]:::http

        subgraph "Routers"
            AuthRouter["Auth Router"]:::http
            OrgRouter["Org Router"]:::http
        end

        subgraph "Services"
            AuthService["Auth Service"]:::http
            OrgService["Org Service"]:::http
        end

        subgraph "Repositories"
            AuthRepo["Auth Repository"]:::http
            OrgRepo["Org Repository"]:::http
        end

        subgraph "Utilities"
            DBUtils["db_utils.py"]:::http
            MailerUtil["mailer_util.py"]:::http
            ModelsUtils["models_utils.py"]:::http
            SchemasUtils["schemas_utils.py"]:::http
            Slugger["slugger.py"]:::http
            Token["token.py"]:::http
        end

        AuthModels["src/auth/models.py"]:::http
        AuthSchemas["src/auth/schemas.py"]:::http
        OAuthLogic["src/auth/oauth.py"]:::http

        OrgModels["src/organization/models.py"]:::http
        OrgSchemas["src/organization/schemas.py"]:::http
        OrgDeps["src/organization/pipes/org_dep.py"]:::http
        OrgPermissions["src/permissions/org_permissions.py"]:::http

        Templates["src/templates/user/verification.html"]:::http
    end

    subgraph "Background Worker"
        CeleryWorker["Celery Worker"]:::http
    end

    subgraph "Data Stores"
        DatabaseSetup["src/app/database.py"]:::db
        Postgres["PostgreSQL"]:::db
        Broker["Message Broker (Redis/RabbitMQ)"]:::db
        AlembicIni["alembic.ini"]:::db
        Migrations["src/migrations/"]:::db
    end

    subgraph "External Services"
        SMTP["SMTP / Email"]:::ext
        OAuthProvider["OAuth Providers"]:::ext
    end

    %% Connections
    Client -->|"HTTP Request"| Main
    Main --> AuthRouter
    Main --> OrgRouter
    AuthRouter --> AuthService
    OrgRouter --> OrgService
    AuthService --> AuthRepo
    OrgService --> OrgRepo
    AuthRepo --> DatabaseSetup
    OrgRepo --> DatabaseSetup
    DatabaseSetup --> Postgres
    AuthService -->|push task| Broker
    OrgService -->|push task| Broker
    Broker -.->|async task| CeleryWorker
    CeleryWorker --> MailerUtil
    CeleryWorker --> SMTP
    AuthRouter --> OAuthLogic
    OAuthLogic <--> OAuthProvider
    OrgRouter --> OrgDeps
    OrgRouter --> OrgPermissions

    %% Click Events
    click Main "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/main.py"
    click Config "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/config.py"
    click DatabaseSetup "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/database.py"
    click AlembicIni "https://github.com/alamarnissi/fastapi-saas-template/blob/main/alembic.ini"
    click Migrations "https://github.com/alamarnissi/fastapi-saas-template/tree/main/src/migrations/"
    click CeleryJobs "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/celery_jobs.py"
    click DBUtils "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/db_utils.py"
    click MailerUtil "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/mailer_util.py"
    click ModelsUtils "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/models_utils.py"
    click SchemasUtils "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/schemas_utils.py"
    click Slugger "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/slugger.py"
    click Token "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/app/utils/token.py"
    click AuthRouter "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/auth_router.py"
    click AuthService "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/auth_service.py"
    click AuthRepo "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/auth_repository.py"
    click AuthModels "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/models.py"
    click AuthSchemas "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/schemas.py"
    click OAuthLogic "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/auth/oauth.py"
    click OrgRouter "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/org_router.py"
    click OrgService "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/org_service.py"
    click OrgRepo "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/org_repository.py"
    click OrgModels "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/models.py"
    click OrgSchemas "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/schemas.py"
    click OrgDeps "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/organization/pipes/org_dep.py"
    click OrgPermissions "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/permissions/org_permissions.py"
    click Templates "https://github.com/alamarnissi/fastapi-saas-template/blob/main/src/templates/user/verification.html"

    %% Styles
    classDef http fill:#E3F2FD,stroke:#90CAF9
    classDef db fill:#E8F5E9,stroke:#66BB6A
    classDef ext fill:#FFF3E0,stroke:#FFA726
```
