# notarious2/fastapi-chat architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, real-time chat application.
- Backend: FastAPI (async), WebSockets, Redis (Pub/Sub & cache), PostgreSQL, Alembic migrations, SQLAlchemy.
- Frontend: Vue 3 + Vuetify 3 (separate repo), communicates over HTTP/REST + WebSocket.

##### File structure
- Top-level files: Dockerfile, docker-compose.yml, Makefile, Procfile, alembic/, pyproject.toml, src/ (app code), templates/, static/, tests/.
- src/ submodules:
- admin/ – admin panel models, services, custom auth backend
- authentication/ – JWT cookie auth, OAuth2 integration
- registration/, contact/, settings/ – REST routers, Pydantic schemas, service layer
- chat/ – chat REST endpoints (history, metadata)
- websocket/ – WS router, handlers, rate limiting, exceptions
- managers/ – PubSubManager, WebsocketManager to coordinate live events
- database.py, models.py, config.py, dependencies.py, main.py, routers.py
- Support: Alembic migrations; tests for each module.

##### README for additional insights
- Tech stack: FastAPI, WebSockets, Pydantic v2, asyncpg, async Redis, SQLAlchemy v2, Alembic, Poetry, Docker.
- Features: JWT HTTP-Only cookies, Google OAuth2, real-time pub/sub scaling, rate-limiting, background file uploads (to AWS S3 in prod), message/read status, user presence/typing, SQLAdmin panel.

##### Components
a. External Clients
- Web browser (Vue 3 + Vuetify)
- Mobile clients (if any)
b. API & WebSocket Layer
- FastAPI HTTP routers (authentication, registration, contact, settings, chat)
- FastAPI WebSocket router (real-time events)
c. Business Logic / Service Layer
- AuthenticationService, RegistrationService, ChatService, ContactService, SettingsService, AdminService
- PubSubManager (wrapping Redis Pub/Sub)
- WebsocketManager (managing active WS connections)
d. Data Layer
- PostgreSQL (asyncpg + SQLAlchemy models + Alembic migrations)
- Redis (Pub/Sub & caching for rate-limiting, presence, “is typing”)
- AWS S3 (file storage in production) / Local StaticFiles (dev)
e. Background Workers / Tasks
- FastAPI background tasks for file upload and non-critical updates
f. External Services
- Google OAuth2
- SQLAdmin panel (built upon FastAPI)

##### Relationships and data flows
- HTTP requests from clients → FastAPI HTTP routers → Service layer → Database or Redis → response.
- WebSocket connection established client ↔ FastAPI WS router → WebsocketManager → PubSubManager → Redis Pub/Sub → other instances’ WebsocketManager → WS handlers → deliver messages to clients.
- Background tasks triggered by endpoints → upload to S3 / update DB → notify via PubSub if needed.
- Authentication flow: login → JWT cookie set → subsequent HTTP/WS requests validated via dependencies.
- OAuth2: Frontend obtains Google token → sends to backend auth endpoint → backend verifies with Google → creates/fetches user in DB → issues JWT.

