# aditya-620/chatterbox architecture

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

- Interactive diagram: https://gitdiagram.com/aditya-620/chatterbox
- Repository: https://github.com/aditya-620/chatterbox

## Overview

**ChatterBox is a full-stack real-time chat application**:
- **Frontend**: React (Vite) SPA using **Axios** for REST and **SockJS + STOMP** for WebSocket messaging.
- **Backend**: Spring Boot application exposing **REST APIs** for room & history, and **WebSocket/STOMP** endpoints for real-time chat.
- **Persistence**: **MongoDB** storing `Room` and `Message` documents.
- **Cross-cutting**: **AES-256 encryption** performed in the backend before persisting messages.

##### Backend (`ChatterBox-backend/src/main/java/...`)
Key components visible directly from structure:
- `config/WebSocketConfig.java` → STOMP endpoint setup, topic/app prefixes, SockJS config (likely), CORS config (via `FRONTEND_URL` in properties)
- `controllers/ChatController.java` → WebSocket message handling (e.g., `@MessageMapping`)
- `controllers/RoomController.java` → REST endpoints: create room, join room, fetch messages with pagination
- `entities/Message.java`, `entities/Room.java` → MongoDB domain models
- `repositories/RoomRepository.java` → MongoDB data access (likely `MongoRepository`)
- `utils/EncryptionUtil.java` → AES encryption/decryption logic (hardcoded key per README)
- `application.properties` → runtime config, env var bindings (`MONGODB_URI`, etc.)
- `Dockerfile` → backend containerization boundary

##### Frontend (`ChatterBox-frontend/src`)
Key components:
- `components/JoinCreateChat.jsx` → UX entry flow (create/join room)
- `components/ChatPage.jsx` → main chat UI; likely initializes WebSocket and renders message list
- `context/ChatContext.jsx` → global chat state (current room, messages, user, theme)
- `services/RoomService.js` → REST calls to backend
- `config/AxiosHelper.js` → axios base URL set via `VITE_API_URL`
- `config/Routes.jsx` → page routing boundaries

##### ChatterBox Backend (Spring Boot)
- REST API: `/api/v1/...`
- WebSocket endpoint: `/chat`
##### MongoDB database

**Configuration links**
- Frontend uses `VITE_API_URL` → points to backend base URL
- Backend uses:
- `MONGODB_URI`, `MONGODB_DATABASE`
- `FRONTEND_URL` for CORS / WebSocket allowed origins

**Deployment boundary**
- Backend can be run via Maven or Docker (`ChatterBox-backend/Dockerfile`)

This is where you “separate into as many components as possible” based on the repo.

##### `RoomController` → `RoomRepository` → MongoDB (query)
3. Backend returns messages (likely decrypted before return; if not, explicitly note “frontend receives encrypted” vs “backend decrypts” depending on code)

##### Backend `ChatController`
- encrypts via `EncryptionUtil`
- persists to MongoDB (via repo/path in code)
- publishes encrypted/decrypted payload to `/topic/room/{roomId}`

##### Important architectural patterns to highlight (based on repo)
- **SPA + API** separation: React frontend decoupled from backend via env-based base URL.
- **Dual-channel communication**:
- REST for “stateful resources” (rooms, history)
- WebSocket/STOMP for “events” (new messages)
- **Pub/Sub topic model**: `/topic/room/{roomId}` is the broadcast channel.
- **Repository pattern**: Spring Data repository encapsulates Mongo persistence.
- **Security/encryption boundary**: encryption occurs **server-side before storage** (explicit trust boundary).

- **Blue rectangles**: runtime containers (React SPA, Spring Boot, MongoDB)

- REST: `/api/v1/rooms`, `/api/v1/rooms/{roomId}`, `/api/v1/rooms/{roomId}/messages`
- WS:
- `/chat`
- Send: `/app/sendMessage/{roomId}`
- Subscribe: `/topic/room/{roomId}`

Callouts for configuration:
- `VITE_API_URL` (frontend)
- `MONGODB_URI`, `MONGODB_DATABASE`, `FRONTEND_URL` (backend)

A **security note** bubble:
- “AES-256 key hardcoded in EncryptionUtil → replace with env/secret manager in production.”

##### Top: Browser/User
2. Left: **React SPA** (JoinCreateChat, ChatPage, ChatContext, RoomService/Axios, STOMP client)
3. Right: **Spring Boot** (RoomController, ChatController, WebSocketConfig, EncryptionUtil, RoomRepository, Entities)
##### Bottom: MongoDB

