# mariaegorenko/chat_project architecture

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

- Interactive diagram: https://gitdiagram.com/mariaegorenko/chat_project
- Repository: https://github.com/mariaegorenko/chat_project

## Overview

Chat Project is a FastAPI web chat with authenticated pages, contact management, and real-time messaging. A user visits the app, authenticates, then uses chat and contact pages; WebSocket handlers process chat and contact events, persist domain data, and deliver messages to connected users or queue them for later. The graph includes the documented browser capabilities and the sampled persistence and session layers. Some templates are mentioned in the README and main.py but are absent from the supplied tree; unsampled details and unshown wiring are omitted.

Main entry points: [`app/main.py`](https://github.com/mariaegorenko/chat_project/blob/main/app/main.py) (FastAPI app and pages), [`app/api/v1/routers/ws_hadlers_chats.py`](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_hadlers_chats.py) (Chat handlers), [`app/api/v1/routers/ws_handlers_contacts.py`](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_handlers_contacts.py) (Contact handlers), [`app/db/repositories/users/crud.py`](https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/users/crud.py) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web entry and UI"]
  node_app["FastAPI app and pages<br/>[main.py]"]
  node_auth_ui["Auth client<br/>[auth.js]"]
  node_register_ui["Registration client<br/>[register.js]"]
  node_chat_ui["Chat client<br/>[chat.js]"]
  node_chats_ui["Chats client<br/>[chats.js]"]
  node_contacts_ui["Contacts client<br/>[contacts.js]"]
  node_ws_client["WebSocket client<br/>[wsClient.js]"]
  node_datetime["Date formatting<br/>[datetime.js]"]
end

subgraph group_identity["Identity and access"]
  node_auth_router["Auth routes<br/>[auth.py]"]
  node_access_deps["Access dependencies<br/>[deps.py]"]
  node_sessions["Session state<br/>[session.py]"]
  node_security["Password and tokens<br/>[security.py]"]
end

subgraph group_realtime["Realtime features"]
  node_ws_entry["WebSocket entry<br/>[ws_main.py]"]
  node_ws_dispatch["Event dispatch<br/>[ws_handlers.py]"]
  node_chat_handlers["Chat handlers"]
  node_contact_handlers["Contact handlers"]
  node_ws_utils["WebSocket utilities<br/>[ws_utils.py]"]
  node_ws_schemas["WebSocket schemas<br/>[ws_schemas.py]"]
  node_chat_service["Chat page logic<br/>[chat_utils.py]"]
  node_contacts_router["Contact API routes<br/>[contacts.py]"]
end

subgraph group_data["Domain persistence"]
  node_users_repo["User repository<br/>[crud.py]"]
  node_chat_repo["Chat repository<br/>[crud.py]"]
  node_contacts_repo["Contact repository<br/>[crud.py]"]
  node_pending_repo["Pending events<br/>[crud.py]"]
  node_database[("SQL database<br/>[base.py]")]
end

node_browser(("User browser"))

node_browser -->|"opens pages"| node_app
node_app -->|"mounts routes"| node_auth_router
node_app -->|"mounts routes"| node_contacts_router
node_app -->|"registers socket"| node_ws_entry
node_app -->|"builds chat page"| node_chat_service
node_app -->|"creates tables"| node_database
node_browser -.->|"uses"| node_auth_ui
node_browser -.->|"uses"| node_register_ui
node_browser -.->|"uses"| node_chat_ui
node_browser -.->|"uses"| node_chats_ui
node_browser -.->|"uses"| node_contacts_ui
node_chat_ui -->|"uses"| node_ws_client
node_chats_ui -->|"uses"| node_ws_client
node_contacts_ui -->|"uses"| node_ws_client
node_chat_ui -->|"formats dates"| node_datetime
node_chats_ui -->|"formats dates"| node_datetime
node_auth_router -->|"authenticates users"| node_users_repo
node_auth_router -->|"uses tokens"| node_security
node_auth_router -->|"manages sessions"| node_sessions
node_access_deps -->|"reads sessions"| node_sessions
node_access_deps -->|"looks up users"| node_users_repo
node_users_repo -->|"hashes passwords"| node_security
node_ws_entry -->|"checks tokens"| node_security
node_ws_entry -->|"loads user"| node_users_repo
node_ws_entry -->|"dispatches events"| node_ws_dispatch
node_ws_dispatch -->|"routes chat events"| node_chat_handlers
node_ws_dispatch -->|"routes contact events"| node_contact_handlers
node_chat_handlers -->|"reads and writes"| node_chat_repo
node_chat_handlers -->|"queues offline events"| node_pending_repo
node_chat_handlers -->|"uses chat logic"| node_chat_service
node_contact_handlers -->|"manages requests"| node_contacts_repo
node_contact_handlers -->|"queues offline events"| node_pending_repo
node_chat_handlers -->|"uses helpers"| node_ws_utils
node_contact_handlers -->|"uses helpers"| node_ws_utils
node_chat_handlers -->|"formats events"| node_ws_schemas
node_contact_handlers -->|"formats events"| node_ws_schemas
node_contacts_router -->|"manages contacts"| node_contacts_repo
node_chat_service -->|"loads chats"| node_chat_repo
node_chat_service -->|"loads companions"| node_users_repo
node_chat_repo -.->|"queries and updates"| node_database
node_contacts_repo -.->|"queries and updates"| node_database
node_pending_repo -.->|"stores pending events"| node_database

click node_app "https://github.com/mariaegorenko/chat_project/blob/main/app/main.py"
click node_auth_ui "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/auth.js"
click node_register_ui "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/register.js"
click node_chat_ui "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/chat.js"
click node_chats_ui "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/chats.js"
click node_contacts_ui "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/contacts.js"
click node_ws_client "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/wsClient.js"
click node_datetime "https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/utils/datetime.js"
click node_auth_router "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/auth.py"
click node_access_deps "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/deps.py"
click node_sessions "https://github.com/mariaegorenko/chat_project/blob/main/app/core/session.py"
click node_security "https://github.com/mariaegorenko/chat_project/blob/main/app/core/security.py"
click node_users_repo "https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/users/crud.py"
click node_ws_entry "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_main.py"
click node_ws_dispatch "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_handlers.py"
click node_chat_handlers "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_hadlers_chats.py"
click node_contact_handlers "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_handlers_contacts.py"
click node_ws_utils "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_utils.py"
click node_ws_schemas "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_schemas.py"
click node_chat_service "https://github.com/mariaegorenko/chat_project/blob/main/app/services/chat_utils.py"
click node_contacts_router "https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/contacts.py"
click node_chat_repo "https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/chats/crud.py"
click node_contacts_repo "https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/contacts/crud.py"
click node_pending_repo "https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/pending/crud.py"
click node_database "https://github.com/mariaegorenko/chat_project/blob/main/app/db/base.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_auth_ui,node_register_ui,node_chat_ui,node_chats_ui,node_contacts_ui,node_ws_client,node_datetime,node_browser toneBlue
class node_auth_router,node_access_deps,node_sessions,node_security toneAmber
class node_ws_entry,node_ws_dispatch,node_chat_handlers,node_contact_handlers,node_ws_utils,node_ws_schemas,node_chat_service,node_contacts_router toneMint
class node_users_repo,node_chat_repo,node_contacts_repo,node_pending_repo,node_database toneRose
```

## Components

### Web entry and UI

- [FastAPI app and pages](https://github.com/mariaegorenko/chat_project/blob/main/app/main.py): `app/main.py`
- [Auth client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/auth.js): `app/static/js/auth.js`
- [Registration client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/register.js): `app/static/js/register.js`
- [Chat client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/chat.js): `app/static/js/chat.js`
- [Chats client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/chats.js): `app/static/js/chats.js`
- [Contacts client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/contacts.js): `app/static/js/contacts.js`
- [WebSocket client](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/wsClient.js): `app/static/js/wsClient.js`
- [Date formatting](https://github.com/mariaegorenko/chat_project/blob/main/app/static/js/utils/datetime.js): `app/static/js/utils/datetime.js`

### Identity and access

- [Auth routes](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/auth.py): `app/api/v1/routers/auth.py`
- [Access dependencies](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/deps.py): `app/api/v1/deps.py`
- [Session state](https://github.com/mariaegorenko/chat_project/blob/main/app/core/session.py): `app/core/session.py`
- [Password and tokens](https://github.com/mariaegorenko/chat_project/blob/main/app/core/security.py): `app/core/security.py`

### Realtime features

- [WebSocket entry](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_main.py): `app/api/v1/routers/ws_main.py`
- [Event dispatch](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_handlers.py): `app/api/v1/routers/ws_handlers.py`
- [Chat handlers](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_hadlers_chats.py): `app/api/v1/routers/ws_hadlers_chats.py`
- [Contact handlers](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_handlers_contacts.py): `app/api/v1/routers/ws_handlers_contacts.py`
- [WebSocket utilities](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_utils.py): `app/api/v1/routers/ws_utils.py`
- [WebSocket schemas](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/ws_schemas.py): `app/api/v1/routers/ws_schemas.py`
- [Chat page logic](https://github.com/mariaegorenko/chat_project/blob/main/app/services/chat_utils.py): `app/services/chat_utils.py`
- [Contact API routes](https://github.com/mariaegorenko/chat_project/blob/main/app/api/v1/routers/contacts.py): `app/api/v1/routers/contacts.py`

### Domain persistence

- [User repository](https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/users/crud.py): `app/db/repositories/users/crud.py`
- [Chat repository](https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/chats/crud.py): `app/db/repositories/chats/crud.py`
- [Contact repository](https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/contacts/crud.py): `app/db/repositories/contacts/crud.py`
- [Pending events](https://github.com/mariaegorenko/chat_project/blob/main/app/db/repositories/pending/crud.py): `app/db/repositories/pending/crud.py`
- [SQL database](https://github.com/mariaegorenko/chat_project/blob/main/app/db/base.py): `app/db/base.py`

### Other components

- **User browser**

## Connections

- User browser → FastAPI app and pages: opens pages (evidence: `README.md`)
- FastAPI app and pages → Auth routes: mounts routes (evidence: `app/main.py`)
- FastAPI app and pages → Contact API routes: mounts routes (evidence: `app/main.py`)
- FastAPI app and pages → WebSocket entry: registers socket (evidence: `app/main.py`)
- FastAPI app and pages → Chat page logic: builds chat page (evidence: `app/main.py`)
- FastAPI app and pages → SQL database: creates tables (evidence: `app/main.py`)
- User browser → Auth client: uses
- User browser → Registration client: uses
- User browser → Chat client: uses
- User browser → Chats client: uses
- User browser → Contacts client: uses
- Chat client → WebSocket client: uses (evidence: `app/static/js/chat.js`)
- Chats client → WebSocket client: uses (evidence: `app/static/js/chats.js`)
- Contacts client → WebSocket client: uses (evidence: `app/static/js/contacts.js`)
- Chat client → Date formatting: formats dates (evidence: `app/static/js/chat.js`)
- Chats client → Date formatting: formats dates (evidence: `app/static/js/chats.js`)
- Auth routes → User repository: authenticates users (evidence: `app/api/v1/routers/auth.py`)
- Auth routes → Password and tokens: uses tokens (evidence: `app/api/v1/routers/auth.py`)
- Auth routes → Session state: manages sessions (evidence: `app/api/v1/routers/auth.py`)
- Access dependencies → Session state: reads sessions (evidence: `app/api/v1/deps.py`)
- Access dependencies → User repository: looks up users (evidence: `app/api/v1/deps.py`)
- User repository → Password and tokens: hashes passwords (evidence: `app/db/repositories/users/crud.py`)
- WebSocket entry → Password and tokens: checks tokens (evidence: `app/api/v1/routers/ws_main.py`)
- WebSocket entry → User repository: loads user (evidence: `app/api/v1/routers/ws_main.py`)
- WebSocket entry → Event dispatch: dispatches events (evidence: `app/api/v1/routers/ws_main.py`)
- Event dispatch → Chat handlers: routes chat events (evidence: `app/api/v1/routers/ws_handlers.py`)
- Event dispatch → Contact handlers: routes contact events (evidence: `app/api/v1/routers/ws_handlers.py`)
- Chat handlers → Chat repository: reads and writes (evidence: `app/api/v1/routers/ws_hadlers_chats.py`)
- Chat handlers → Pending events: queues offline events (evidence: `app/api/v1/routers/ws_hadlers_chats.py`)
- Chat handlers → Chat page logic: uses chat logic (evidence: `app/api/v1/routers/ws_hadlers_chats.py`)
- Contact handlers → Contact repository: manages requests (evidence: `app/api/v1/routers/ws_handlers_contacts.py`)
- Contact handlers → Pending events: queues offline events (evidence: `app/api/v1/routers/ws_handlers_contacts.py`)
- Chat handlers → WebSocket utilities: uses helpers (evidence: `app/api/v1/routers/ws_hadlers_chats.py`)
- Contact handlers → WebSocket utilities: uses helpers (evidence: `app/api/v1/routers/ws_handlers_contacts.py`)
- Chat handlers → WebSocket schemas: formats events (evidence: `app/api/v1/routers/ws_hadlers_chats.py`)
- Contact handlers → WebSocket schemas: formats events (evidence: `app/api/v1/routers/ws_handlers_contacts.py`)
- Contact API routes → Contact repository: manages contacts (evidence: `app/api/v1/routers/contacts.py`)
- Chat page logic → Chat repository: loads chats (evidence: `app/services/chat_utils.py`)
- Chat page logic → User repository: loads companions (evidence: `app/services/chat_utils.py`)
- Chat repository → SQL database: queries and updates
- Contact repository → SQL database: queries and updates
- Pending events → SQL database: stores pending events
