# sagungiri123/fastapi-chat-system architecture

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

- Interactive diagram: https://gitdiagram.com/sagungiri123/fastapi-chat-system
- Repository: https://github.com/sagungiri123/fastapi-chat-system

## Overview

Real-Time Chat Backend serves a small browser client and authenticated FastAPI endpoints. The main workflow is register/login, select or create a DM room, connect over WebSocket, then send and receive persisted messages; REST endpoints also provide cursor-based history, search, edits, and soft deletes. WebSocket events carry presence and typing updates, while Redis Pub/Sub distributes room events across server processes. The users and Redis helper implementations were not sampled, so their internal behavior and some wiring are represented only where the README or sampled callers support it.

Main entry points: [`app/api/websocket.py`](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/websocket.py) (WebSocket Handler), [`app/api/v1/messages.py`](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/messages.py) (Message Routes), [`app/main.py`](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/main.py) (FastAPI App), [`app/static/script.js`](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/static/script.js) (Client Logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_web_client["Chat UI<br/>[index.html]"]
  node_client_script["Client Logic<br/>[script.js]"]
end

subgraph group_api["HTTP API"]
  node_app_entry["FastAPI App<br/>[main.py]"]
  node_users_api["User and DM Routes<br/>[users.py]"]
  node_messages_api["Message Routes<br/>[messages.py]"]
end

subgraph group_realtime["Realtime Messaging"]
  node_ws_endpoint["WebSocket Handler<br/>[websocket.py]"]
  node_redis_helpers["Redis Room Helpers<br/>[redis.py]"]
  node_redis["Redis Pub/Sub"]
end

subgraph group_identity["Identity"]
  node_auth_api["Auth Routes<br/>[auth.py]"]
  node_security["Token and Password Security<br/>[security.py]"]
end

subgraph group_storage["Persistence"]
  node_user_model["User Model<br/>[user.py]"]
  node_message_model["Message Model<br/>[message.py]"]
  node_db_sessions["DB Sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
end

node_browser_user(("Chat User"))

node_browser_user -->|"uses"| node_web_client
node_web_client -->|"loads"| node_client_script
node_app_entry -->|"registers routes"| node_auth_api
node_app_entry -->|"registers routes"| node_users_api
node_app_entry -->|"registers routes"| node_messages_api
node_app_entry -->|"registers route"| node_ws_endpoint
node_app_entry -->|"serves static"| node_web_client
node_client_script -->|"calls auth"| node_auth_api
node_client_script -->|"requests DM"| node_users_api
node_client_script -->|"loads and edits"| node_messages_api
node_client_script -->|"opens socket"| node_ws_endpoint
node_auth_api -->|"hashes and signs"| node_security
node_auth_api -->|"queries and writes"| node_db_sessions
node_security -->|"looks up user"| node_db_sessions
node_messages_api -->|"authenticates"| node_security
node_messages_api -->|"queries and updates"| node_db_sessions
node_messages_api -->|"publishes events"| node_redis_helpers
node_ws_endpoint -->|"authenticates token"| node_security
node_ws_endpoint -->|"persists messages"| node_db_sessions
node_ws_endpoint -->|"manages room events"| node_redis_helpers
node_redis_helpers -->|"accesses Pub/Sub"| node_redis
node_ws_endpoint -->|"publishes and subscribes"| node_redis
node_redis -->|"dispatches events"| node_ws_endpoint
node_auth_api -->|"reads and creates"| node_user_model
node_security -->|"queries"| node_user_model
node_messages_api -->|"queries and updates"| node_message_model
node_ws_endpoint -->|"creates messages"| node_message_model
node_db_sessions -->|"connects"| node_postgres

click node_web_client "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/static/index.html"
click node_client_script "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/static/script.js"
click node_app_entry "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/main.py"
click node_auth_api "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/auth.py"
click node_users_api "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/users.py"
click node_messages_api "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/messages.py"
click node_ws_endpoint "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/websocket.py"
click node_security "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/security.py"
click node_user_model "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/models/user.py"
click node_message_model "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/models/message.py"
click node_db_sessions "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/database.py"
click node_redis_helpers "https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/redis.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_web_client,node_client_script,node_browser_user toneBlue
class node_app_entry,node_users_api,node_messages_api toneAmber
class node_ws_endpoint,node_redis_helpers,node_redis toneMint
class node_auth_api,node_security toneRose
class node_user_model,node_message_model,node_db_sessions,node_postgres toneIndigo
```

## Components

### Browser Client

- [Chat UI](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/static/index.html): `app/static/index.html`
- [Client Logic](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/static/script.js): `app/static/script.js`

### HTTP API

- [FastAPI App](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/main.py): `app/main.py`
- [User and DM Routes](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/users.py): `app/api/v1/users.py`
- [Message Routes](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/messages.py): `app/api/v1/messages.py`

### Realtime Messaging

- [WebSocket Handler](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/websocket.py): `app/api/websocket.py`
- [Redis Room Helpers](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/redis.py): `app/core/redis.py`
- **Redis Pub/Sub**

### Identity

- [Auth Routes](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/api/v1/auth.py): `app/api/v1/auth.py`
- [Token and Password Security](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/security.py): `app/core/security.py`

### Persistence

- [User Model](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/models/user.py): `app/models/user.py`
- [Message Model](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/models/message.py): `app/models/message.py`
- [DB Sessions](https://github.com/sagungiri123/fastapi-chat-system/blob/main/app/core/database.py): `app/core/database.py`
- **PostgreSQL**

### Other components

- **Chat User**

## Connections

- Chat User → Chat UI: uses
- Chat UI → Client Logic: loads
- FastAPI App → Auth Routes: registers routes
- FastAPI App → User and DM Routes: registers routes
- FastAPI App → Message Routes: registers routes
- FastAPI App → WebSocket Handler: registers route
- FastAPI App → Chat UI: serves static
- Client Logic → Auth Routes: calls auth
- Client Logic → User and DM Routes: requests DM
- Client Logic → Message Routes: loads and edits
- Client Logic → WebSocket Handler: opens socket
- Auth Routes → Token and Password Security: hashes and signs
- Auth Routes → DB Sessions: queries and writes
- Token and Password Security → DB Sessions: looks up user
- Message Routes → Token and Password Security: authenticates
- Message Routes → DB Sessions: queries and updates
- Message Routes → Redis Room Helpers: publishes events
- WebSocket Handler → Token and Password Security: authenticates token
- WebSocket Handler → DB Sessions: persists messages
- WebSocket Handler → Redis Room Helpers: manages room events
- Redis Room Helpers → Redis Pub/Sub: accesses Pub/Sub
- WebSocket Handler → Redis Pub/Sub: publishes and subscribes
- Redis Pub/Sub → WebSocket Handler: dispatches events
- Auth Routes → User Model: reads and creates
- Token and Password Security → User Model: queries
- Message Routes → Message Model: queries and updates
- WebSocket Handler → Message Model: creates messages
- DB Sessions → PostgreSQL: connects