# fastapi-practices/fastapi-best-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/fastapi-practices/fastapi-best-architecture
- Repository: https://github.com/fastapi-practices/fastapi-best-architecture

## Overview

FastAPI Best Architecture is an enterprise backend framework organized in API, schema, service, CRUD, and model layers. Its main user workflow is an administrator request entering the application router, passing through an API endpoint and business service to persistent data, then returning a response. The repository also provides authentication and access control, task scheduling and results, plugin-based capabilities, and shared runtime infrastructure. Layer relationships follow the README’s documented architecture; several feature branches are visible in the tree but were not sampled, so their internal wiring is not asserted.

Main entry points: [`backend/app/router.py`](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/router.py) (Application router), [`backend/app/admin/service/auth_service.py`](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/admin/service/auth_service.py) (Authentication service), [`backend/app/admin/api`](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/api) (Admin APIs), [`backend/app/task/api`](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/task/api) (Task APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and administration"]
  node_app["Application router<br/>[router.py]"]
  node_admin_api["Admin APIs"]
  node_auth_api["Authentication API"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_access["Access control"]
  node_admin_service["Admin services"]
  node_admin_crud["Admin CRUD"]
  node_admin_models["Admin models"]
end

subgraph group_tasks["Task execution"]
  node_task_api["Task APIs"]
  node_scheduler_service["Scheduler service"]
  node_scheduler_crud["Scheduler CRUD<br/>[crud_scheduler.py]"]
  node_scheduler_model["Scheduler model<br/>[scheduler.py]"]
  node_celery["Celery workers<br/>[celery.py]"]
  node_task_actions["Task actions<br/>[actions.py]"]
  node_result_api["Result API<br/>[result.py]"]
  node_result_service["Result service<br/>[result_service.py]"]
end

subgraph group_plugins["Plugins and extensions"]
  node_plugin_router["Plugin router<br/>[router.py]"]
  node_plugin_modules["Plugin capabilities"]
  node_codegen["Code generator"]
  node_oauth["Social login"]
end

subgraph group_runtime["Shared runtime"]
  node_sql_db[("SQL database")]
  node_redis[("Redis<br/>[redis.py]")]
  node_socketio["Live connections<br/>[server.py]"]
  node_middleware["Request middleware"]
  node_entry["Service startup<br/>[main.py]"]
end

node_admin(("Administrator"))

node_admin -->|"sends request"| node_app
node_app -->|"routes requests"| node_admin_api
node_admin_api -->|"routes login"| node_auth_api
node_auth_api -->|"invokes login"| node_auth_service
node_auth_service -->|"creates tokens"| node_access
node_auth_service -->|"reads user/menu"| node_admin_crud
node_admin_api -->|"invokes services"| node_admin_service
node_admin_service -->|"uses data access"| node_admin_crud
node_admin_crud -->|"queries models"| node_admin_models
node_admin_models -->|"persists data"| node_sql_db
node_app -->|"routes requests"| node_task_api
node_task_api -->|"manages schedules"| node_scheduler_service
node_scheduler_service -->|"reads/writes schedules"| node_scheduler_crud
node_scheduler_crud -->|"queries models"| node_scheduler_model
node_scheduler_service -->|"dispatches task"| node_celery
node_celery -->|"executes tasks"| node_task_actions
node_task_api -->|"routes result requests"| node_result_api
node_result_api -->|"retrieves results"| node_result_service
node_app -->|"includes extensions"| node_plugin_router
node_plugin_router -->|"injects routes"| node_plugin_modules
node_plugin_modules -.->|"includes capability"| node_codegen
node_plugin_modules -.->|"includes capability"| node_oauth
node_oauth -->|"uses state storage"| node_redis
node_auth_service -->|"uses token storage"| node_redis
node_socketio -->|"validates tokens"| node_access
node_socketio -->|"tracks sessions"| node_redis
node_entry -->|"registers application"| node_app
node_app -->|"processes requests"| node_middleware

click node_app "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/router.py"
click node_admin_api "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/api"
click node_auth_api "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/api/v1/auth"
click node_auth_service "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/admin/service/auth_service.py"
click node_access "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/common/security"
click node_admin_service "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/service"
click node_admin_crud "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/crud"
click node_admin_models "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/model"
click node_task_api "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/task/api"
click node_scheduler_service "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/service/scheduler_service.py"
click node_scheduler_crud "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/crud/crud_scheduler.py"
click node_scheduler_model "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/model/scheduler.py"
click node_celery "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/celery.py"
click node_task_actions "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/actions.py"
click node_result_api "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/api/v1/result.py"
click node_result_service "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/service/result_service.py"
click node_plugin_router "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/plugin/router.py"
click node_plugin_modules "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/plugin"
click node_codegen "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/plugin/code_generator/service/code_gen_service.py"
click node_oauth "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/plugin/oauth2"
click node_redis "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/database/redis.py"
click node_socketio "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/common/socketio/server.py"
click node_middleware "https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/middleware"
click node_entry "https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/main.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_admin_api,node_auth_api,node_auth_service,node_access,node_admin_service,node_admin_crud,node_admin_models toneBlue
class node_task_api,node_scheduler_service,node_scheduler_crud,node_scheduler_model,node_celery,node_task_actions,node_result_api,node_result_service toneAmber
class node_plugin_router,node_plugin_modules,node_codegen,node_oauth toneMint
class node_sql_db,node_redis,node_socketio,node_middleware,node_entry toneRose
class node_admin toneIndigo
```

## Components

### Request and administration

- [Application router](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/router.py): `backend/app/router.py`
- [Admin APIs](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/api): `backend/app/admin/api`
- [Authentication API](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/api/v1/auth): `backend/app/admin/api/v1/auth`
- [Authentication service](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/admin/service/auth_service.py): `backend/app/admin/service/auth_service.py`
- [Access control](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/common/security): `backend/common/security`
- [Admin services](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/service): `backend/app/admin/service`
- [Admin CRUD](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/crud): `backend/app/admin/crud`
- [Admin models](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/admin/model): `backend/app/admin/model`

### Task execution

- [Task APIs](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/app/task/api): `backend/app/task/api`
- [Scheduler service](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/service/scheduler_service.py): `backend/app/task/service/scheduler_service.py`
- [Scheduler CRUD](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/crud/crud_scheduler.py): `backend/app/task/crud/crud_scheduler.py`
- [Scheduler model](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/model/scheduler.py): `backend/app/task/model/scheduler.py`
- [Celery workers](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/celery.py): `backend/app/task/celery.py`
- [Task actions](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/actions.py): `backend/app/task/actions.py`
- [Result API](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/api/v1/result.py): `backend/app/task/api/v1/result.py`
- [Result service](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/app/task/service/result_service.py): `backend/app/task/service/result_service.py`

### Plugins and extensions

- [Plugin router](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/plugin/router.py): `backend/plugin/router.py`
- [Plugin capabilities](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/plugin): `backend/plugin`
- [Code generator](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/plugin/code_generator/service/code_gen_service.py): `backend/plugin/code_generator/service/code_gen_service.py`
- [Social login](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/plugin/oauth2): `backend/plugin/oauth2`

### Shared runtime

- **SQL database**
- [Redis](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/database/redis.py): `backend/database/redis.py`
- [Live connections](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/common/socketio/server.py): `backend/common/socketio/server.py`
- [Request middleware](https://github.com/fastapi-practices/fastapi-best-architecture/tree/master/backend/middleware): `backend/middleware`
- [Service startup](https://github.com/fastapi-practices/fastapi-best-architecture/blob/master/backend/main.py): `backend/main.py`

### Other components

- **Administrator**

## Connections

- Administrator → Application router: sends request
- Application router → Admin APIs: routes requests
- Admin APIs → Authentication API: routes login
- Authentication API → Authentication service: invokes login
- Authentication service → Access control: creates tokens
- Authentication service → Admin CRUD: reads user/menu
- Admin APIs → Admin services: invokes services
- Admin services → Admin CRUD: uses data access
- Admin CRUD → Admin models: queries models
- Admin models → SQL database: persists data
- Application router → Task APIs: routes requests
- Task APIs → Scheduler service: manages schedules
- Scheduler service → Scheduler CRUD: reads/writes schedules
- Scheduler CRUD → Scheduler model: queries models
- Scheduler service → Celery workers: dispatches task
- Celery workers → Task actions: executes tasks
- Task APIs → Result API: routes result requests
- Result API → Result service: retrieves results
- Application router → Plugin router: includes extensions
- Plugin router → Plugin capabilities: injects routes
- Plugin capabilities → Code generator: includes capability
- Plugin capabilities → Social login: includes capability
- Social login → Redis: uses state storage
- Authentication service → Redis: uses token storage
- Live connections → Access control: validates tokens
- Live connections → Redis: tracks sessions
- Service startup → Application router: registers application
- Application router → Request middleware: processes requests