##### Architectural patterns & design principles
- Layered architecture: routers → services → data access
- CQRS-style split between HTTP (queries, commands) and WebSocket (real-time events)
- Pub/Sub for horizontal scalability across multiple backend replicas
- Dependency injection via FastAPI’s `Depends` for database sessions, auth, config
- Asynchronous all the way: database, Redis, HTTP, WS

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    ClientBrowser["Web Browser\n(Vue3 + Vuetify)"]:::client
    ClientMobile["Mobile Client"]:::client

    %% Backend Cluster
    subgraph "Backend (FastAPI Cluster)"
        direction TB

        subgraph "HTTP Routers"
            direction TB
            AuthRouter["Authentication Router"]:::compute
            RegRouter["Registration Router"]:::compute
            ContactRouter["Contact Router"]:::compute
            SettingsRouter["Settings Router"]:::compute
            ChatRouter["Chat Router"]:::compute
            AdminRouter["Admin Panel Router"]:::compute
        end

        subgraph "WebSocket Layer"
            direction TB
            WSRouter["FastAPI WS Router"]:::compute
            WSHandlers["WS Handlers"]:::compute
            WSRL["WS Rate Limiter"]:::compute
            WSExceptions["WS Exceptions"]:::compute
            WSSchemas["WS Schemas"]:::compute
            WSServices["WS Services"]:::compute
        end

        subgraph "Service Layer"
            direction TB
            AuthService["AuthenticationService"]:::compute
            RegService["RegistrationService"]:::compute
            ContactService["ContactService"]:::compute
            SettingsService["SettingsService"]:::compute
            ChatService["ChatService"]:::compute
            AdminService["AdminService"]:::compute
        end

        subgraph "Managers"
            direction TB
            PubSubManager["PubSubManager"]:::compute
            WebsocketManager["WebsocketManager"]:::compute
        end

        BackgroundTasks["Background Tasks"]:::background
    end

    %% Data Stores & External
    subgraph "Data Layer & External"
        direction TB
        Postgres["PostgreSQL\n(asyncpg + SQLAlchemy)"]:::db
        Redis["Redis\n(Pub/Sub & cache)"]:::db
        S3["AWS S3 Bucket"]:::external
        GoogleOAuth2["Google OAuth2"]:::external
    end

    %% Flows
    ClientBrowser -->|"HTTP/REST"| AuthRouter
    ClientBrowser -->|"HTTP/REST"| RegRouter
    ClientBrowser -->|"HTTP/REST"| ContactRouter
    ClientBrowser -->|"HTTP/REST"| SettingsRouter
    ClientBrowser -->|"HTTP/REST"| ChatRouter
    ClientBrowser -->|"HTTP/REST"| AdminRouter

    ClientMobile -->|"HTTP/REST"| AuthRouter
    ClientMobile -->|"HTTP/REST"| ChatRouter

    ClientBrowser -->|"WebSocket"| WSRouter
    ClientMobile -->|"WebSocket"| WSRouter

    %% HTTP to Services
    AuthRouter -->|"calls"| AuthService
    RegRouter -->|"calls"| RegService
    ContactRouter -->|"calls"| ContactService
    SettingsRouter -->|"calls"| SettingsService
    ChatRouter -->|"calls"| ChatService
    AdminRouter -->|"calls"| AdminService

    %% WS Flow
    WSRouter --> WSHandlers
    WSHandlers --> WSRL
    WSRL --> WSServices
    WSServices --> PubSubManager
    PubSubManager --> Redis
    PubSubManager --> WebsocketManager
    WebsocketManager --> WSHandlers
    WSHandlers -->|"deliver"| ClientBrowser
    WSHandlers -->|"deliver"| ClientMobile

    %% Service to Data
    AuthService --> Postgres
    RegService --> Postgres
    ContactService --> Postgres
    SettingsService --> Postgres
    ChatService --> Postgres
    AdminService --> Postgres

    %% Background tasks
    ChatService -->|"triggers"| BackgroundTasks
    BackgroundTasks -->|"upload"| S3
    BackgroundTasks -->|"update"| Postgres
    BackgroundTasks -->|"notify"| PubSubManager

    %% OAuth2 flow
    AuthRouter -->|"verify token"| GoogleOAuth2

    %% Click events
    click AuthRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/authentication/router.py"
    click RegRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/registration/router.py"
    click ContactRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/contact/router.py"
    click SettingsRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/settings/router.py"
    click ChatRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/chat/router.py"
    click AdminRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/admin/admin.py"
    click WSRouter "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/router.py"
    click WSHandlers "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/handlers.py"
    click WSRL "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/rate_limiter.py"
    click WSExceptions "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/exceptions.py"
    click WSSchemas "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/schemas.py"
    click WSServices "https://github.com/notarious2/fastapi-chat/blob/master/src/websocket/services.py"
    click AuthService "https://github.com/notarious2/fastapi-chat/blob/master/src/authentication/services.py"
    click RegService "https://github.com/notarious2/fastapi-chat/blob/master/src/registration/services.py"
    click ContactService "https://github.com/notarious2/fastapi-chat/blob/master/src/contact/services.py"
    click SettingsService "https://github.com/notarious2/fastapi-chat/blob/master/src/settings/services.py"
    click ChatService "https://github.com/notarious2/fastapi-chat/blob/master/src/chat/services.py"
    click AdminService "https://github.com/notarious2/fastapi-chat/blob/master/src/admin/services.py"
    click PubSubManager "https://github.com/notarious2/fastapi-chat/blob/master/src/managers/pubsub_manager.py"
    click WebsocketManager "https://github.com/notarious2/fastapi-chat/blob/master/src/managers/websocket_manager.py"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,color:#000
    classDef compute fill:#87CEFA,stroke:#000,color:#000
    classDef db fill:#7CFC00,stroke:#000,color:#000
    classDef external fill:#FFD700,stroke:#000,color:#000
    classDef background fill:#FFA500,stroke:#000,color:#000
```
