# meschac38700/fastapi_getstarted architecture

> Architecture diagram of the GitHub repository meschac38700/fastapi_getstarted, 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/meschac38700/fastapi_getstarted
- Repository: https://github.com/meschac38700/fastapi_getstarted

## Overview

This is a FastAPI starter application whose core user-facing flow is HTTP requests through registered app routers, then authentication/authorization and domain handlers, with SQLModel persistence. Major capabilities include user and token authentication, groups and permissions, hero CRUD, and chat rooms/messages with WebSocket broadcasting. The README also describes extensible per-app structure. Edges reflect only README statements and shown source/index references; router registration and several subsystem details are unsampled, so uncertain wiring is left out.

Main entry points: [`src/apps/authentication/dependencies/oauth2.py`](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/dependencies/oauth2.py) (Token and session auth), [`src/main.py`](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/main.py) (FastAPI app), [`src/apps/user/models/user.py`](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/models/user.py) (User accounts), [`src/apps/authorization/models`](https://github.com/meschac38700/fastapi_getstarted/tree/master/src/apps/authorization/models) (Permission models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application runtime"]
  node_main["FastAPI app<br/>[main.py]"]
  node_appdiscovery["App discovery<br/>[apps.py]"]
  node_settings["Runtime settings<br/>[app.py]"]
end

subgraph group_identity["Identity and access"]
  node_authdeps["Token and session auth<br/>[oauth2.py]"]
  node_authroutes["Authentication routes<br/>[routers.py]"]
  node_tokens["JWT tokens<br/>[token.py]"]
  node_users["User accounts<br/>[user.py]"]
  node_userapi["User endpoints<br/>[users.py]"]
  node_roles["Role checks<br/>[roles.py]"]
  node_accessapi["Groups and permissions<br/>[groups.py]"]
  node_permissionmodels["Permission models"]
end

subgraph group_domains["Product domains"]
  node_heroapi["Hero endpoints<br/>[routers.py]"]
  node_heromodel["Hero model<br/>[hero.py]"]
  node_chatapi["Chat room endpoints<br/>[room.py]"]
  node_chatmodels["Chat models<br/>[orm.py]"]
  node_chatmanager["WebSocket manager<br/>[manager.py]"]
  node_chatweb["Chat WebSocket<br/>[web.py]"]
end

subgraph group_platform["Persistence and services"]
  node_dbsession["DB session<br/>[session.py]"]
  node_dbquery["Query manager<br/>[manager.py]"]
  node_database[("Relational database")]
  node_broker["Broadcast broker"]
  node_celery["Celery service<br/>[main.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_main
node_main -->|"discovers apps"| node_appdiscovery
node_main -->|"configures runtime"| node_settings
node_main -->|"attaches service"| node_celery
node_authdeps -->|"looks up token"| node_tokens
node_authdeps -->|"resolves user"| node_users
node_authroutes -->|"uses dependencies"| node_authdeps
node_authroutes -->|"uses token model"| node_tokens
node_userapi -->|"uses authentication"| node_authdeps
node_userapi -->|"uses permissions"| node_permissionmodels
node_userapi -->|"reads and writes"| node_users
node_users -->|"relates access data"| node_permissionmodels
node_accessapi -->|"uses models"| node_permissionmodels
node_accessapi -->|"uses role checks"| node_roles
node_heroapi -->|"checks permissions"| node_permissionmodels
node_heroapi -->|"reads and writes"| node_heromodel
node_chatapi -->|"authenticates requests"| node_authdeps
node_chatapi -->|"uses room models"| node_chatmodels
node_chatapi -->|"checks roles"| node_roles
node_chatweb -->|"starts WebSocket handling"| node_chatmanager
node_chatmanager -->|"persists messages"| node_chatmodels
node_chatmanager -->|"publishes and subscribes"| node_broker
node_chatmodels -->|"relates chat users"| node_users
node_dbsession -->|"reads configuration"| node_settings
node_dbquery -->|"uses session dependency"| node_dbsession
node_dbsession -.->|"opens database access"| node_database
node_celery -->|"reads broker settings"| node_settings
node_celery -->|"discovers task apps"| node_appdiscovery

click node_main "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/main.py"
click node_appdiscovery "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/services/files/apps.py"
click node_settings "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/settings/app.py"
click node_authdeps "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/dependencies/oauth2.py"
click node_authroutes "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/routers.py"
click node_tokens "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/models/token.py"
click node_users "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/models/user.py"
click node_userapi "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/routers/users.py"
click node_roles "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/dependencies/roles.py"
click node_accessapi "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authorization/routers/groups.py"
click node_permissionmodels "https://github.com/meschac38700/fastapi_getstarted/tree/master/src/apps/authorization/models"
click node_heroapi "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/hero/routers.py"
click node_heromodel "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/hero/models/hero.py"
click node_chatapi "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/routers/room.py"
click node_chatmodels "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/models/orm.py"
click node_chatmanager "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/services/manager.py"
click node_chatweb "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/web.py"
click node_dbsession "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/db/dependencies/session.py"
click node_dbquery "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/db/query/manager.py"
click node_celery "https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/services/celery/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_main,node_appdiscovery,node_settings,node_client toneBlue
class node_authdeps,node_authroutes,node_tokens,node_users,node_userapi,node_roles,node_accessapi,node_permissionmodels toneAmber
class node_heroapi,node_heromodel,node_chatapi,node_chatmodels,node_chatmanager,node_chatweb toneMint
class node_dbsession,node_dbquery,node_database,node_broker,node_celery toneRose
```

## Components

### Application runtime

- [FastAPI app](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/main.py): `src/main.py`
- [App discovery](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/services/files/apps.py): `src/core/services/files/apps.py`
- [Runtime settings](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/settings/app.py): `src/settings/app.py`

### Identity and access

- [Token and session auth](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/dependencies/oauth2.py): `src/apps/authentication/dependencies/oauth2.py`
- [Authentication routes](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/routers.py): `src/apps/authentication/routers.py`
- [JWT tokens](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authentication/models/token.py): `src/apps/authentication/models/token.py`
- [User accounts](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/models/user.py): `src/apps/user/models/user.py`
- [User endpoints](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/routers/users.py): `src/apps/user/routers/users.py`
- [Role checks](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/user/dependencies/roles.py): `src/apps/user/dependencies/roles.py`
- [Groups and permissions](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/authorization/routers/groups.py): `src/apps/authorization/routers/groups.py`
- [Permission models](https://github.com/meschac38700/fastapi_getstarted/tree/master/src/apps/authorization/models): `src/apps/authorization/models`

### Product domains

- [Hero endpoints](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/hero/routers.py): `src/apps/hero/routers.py`
- [Hero model](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/hero/models/hero.py): `src/apps/hero/models/hero.py`
- [Chat room endpoints](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/routers/room.py): `src/apps/chat/routers/room.py`
- [Chat models](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/models/orm.py): `src/apps/chat/models/orm.py`
- [WebSocket manager](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/services/manager.py): `src/apps/chat/services/manager.py`
- [Chat WebSocket](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/apps/chat/web.py): `src/apps/chat/web.py`

### Persistence and services

- [DB session](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/db/dependencies/session.py): `src/core/db/dependencies/session.py`
- [Query manager](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/db/query/manager.py): `src/core/db/query/manager.py`
- **Relational database**
- **Broadcast broker**
- [Celery service](https://github.com/meschac38700/fastapi_getstarted/blob/master/src/core/services/celery/main.py): `src/core/services/celery/main.py`

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests (evidence: `src/main.py`)
- FastAPI app → App discovery: discovers apps (evidence: `src/main.py`)
- FastAPI app → Runtime settings: configures runtime (evidence: `src/main.py`)
- FastAPI app → Celery service: attaches service (evidence: `src/main.py`)
- Token and session auth → JWT tokens: looks up token (evidence: `src/apps/authentication/dependencies/oauth2.py`)
- Token and session auth → User accounts: resolves user (evidence: `src/apps/authentication/dependencies/oauth2.py`)
- Authentication routes → Token and session auth: uses dependencies (evidence: `src/apps/authentication/routers.py`)
- Authentication routes → JWT tokens: uses token model (evidence: `src/apps/authentication/routers.py`)
- User endpoints → Token and session auth: uses authentication (evidence: `src/apps/user/routers/users.py`)
- User endpoints → Permission models: uses permissions (evidence: `src/apps/user/routers/users.py`)
- User endpoints → User accounts: reads and writes (evidence: `src/apps/user/routers/users.py`)
- User accounts → Permission models: relates access data (evidence: `src/apps/user/models/user.py`)
- Groups and permissions → Permission models: uses models (evidence: `src/apps/authorization/routers/groups.py`)
- Groups and permissions → Role checks: uses role checks (evidence: `src/apps/authorization/routers/groups.py`)
- Hero endpoints → Permission models: checks permissions (evidence: `src/apps/hero/routers.py`)
- Hero endpoints → Hero model: reads and writes (evidence: `src/apps/hero/routers.py`)
- Chat room endpoints → Token and session auth: authenticates requests (evidence: `src/apps/chat/routers/room.py`)
- Chat room endpoints → Chat models: uses room models (evidence: `src/apps/chat/routers/room.py`)
- Chat room endpoints → Role checks: checks roles (evidence: `src/apps/chat/routers/room.py`)
- Chat WebSocket → WebSocket manager: starts WebSocket handling (evidence: `src/apps/chat/web.py`)
- WebSocket manager → Chat models: persists messages (evidence: `src/apps/chat/services/manager.py`)
- WebSocket manager → Broadcast broker: publishes and subscribes (evidence: `src/apps/chat/services/manager.py`)
- Chat models → User accounts: relates chat users (evidence: `src/apps/chat/models/orm.py`)
- DB session → Runtime settings: reads configuration (evidence: `src/core/db/dependencies/session.py`)
- Query manager → DB session: uses session dependency (evidence: `src/core/db/query/manager.py`)
- DB session → Relational database: opens database access
- Celery service → Runtime settings: reads broker settings (evidence: `src/core/services/celery/main.py`)
- Celery service → App discovery: discovers task apps (evidence: `src/core/services/celery/main.py`)
