# dheerajroy/worldchat architecture

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

- Interactive diagram: https://gitdiagram.com/dheerajroy/worldchat
- Repository: https://github.com/dheerajroy/worldchat

## Overview

##### Project type and purpose
- Full-stack real-time chat application (“WorldChat”)
- Frontend: Next.js (React) + Tailwind CSS
- Backend: FastAPI (Python) supporting WebSocket-based chat

##### File structure
- Top-level “client” directory
– Next.js app using the new “app/” router pattern (app/page.jsx, app/layout.jsx, components/)
– Configuration: jsconfig.json, next.config.js, tailwind.config.js
- Top-level “server” directory
– FastAPI app: app/main.py, routers/chat.py
– WebSocket connection manager: dependencies/connection_manager.py
– No persistent database configured (in-memory pub/sub)

##### Extract additional insights from README
- FastAPI-backed real-time communication
- Next.js dynamic/interactive UI
- CORS settings in main.py and API_URL in client code
- Run servers separately on localhost:8000 (backend) and 3000 (frontend)

##### Main components and how they interact
a. User’s Web Browser
– Runs the Next.js app, opens a WebSocket and issues REST calls as needed
b. Next.js Frontend Server
– Serves HTML/CSS/JS via SSR or static export
– Connects to FastAPI over WebSocket for chat messages
– May proxy API calls (or direct-fetch to backend API_URL)
c. FastAPI Backend
– HTTP endpoints (if any future REST calls)
– WebSocket endpoint (/ws/chat) managed by connection_manager
d. Connection Manager (in-memory)
– Tracks active WebSocket connections
– Broadcasts incoming messages to all connected clients
e. External Services (none currently, but room for DB or authentication service)

##### Architectural patterns & design principles
- Separation of concerns: UI layer (Next.js) vs. communication layer (FastAPI)
- Real-time pub/sub: WebSocket connections managed by a central broadcast manager
- Modular routers in FastAPI (chat.py) and dependency injection for manager

##### Putting it all together
– Label: Next.js + TailwindCSS
– Inside it, nest “Chat Router (/ws)” and “Connection Manager”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    U["User Browser"]:::client
    U -->|"HTTP GET (SSR page load)"| NL
    U -->|"WebSocket handshake & messages"| CR

    %% Frontend Layer
    subgraph "Next.js Frontend" 
        direction TB
        NL["Layout & Entry Points"]:::frontend
        NP["Home Page (page.jsx)"]:::frontend
        CP["Chat Page (Chat.jsx)"]:::frontend
        NP2["Name Page (Name.jsx)"]:::frontend
        MC["Message Component"]:::frontend
        NC["NavBar Component"]:::frontend
        CFG["Configuration Files"]:::config
    end

    NL -->|serves UI| U
    NL -->|loads Page| NP
    NL -->|loads Page| NP2
    NP -->|uses Components| MC
    NP2 -->|uses Components| NC
    CFG -.-> NL

    %% Backend Layer
    subgraph "FastAPI Backend"
        direction TB
        FB["FastAPI Server"]:::backend
        CR["Chat Router (/ws/chat)"]:::backend
        CM["Connection Manager"]:::pubsub
        REQ["requirements.txt"]:::config
    end

    FB --> CR
    CR --> CM
    CM --> CR
    FB -->|CORS & REST| U

    %% Future Persistence
    P["Future Persistence (DB)"]:::persistence
    P -.-> CM

    %% Data Flows
    NL -->|"WS connect & messages"| CR
    CR -->|"broadcast messages"| NL

    %% Click events
    click NL "https://github.com/dheerajroy/worldchat/blob/main/client/app/layout.jsx"
    click NP "https://github.com/dheerajroy/worldchat/blob/main/client/app/page.jsx"
    click CP "https://github.com/dheerajroy/worldchat/blob/main/client/app/pages/Chat.jsx"
    click NP2 "https://github.com/dheerajroy/worldchat/blob/main/client/app/pages/Name.jsx"
    click MC "https://github.com/dheerajroy/worldchat/blob/main/client/app/components/Message.jsx"
    click NC "https://github.com/dheerajroy/worldchat/blob/main/client/app/components/NavBar.jsx"
    click CFG "https://github.com/dheerajroy/worldchat/blob/main/client/jsconfig.json"
    click CFG "https://github.com/dheerajroy/worldchat/blob/main/client/next.config.js"
    click CFG "https://github.com/dheerajroy/worldchat/blob/main/client/tailwind.config.js"
    click FB "https://github.com/dheerajroy/worldchat/blob/main/server/app/main.py"
    click CR "https://github.com/dheerajroy/worldchat/blob/main/server/app/routers/chat.py"
    click CM "https://github.com/dheerajroy/worldchat/blob/main/server/app/dependencies/connection_manager.py"
    click REQ "https://github.com/dheerajroy/worldchat/blob/main/server/requirements.txt"
    click P "https://github.com/dheerajroy/worldchat/blob/main/README.md"
    click U "https://github.com/dheerajroy/worldchat/blob/main/.gitignore"

    %% Styles
    classDef client fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef frontend fill:#e8f4fc,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#f0f8ff,stroke:#036,stroke-width:1px
    classDef pubsub fill:#fff4e5,stroke:#d97706,stroke-width:1px
    classDef config fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,stroke-dasharray: 2 2
    classDef persistence fill:#f5e1ff,stroke:#9333ea,stroke-width:1px,stroke-dasharray: 2 2
```
