# odaiahmed99/fastapi-mvt architecture

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

- Interactive diagram: https://gitdiagram.com/odaiahmed99/fastapi-mvt
- Repository: https://github.com/odaiahmed99/fastapi-mvt

## Overview

fastapi-mvt is a productivity library for ordinary FastAPI applications: it adds an async Django-style ORM, request-scoped transactions, safe Alembic migrations, project scaffolding and CLI workflows, plus optional authentication, admin, and WebSocket fan-out. A typical API request enters the app, uses ORM queries within the request transaction, and returns model data; developers also create projects and evolve schemas through the CLI. The README documents a migration-built, rollback-isolated test harness. Some subsystems are represented at their exact enclosing paths because their implementation was not sampled.

Main entry points: [`fastapi_mvt/migrations/commands.py`](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/migrations/commands.py) (Migration workflow), [`fastapi_mvt/db/database.py`](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/database.py) (Database sessions), [`fastapi_mvt/cli.py`](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/cli.py) (CLI commands), [`fastapi_mvt/auth/__init__.py`](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/auth/__init__.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["ORM and requests"]
  node_request_transactions["Request transactions<br/>[database.py]"]
  node_model_layer["Models and fields<br/>[models.py]"]
  node_queryset["QuerySet ORM<br/>[query.py]"]
  node_database_sessions["Database sessions<br/>[database.py]"]
  node_api_schemas["Model schemas<br/>[schemas.py]"]
  node_pagination["Pagination<br/>[pagination.py]"]
end

subgraph group_schema["Schema evolution"]
  node_migration_commands["Migration workflow<br/>[commands.py]"]
  node_migration_autogen["Migration safety<br/>[autogen.py]"]
  node_migration_files["Migration history"]
end

subgraph group_developer["Project tools"]
  node_project_config["Project loading<br/>[project.py]"]
  node_command_line["CLI commands<br/>[cli.py]"]
  node_scaffolding["Project scaffolding"]
  node_test_harness["Test harness<br/>[plugin.py]"]
end

subgraph group_extensions["Optional capabilities"]
  node_authentication["Authentication<br/>[__init__.py]"]
  node_passwords["Password hashing<br/>[passwords.py]"]
  node_admin_site["Admin site<br/>[admin.py]"]
  node_websocket_fanout["WebSocket fan-out<br/>[websockets.py]"]
end

node_developer_actor(("API developer"))
node_api_client(("API client"))
node_fastapi_app["FastAPI app"]
node_cli_user(("CLI user"))
node_database_server[("SQL database")]
node_redis_service[("Redis")]

node_api_client -->|"sends requests"| node_fastapi_app
node_fastapi_app -->|"handles requests"| node_request_transactions
node_request_transactions -->|"opens session"| node_database_sessions
node_request_transactions -->|"commits before response"| node_fastapi_app
node_fastapi_app -->|"returns response"| node_api_client
node_developer_actor -->|"defines API"| node_fastapi_app
node_model_layer -->|"provides models"| node_queryset
node_queryset -->|"executes queries"| node_database_sessions
node_database_sessions -->|"reads and writes"| node_database_server
node_developer_actor -->|"defines schemas"| node_api_schemas
node_api_schemas -->|"derives from models"| node_model_layer
node_developer_actor -->|"uses pagination"| node_pagination
node_pagination -->|"paginates queries"| node_queryset
node_cli_user -->|"runs commands"| node_command_line
node_command_line -->|"loads project"| node_project_config
node_command_line -->|"generates projects"| node_scaffolding
node_command_line -->|"dispatches migration commands"| node_migration_commands
node_migration_commands -->|"loads project settings"| node_project_config
node_migration_commands -->|"checks model changes"| node_migration_autogen
node_migration_commands -->|"applies and records migrations"| node_migration_files
node_migration_autogen -->|"compares model metadata"| node_model_layer
node_test_harness -->|"loads project"| node_project_config
node_test_harness -->|"builds test database"| node_migration_commands
node_test_harness -->|"isolates test transactions"| node_database_sessions
node_fastapi_app -.->|"serves auth routes"| node_authentication
node_authentication -->|"looks up users"| node_queryset
node_authentication -->|"hashes passwords"| node_passwords
node_admin_site -.->|"uses session maker"| node_database_sessions
node_admin_site -.->|"authenticates admins"| node_authentication
node_fastapi_app -.->|"serves WebSockets"| node_websocket_fanout
node_websocket_fanout -.->|"publishes across processes"| node_redis_service

click node_request_transactions "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/database.py"
click node_model_layer "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/models.py"
click node_queryset "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/query.py"
click node_database_sessions "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/database.py"
click node_api_schemas "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/schemas.py"
click node_pagination "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/pagination.py"
click node_project_config "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/project.py"
click node_command_line "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/cli.py"
click node_scaffolding "https://github.com/odaiahmed99/fastapi-mvt/tree/main/fastapi_mvt/scaffold"
click node_migration_commands "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/migrations/commands.py"
click node_migration_autogen "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/migrations/autogen.py"
click node_migration_files "https://github.com/odaiahmed99/fastapi-mvt/tree/main/fastapi_mvt/migrations"
click node_test_harness "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/testing/plugin.py"
click node_authentication "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/auth/__init__.py"
click node_passwords "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/auth/passwords.py"
click node_admin_site "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/admin.py"
click node_websocket_fanout "https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/websockets.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_request_transactions,node_model_layer,node_queryset,node_database_sessions,node_api_schemas,node_pagination,node_api_client,node_cli_user toneBlue
class node_migration_commands,node_migration_autogen,node_migration_files,node_database_server,node_redis_service toneAmber
class node_project_config,node_command_line,node_scaffolding,node_test_harness,node_developer_actor,node_fastapi_app toneMint
class node_authentication,node_passwords,node_admin_site,node_websocket_fanout toneRose
```

## Components

### ORM and requests

- [Request transactions](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/database.py): `fastapi_mvt/db/database.py`
- [Models and fields](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/models.py): `fastapi_mvt/db/models.py`
- [QuerySet ORM](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/query.py): `fastapi_mvt/db/query.py`
- [Database sessions](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/database.py): `fastapi_mvt/db/database.py`
- [Model schemas](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/schemas.py): `fastapi_mvt/db/schemas.py`
- [Pagination](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/db/pagination.py): `fastapi_mvt/db/pagination.py`

### Schema evolution

- [Migration workflow](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/migrations/commands.py): `fastapi_mvt/migrations/commands.py`
- [Migration safety](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/migrations/autogen.py): `fastapi_mvt/migrations/autogen.py`
- [Migration history](https://github.com/odaiahmed99/fastapi-mvt/tree/main/fastapi_mvt/migrations): `fastapi_mvt/migrations`

### Project tools

- [Project loading](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/project.py): `fastapi_mvt/project.py`
- [CLI commands](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/cli.py): `fastapi_mvt/cli.py`
- [Project scaffolding](https://github.com/odaiahmed99/fastapi-mvt/tree/main/fastapi_mvt/scaffold): `fastapi_mvt/scaffold`
- [Test harness](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/testing/plugin.py): `fastapi_mvt/testing/plugin.py`

### Optional capabilities

- [Authentication](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/auth/__init__.py): `fastapi_mvt/auth/__init__.py`
- [Password hashing](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/auth/passwords.py): `fastapi_mvt/auth/passwords.py`
- [Admin site](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/admin.py): `fastapi_mvt/admin.py`
- [WebSocket fan-out](https://github.com/odaiahmed99/fastapi-mvt/blob/main/fastapi_mvt/websockets.py): `fastapi_mvt/websockets.py`

### Other components

- **API developer**
- **API client**
- **FastAPI app**
- **CLI user**
- **SQL database**
- **Redis**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → Request transactions: handles requests
- Request transactions → Database sessions: opens session
- Request transactions → FastAPI app: commits before response
- FastAPI app → API client: returns response
- API developer → FastAPI app: defines API
- Models and fields → QuerySet ORM: provides models
- QuerySet ORM → Database sessions: executes queries
- Database sessions → SQL database: reads and writes
- API developer → Model schemas: defines schemas
- Model schemas → Models and fields: derives from models
- API developer → Pagination: uses pagination
- Pagination → QuerySet ORM: paginates queries
- CLI user → CLI commands: runs commands
- CLI commands → Project loading: loads project
- CLI commands → Project scaffolding: generates projects
- CLI commands → Migration workflow: dispatches migration commands
- Migration workflow → Project loading: loads project settings
- Migration workflow → Migration safety: checks model changes
- Migration workflow → Migration history: applies and records migrations
- Migration safety → Models and fields: compares model metadata
- Test harness → Project loading: loads project
- Test harness → Migration workflow: builds test database
- Test harness → Database sessions: isolates test transactions
- FastAPI app → Authentication: serves auth routes
- Authentication → QuerySet ORM: looks up users
- Authentication → Password hashing: hashes passwords
- Admin site → Database sessions: uses session maker
- Admin site → Authentication: authenticates admins
- FastAPI app → WebSocket fan-out: serves WebSockets
- WebSocket fan-out → Redis: publishes across processes