# 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-10-01). 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 around a three-tier API/schema/service/CRUD/model structure. Its main request path begins at the HTTP API and returns a response; authentication verifies JWTs and loads user state. Major product branches include administration, asynchronous scheduled tasks, and dynamically routed plugins for code generation, configuration, dictionaries, email, notices, and OAuth2. The graph also shows shared runtime infrastructure. Some subsystem routes and calls are unsampled, so uncertain links are omitted or marked unverified.

Main entry points: [`backend/plugin/router.py`](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/router.py) (Plugin routing), [`backend/common/security/jwt.py`](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/security/jwt.py) (JWT security), [`backend/app/admin/api`](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/admin/api) (Admin API), [`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)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["App startup<br/>[main.py]"]
  node_app_router["App routes<br/>[router.py]"]
  node_plugin_router["Plugin routing<br/>[router.py]"]
end

subgraph group_admin["Administration"]
  node_admin_api["Admin API"]
  node_admin_auth["Authentication<br/>[auth_service.py]"]
  node_user_crud["User access<br/>[crud_user.py]"]
  node_user_schema["User schemas<br/>[user.py]"]
  node_admin_domains["Admin domains"]
end

subgraph group_tasks["Background tasks"]
  node_task_api["Task API"]
  node_scheduler["Scheduler service"]
  node_task_store[("Task database<br/>[database.py]")]
  node_celery["Task execution<br/>[celery.py]"]
end

subgraph group_plugins["Plugin capabilities"]
  node_codegen["Code generation"]
  node_config_plugin["Configuration plugin"]
  node_dict_plugin["Dictionary plugin"]
  node_email_plugin["Email plugin"]
  node_notice_plugin["Notice plugin<br/>[notice_service.py]"]
  node_oauth_plugin["OAuth2 plugin<br/>[oauth2_service.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_jwt["JWT security<br/>[jwt.py]"]
  node_settings["Settings<br/>[conf.py]"]
  node_redis[("Redis client<br/>[redis.py]")]
  node_context["Request context<br/>[context.py]"]
  node_observability["Metrics<br/>[fastapi.py]"]
  node_shared_utils["Shared utilities"]
  node_shared_types["Shared types<br/>[enums.py]"]
  node_logging["Logging<br/>[log.py]"]
end

node_client(("API client"))

node_client -.->|"sends requests"| node_admin_api
node_admin_api -.->|"authenticates"| node_admin_auth
node_admin_auth -.->|"issues tokens"| node_jwt
node_jwt -->|"loads users"| node_user_crud
node_jwt -->|"checks token state"| node_redis
node_jwt -->|"validates user data"| node_user_schema
node_admin_auth -->|"accesses users"| node_user_crud
node_admin_auth -->|"uses schemas"| node_user_schema
node_admin_api -->|"registers metrics"| node_observability
node_admin_api -->|"routes domains"| node_admin_domains
node_main -->|"initializes plugins"| node_plugin_router
node_plugin_router -->|"registers routes"| node_app_router
node_plugin_router -.->|"routes capability"| node_codegen
node_plugin_router -.->|"routes capability"| node_config_plugin
node_plugin_router -.->|"routes capability"| node_dict_plugin
node_plugin_router -.->|"routes capability"| node_email_plugin
node_plugin_router -.->|"routes capability"| node_notice_plugin
node_plugin_router -.->|"routes capability"| node_oauth_plugin
node_task_api -.->|"handles schedules"| node_scheduler
node_scheduler -->|"dispatches tasks"| node_celery
node_scheduler -.->|"accesses persistence"| node_task_store
node_task_api -->|"registers metrics"| node_observability
node_settings -->|"configures client"| node_redis
node_settings -->|"configures metrics"| node_observability
node_jwt -->|"sets identity"| node_context
node_logging -->|"reads configuration"| node_settings
node_logging -->|"uses timezone utilities"| node_shared_utils

click node_main "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/main.py"
click node_app_router "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/router.py"
click node_plugin_router "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/router.py"
click node_admin_api "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/admin/api"
click node_admin_auth "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/service/auth_service.py"
click node_jwt "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/security/jwt.py"
click node_user_crud "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/crud/crud_user.py"
click node_user_schema "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/schema/user.py"
click node_admin_domains "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/admin"
click node_task_api "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/task/api"
click node_scheduler "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/task/service/scheduler_service.py"
click node_task_store "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/task/database.py"
click node_celery "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/task/celery.py"
click node_codegen "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/code_generator/service/code_gen_service.py"
click node_config_plugin "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/plugin/config"
click node_dict_plugin "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/dict/service/dict_data_service.py"
click node_email_plugin "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/plugin/email"
click node_notice_plugin "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/notice/service/notice_service.py"
click node_oauth_plugin "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/oauth2/service/oauth2_service.py"
click node_settings "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/core/conf.py"
click node_redis "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/database/redis.py"
click node_context "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/context.py"
click node_observability "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/observability/prometheus/fastapi.py"
click node_shared_utils "https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/utils"
click node_shared_types "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/enums.py"
click node_logging "https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/log.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_main,node_app_router,node_plugin_router,node_client toneBlue
class node_admin_api,node_admin_auth,node_user_crud,node_user_schema,node_admin_domains toneAmber
class node_task_api,node_scheduler,node_task_store,node_celery toneMint
class node_codegen,node_config_plugin,node_dict_plugin,node_email_plugin,node_notice_plugin,node_oauth_plugin toneRose
class node_jwt,node_settings,node_redis,node_context,node_observability,node_shared_utils,node_shared_types,node_logging toneIndigo
```

## Components

### Application entry

- [App startup](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/main.py): `backend/main.py`
- [App routes](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/router.py): `backend/app/router.py`
- [Plugin routing](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/router.py): `backend/plugin/router.py`

### Administration

- [Admin API](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/admin/api): `backend/app/admin/api`
- [Authentication](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/service/auth_service.py): `backend/app/admin/service/auth_service.py`
- [User access](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/crud/crud_user.py): `backend/app/admin/crud/crud_user.py`
- [User schemas](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/admin/schema/user.py): `backend/app/admin/schema/user.py`
- [Admin domains](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/app/admin): `backend/app/admin`

### Background tasks

- [Task API](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`
- [Task database](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/task/database.py): `backend/app/task/database.py`
- [Task execution](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/app/task/celery.py): `backend/app/task/celery.py`

### Plugin capabilities

- [Code generation](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`
- [Configuration plugin](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/plugin/config): `backend/plugin/config`
- [Dictionary plugin](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/dict/service/dict_data_service.py): `backend/plugin/dict/service/dict_data_service.py`
- [Email plugin](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/plugin/email): `backend/plugin/email`
- [Notice plugin](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/notice/service/notice_service.py): `backend/plugin/notice/service/notice_service.py`
- [OAuth2 plugin](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/plugin/oauth2/service/oauth2_service.py): `backend/plugin/oauth2/service/oauth2_service.py`

### Shared runtime

- [JWT security](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/security/jwt.py): `backend/common/security/jwt.py`
- [Settings](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/core/conf.py): `backend/core/conf.py`
- [Redis client](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/database/redis.py): `backend/database/redis.py`
- [Request context](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/context.py): `backend/common/context.py`
- [Metrics](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/observability/prometheus/fastapi.py): `backend/common/observability/prometheus/fastapi.py`
- [Shared utilities](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/utils): `backend/utils`
- [Shared types](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/enums.py): `backend/common/enums.py`
- [Logging](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/backend/common/log.py): `backend/common/log.py`

### Other components

- **API client**

## Connections

- API client → Admin API: sends requests (evidence: `README.md`)
- Admin API → Authentication: authenticates
- Authentication → JWT security: issues tokens (evidence: `backend/app/admin/service/auth_service.py`)
- JWT security → User access: loads users (evidence: `backend/common/security/jwt.py`)
- JWT security → Redis client: checks token state (evidence: `backend/common/security/jwt.py`)
- JWT security → User schemas: validates user data (evidence: `backend/common/security/jwt.py`)
- Authentication → User access: accesses users (evidence: `backend/app/admin/service/auth_service.py`)
- Authentication → User schemas: uses schemas (evidence: `backend/app/admin/service/auth_service.py`)
- Admin API → Metrics: registers metrics (evidence: `backend/app/admin/api/router.py`)
- Admin API → Admin domains: routes domains (evidence: `backend/app/admin/api/v1/sys/__init__.py`)
- App startup → Plugin routing: initializes plugins (evidence: `backend/main.py`)
- Plugin routing → App routes: registers routes (evidence: `backend/plugin/router.py`)
- Plugin routing → Code generation: routes capability
- Plugin routing → Configuration plugin: routes capability
- Plugin routing → Dictionary plugin: routes capability
- Plugin routing → Email plugin: routes capability
- Plugin routing → Notice plugin: routes capability
- Plugin routing → OAuth2 plugin: routes capability
- Task API → Scheduler service: handles schedules
- Scheduler service → Task execution: dispatches tasks (evidence: `backend/app/task/service/scheduler_service.py`)
- Scheduler service → Task database: accesses persistence
- Task API → Metrics: registers metrics (evidence: `backend/app/task/api/router.py`)
- Settings → Redis client: configures client (evidence: `backend/database/redis.py`)
- Settings → Metrics: configures metrics (evidence: `backend/common/observability/prometheus/fastapi.py`)
- JWT security → Request context: sets identity (evidence: `backend/common/security/jwt.py`)
- Logging → Settings: reads configuration (evidence: `backend/common/log.py`)
- Logging → Shared utilities: uses timezone utilities (evidence: `backend/common/log.py`)