This will be the most accurate representation of what the repository actually contains, while staying detailed and readable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context / Actors
    %% =========================
    U["User<br/>(Browser)"]:::actor

    subgraph SYS["ChatterBox System"]
        direction TB

        %% =========================
        %% Frontend Container
        %% =========================
        subgraph FE_CONT["Frontend Container: React SPA (Vite)"]
            direction TB

            FE_App["App (React Root)"]:::container
            FE_Main["Vite Entry (main.jsx)"]:::component
            FE_Routes["Routes (Routing Boundary)"]:::component

            subgraph FE_UI["UI Components"]
                direction TB
                FE_Join["JoinCreateChat (Create/Join Room UI)"]:::component
                FE_Chat["ChatPage (Chat UI + STOMP Client)"]:::component
            end

            subgraph FE_STATE["State + Services"]
                direction TB
                FE_Context["ChatContext (Global State)"]:::component
                FE_Axios["AxiosHelper (VITE_API_URL base client)"]:::component
                FE_RoomService["RoomService (REST API wrapper)"]:::component
            end

            FE_ViteCfg["Vite Config"]:::component
            FE_Env["Config: VITE_API_URL"]:::note

            FE_Main -->|"bootstraps"| FE_App
            FE_App -->|"uses"| FE_Routes
            FE_Routes -->|"routes_to"| FE_Join
            FE_Routes -->|"routes_to"| FE_Chat
            FE_App -->|"provides"| FE_Context
            FE_RoomService -->|"uses"| FE_Axios
            FE_Axios -.->|"reads"| FE_Env
        end

        %% =========================
        %% Backend Container
        %% =========================
        subgraph BE_CONT["Backend Container: Spring Boot"]
            direction TB

            BE_App["Spring Boot Application"]:::container
            BE_Docker["Dockerfile (Container Boundary)"]:::note

            subgraph BE_WEB["Web/API Layer"]
                direction TB
                BE_RoomCtrl["RoomController (REST)"]:::component
                BE_ChatCtrl["ChatController (WebSocket/STOMP)"]:::component
                BE_WSConfig["WebSocketConfig (STOMP/SockJS/CORS)"]:::component
            end

            subgraph BE_DOMAIN["Domain + Persistence"]
                direction TB
                BE_Repo["RoomRepository (Spring Data Mongo)"]:::component
                BE_Room["Room (Mongo Document)"]:::component
                BE_Message["Message (Mongo Document)"]:::component
                BE_MsgReq["MessageRequest (Inbound DTO)"]:::component
            end

            subgraph BE_XCUT["Cross-cutting"]
                direction TB
                BE_Enc["EncryptionUtil (AES-256 encrypt/decrypt)"]:::component
                BE_SecNote["Security Note: AES-256 key is hardcoded<br/>→ use env/secret manager in production"]:::warning
            end

            BE_Props["application.properties (MONGODB_URI, MONGODB_DATABASE, FRONTEND_URL)"]:::note

            BE_App -->|"registers"| BE_RoomCtrl
            BE_App -->|"registers"| BE_ChatCtrl
            BE_App -.->|"loads"| BE_WSConfig
            BE_App -.->|"reads"| BE_Props
            BE_Docker -.->|"packages_runs"| BE_App

            BE_RoomCtrl -->|"uses"| BE_Repo
            BE_ChatCtrl -->|"uses"| BE_Enc
            BE_ChatCtrl -->|"uses"| BE_Repo
            BE_ChatCtrl -->|"accepts"| BE_MsgReq
            BE_Repo -->|"persists"| BE_Room
            BE_Room -->|"contains_or_links"| BE_Message

            BE_Enc -.->|"encrypt_before_persist"| BE_Repo
            BE_SecNote -.->|"callout"| BE_Enc
        end

        %% =========================
        %% Database
        %% =========================
        DB[("MongoDB<br/>(Rooms & Messages)")]:::db
    end

    %% =========================
    %% Protocol Flows (Vertical)
    %% =========================
    U -->|"uses_UI"| FE_App

    %% REST - Create / Join / History
    FE_Join -->|"REST: POST /api/v1/rooms"| BE_RoomCtrl
    FE_Join -->|"REST: GET /api/v1/rooms/{roomId}"| BE_RoomCtrl
    FE_Chat -->|"REST: GET /api/v1/rooms/{roomId}/messages?page=X&size=Y"| BE_RoomCtrl

    %% WebSocket/STOMP - Real-time
    FE_Chat -->|"WS(S)+SockJS: CONNECT /chat"| BE_WSConfig
    FE_Chat -->|"STOMP: SUBSCRIBE /topic/room/{roomId}"| BE_ChatCtrl
    FE_Chat -->|"STOMP: SEND /app/sendMessage/{roomId} (MessageRequest)"| BE_ChatCtrl
    BE_ChatCtrl -->|"STOMP: PUBLISH /topic/room/{roomId}"| FE_Chat

    %% DB reads/writes
    BE_Repo -->|"Mongo: read/write"| DB
    BE_RoomCtrl -->|"Mongo: query_via_repo"| BE_Repo
    BE_ChatCtrl -->|"Mongo: insert_message_via_repo"| BE_Repo

    %% Encryption boundary (explicit step)
    BE_ChatCtrl -->|"encrypt_content"| BE_Enc
    BE_Enc -->|"encrypted_payload"| BE_Repo

    %% =========================
    %% Legend (color + arrows)
    %% =========================
    subgraph LEGEND["Legend"]
        direction TB
        L1["Blue: Runtime Containers"]:::container
        L2["Gray: Internal Components/Modules"]:::component
        L3["Black cylinder: Database"]:::db
        L4["Green links: REST/HTTP"]:::legendRest
        L5["Orange links: WebSocket/STOMP"]:::legendWs
        L6["Purple links: DB IO"]:::legendDb
        L7["Yellow: Notes/Config"]:::note
        L8["Red: Security Callouts"]:::warning
    end

    %% =========================
    %% Link Styles (by index) - Mermaid uses 0-based indexing
    %% =========================
    %% REST links (green): indices 21-23
    linkStyle 21 stroke:#22c55e,stroke-width:2px
    linkStyle 22 stroke:#22c55e,stroke-width:2px
    linkStyle 23 stroke:#22c55e,stroke-width:2px

    %% WS links (orange): indices 24-27
    linkStyle 24 stroke:#f59e0b,stroke-width:2px
    linkStyle 25 stroke:#f59e0b,stroke-width:2px
    linkStyle 26 stroke:#f59e0b,stroke-width:2px
    linkStyle 27 stroke:#f59e0b,stroke-width:2px

    %% DB links (purple): indices 28-30
    linkStyle 28 stroke:#a855f7,stroke-width:2px
    linkStyle 29 stroke:#a855f7,stroke-width:2px
    linkStyle 30 stroke:#a855f7,stroke-width:2px

    %% Encryption links (dashed gray): indices 31-32
    linkStyle 31 stroke:#6b7280,stroke-width:2px,stroke-dasharray:5 5
    linkStyle 32 stroke:#6b7280,stroke-width:2px,stroke-dasharray:5 5

    %% =========================
    %% Click Events (from mappings)
    %% =========================
    click BE_App "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/ChatterBoxBackendApplication.java"
    click BE_WSConfig "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/config/WebSocketConfig.java"
    click BE_ChatCtrl "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/controllers/ChatController.java"
    click BE_RoomCtrl "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/controllers/RoomController.java"
    click BE_Message "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/entities/Message.java"
    click BE_Room "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/entities/Room.java"
    click BE_MsgReq "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/playload/MessageRequest.java"
    click BE_Repo "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/repositories/RoomRepository.java"
    click BE_Enc "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/java/com/adityarastogi/ChatterBox_backend/utils/EncryptionUtil.java"
    click BE_Props "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-backend/src/main/resources/application.properties"
    click BE_Docker "https://github.com/aditya-620/chatterbox/tree/main/ChatterBox-backend/Dockerfile"

    click FE_App "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/App.jsx"
    click FE_Routes "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/config/Routes.jsx"
    click FE_Join "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/components/JoinCreateChat.jsx"
    click FE_Chat "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/components/ChatPage.jsx"
    click FE_Context "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/context/ChatContext.jsx"
    click FE_RoomService "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/services/RoomService.js"
    click FE_Axios "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/config/AxiosHelper.js"
    click FE_Main "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/src/main.jsx"
    click FE_ViteCfg "https://github.com/aditya-620/chatterbox/blob/main/ChatterBox-frontend/vite.config.js"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:1.5px,color:#111827
    classDef container fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0b1b3a
    classDef component fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef db fill:#111827,stroke:#111827,stroke-width:2px,color:#ffffff
    classDef note fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#713f12
    classDef warning fill:#fee2e2,stroke:#b91c1c,stroke-width:1.8px,color:#7f1d1d
    classDef legendRest fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
    classDef legendWs fill:#ffedd5,stroke:#f59e0b,stroke-width:1.5px,color:#7c2d12
    classDef legendDb fill:#f3e8ff,stroke:#a855f7,stroke-width:1.5px,color:#3b0764
```
