# qimolin/fastapi-multi-tenancy architecture

> Architecture diagram of the GitHub repository qimolin/fastapi-multi-tenancy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qimolin/fastapi-multi-tenancy
- Repository: https://github.com/qimolin/fastapi-multi-tenancy

## Overview

This is a FastAPI starter template for tenant-isolated applications. The main workflow creates a tenant and owner, authenticates users to issue tenant-bearing JWTs, then applies authenticated requests under PostgreSQL row-level security; tenant admins can manage users, and the example domain demonstrates tenant-scoped CRUD. Redis stores refresh-token state, while audit logging and health checks support operations. The README documents PostgreSQL RLS and the example CRUD capability; their implementation details are not fully sampled, so uncertain internal wiring is omitted.

Main entry points: [`src/main.py`](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/main.py) (FastAPI app), [`src/auth/service.py`](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/service.py) (Auth service), [`src/tenants/router.py`](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/router.py) (Tenant endpoints), [`src/auth/router.py`](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/router.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["API and middleware"]
  node_app["FastAPI app<br/>[main.py]"]
  node_correlation["Correlation IDs<br/>[middleware.py]"]
  node_handlers["Error handlers"]
end

subgraph group_tenant["Tenant management"]
  node_tenant_router["Tenant endpoints<br/>[router.py]"]
  node_tenant_service["Tenant service<br/>[service.py]"]
  node_tenant_model["Tenant model<br/>[models.py]"]
end

subgraph group_auth["Authentication and RBAC"]
  node_auth_router["Auth endpoints<br/>[router.py]"]
  node_auth_service["Auth service<br/>[service.py]"]
  node_auth_dependencies["Auth and roles<br/>[dependencies.py]"]
  node_auth_utils["Token and passwords<br/>[utils.py]"]
  node_user_model["User model<br/>[models.py]"]
end

subgraph group_domain["Example domain"]
  node_example_router["Example endpoints<br/>[router.py]"]
  node_example_service["Example CRUD<br/>[service.py]"]
  node_example_model["Post model<br/>[models.py]"]
end

subgraph group_data["Persistence and operations"]
  node_database["DB sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_audit["Audit logging<br/>[utils.py]"]
  node_health["Health endpoint<br/>[router.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"processes through"| node_correlation
node_app -->|"dispatches"| node_tenant_router
node_app -->|"dispatches"| node_auth_router
node_app -->|"dispatches"| node_example_router
node_app -->|"dispatches"| node_health
node_app -->|"registers"| node_handlers
node_tenant_router -->|"creates tenant"| node_tenant_service
node_tenant_router -->|"creates owner"| node_auth_service
node_tenant_router -->|"sets tenant context"| node_database
node_tenant_service -->|"persists"| node_tenant_model
node_tenant_router -->|"logs events"| node_audit
node_auth_router -->|"authenticates and issues tokens"| node_auth_service
node_auth_router -->|"requires user or admin"| node_auth_dependencies
node_auth_router -->|"queries users"| node_database
node_auth_router -->|"logs events"| node_audit
node_auth_service -->|"hashes and signs"| node_auth_utils
node_auth_service -->|"reads and creates"| node_user_model
node_auth_service -->|"stores refresh tokens"| node_redis
node_auth_dependencies -->|"decodes tokens"| node_auth_utils
node_auth_dependencies -->|"sets RLS context"| node_database
node_auth_dependencies -->|"loads user"| node_auth_service
node_example_router -->|"calls CRUD"| node_example_service
node_example_router -->|"requires authentication"| node_auth_dependencies
node_example_service -->|"queries and persists"| node_example_model
node_example_service -->|"uses session"| node_database
node_database -->|"executes queries"| node_postgres
node_health -->|"checks connectivity"| node_postgres
node_health -->|"checks connectivity"| node_redis

click node_app "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/main.py"
click node_correlation "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/middleware.py"
click node_handlers "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/exception_handlers.py"
click node_tenant_router "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/router.py"
click node_tenant_service "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/service.py"
click node_tenant_model "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/models.py"
click node_auth_router "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/router.py"
click node_auth_service "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/service.py"
click node_auth_dependencies "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/dependencies.py"
click node_auth_utils "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/utils.py"
click node_user_model "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/models.py"
click node_example_router "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/router.py"
click node_example_service "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/service.py"
click node_example_model "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/models.py"
click node_database "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/database.py"
click node_audit "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/audit/utils.py"
click node_health "https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/health/router.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_correlation,node_handlers,node_client toneBlue
class node_tenant_router,node_tenant_service,node_tenant_model toneAmber
class node_auth_router,node_auth_service,node_auth_dependencies,node_auth_utils,node_user_model toneMint
class node_example_router,node_example_service,node_example_model toneRose
class node_database,node_postgres,node_redis,node_audit,node_health toneIndigo
```

## Components

### API and middleware

- [FastAPI app](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/main.py): `src/main.py`
- [Correlation IDs](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/middleware.py): `src/middleware.py`
- [Error handlers](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/exception_handlers.py): `src/exception_handlers.py`

### Tenant management

- [Tenant endpoints](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/router.py): `src/tenants/router.py`
- [Tenant service](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/service.py): `src/tenants/service.py`
- [Tenant model](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/tenants/models.py): `src/tenants/models.py`

### Authentication and RBAC

- [Auth endpoints](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/router.py): `src/auth/router.py`
- [Auth service](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/service.py): `src/auth/service.py`
- [Auth and roles](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/dependencies.py): `src/auth/dependencies.py`
- [Token and passwords](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/utils.py): `src/auth/utils.py`
- [User model](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/auth/models.py): `src/auth/models.py`

### Example domain

- [Example endpoints](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/router.py): `src/example/router.py`
- [Example CRUD](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/service.py): `src/example/service.py`
- [Post model](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/example/models.py): `src/example/models.py`

### Persistence and operations

- [DB sessions](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/database.py): `src/database.py`
- **PostgreSQL**
- **Redis**
- [Audit logging](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/audit/utils.py): `src/audit/utils.py`
- [Health endpoint](https://github.com/qimolin/fastapi-multi-tenancy/blob/main/src/health/router.py): `src/health/router.py`

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → Correlation IDs: processes through
- FastAPI app → Tenant endpoints: dispatches
- FastAPI app → Auth endpoints: dispatches
- FastAPI app → Example endpoints: dispatches
- FastAPI app → Health endpoint: dispatches
- FastAPI app → Error handlers: registers
- Tenant endpoints → Tenant service: creates tenant
- Tenant endpoints → Auth service: creates owner
- Tenant endpoints → DB sessions: sets tenant context
- Tenant service → Tenant model: persists
- Tenant endpoints → Audit logging: logs events
- Auth endpoints → Auth service: authenticates and issues tokens
- Auth endpoints → Auth and roles: requires user or admin
- Auth endpoints → DB sessions: queries users
- Auth endpoints → Audit logging: logs events
- Auth service → Token and passwords: hashes and signs
- Auth service → User model: reads and creates
- Auth service → Redis: stores refresh tokens
- Auth and roles → Token and passwords: decodes tokens
- Auth and roles → DB sessions: sets RLS context
- Auth and roles → Auth service: loads user
- Example endpoints → Example CRUD: calls CRUD
- Example endpoints → Auth and roles: requires authentication
- Example CRUD → Post model: queries and persists
- Example CRUD → DB sessions: uses session
- DB sessions → PostgreSQL: executes queries
- Health endpoint → PostgreSQL: checks connectivity
- Health endpoint → Redis: checks connectivity