# sscoderin/chatrr architecture

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

- Interactive diagram: https://gitdiagram.com/sscoderin/chatrr
- Repository: https://github.com/sscoderin/chatrr

## Overview

##### Main Components
a. Frontend (Next.js)
- App‐Router pages under app/(pages)/chat for the chat UI
- Shared UI components under app/components (e.g., Header, SignIn/SignUp)
- Zustand stores (lib/store/useAuth.js, useChat.js) for client‐side state management
- Global layout (app/layout.tsx) and styling (globals.css)
b. Backend/API (Next.js API Routes)
- Auth routes (app/api/auth/*) for signup, signin, logout, update profile
- Message routes (app/api/message/*) for send, chats, contacts, chathistory
- pages/api/socket.js hosting the Socket.IO server for real‐time messaging
c. Middleware Layer
- arcjet.middleware.js for rate limiting/security
- auth.middleware.js and socket.auth.middleware.js to guard API & socket endpoints
d. Database
- MySQL instance (configured via lib/database_connect.js)
- Data models in models/MessageModel.js and models/UserModel.js
e. External Services
- Cloudinary for file hosting (images, avatars)
- Arcjet (ARCJET_KEY) for higher‐level security/rate‐limit
- JWT_SECRET used by auth middleware to sign/verify tokens

##### Relationships & Data Flows
- When a user visits the chat page, the Next.js frontend calls the auth API to validate or create a session
- Frontend uses useAuth store to hold user info, and useChat to manage real‐time message streams
- On successful sign‐in, the client opens a WebSocket (via Socket.IO) to pages/api/socket.js; socket.auth.middleware.js checks the JWT
- For each message sent:
– Frontend → Socket.IO channel → backend event handler in pages/api/socket.js
– Server persists to MySQL (via MessageModel)
– Server broadcasts to other clients in the same chat room
- For retrieving chat history or contact lists, the client hits RESTful endpoints in app/api/message/* (protected by auth.middleware.js)
- Arcjet middleware is applied globally to HTTP routes to throttle/secure API calls

##### Architectural Patterns & Principles
– Separation of Concerns:
- Presentation (components under app/(pages)/chat)
- Client State Management (Zustand stores)
- API Layer (Next.js API routes)
- Database Access Layer (lib/database_connect.js + models/)
- Middleware for cross‐cutting concerns (auth, rate‐limit)
– Real‐time event‐driven messaging with WebSockets (Socket.IO)
– Token‐based authentication (JWT)
– Environment‐driven configuration (via `.env`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Boundary
    subgraph "Client"
        direction TB
        NextJS["Next.js Frontend"]:::frontend
        UIComponents["UI Components<br/>(ChatList, ChatSection, SignIn, SignUp, etc.)"]:::frontend
        ZustandStores["Zustand Stores<br/>(useAuth, useChat)"]:::state
    end

    %% Server Boundary
    subgraph "Server"
        direction TB
        subgraph "API Layer"
            direction TB
            AuthAPI["Auth API<br/>(signup, signin, logout, updateprofile)"]:::backend
            MessageAPI["Message API<br/>(send, chats, contacts, chathistory)"]:::backend
        end
        SocketServer["Socket.IO Server<br/>(pages/api/socket.js)"]:::backend

        %% Middleware
        ArcjetMW["arcjet.middleware.js"]:::middleware
        AuthMW["auth.middleware.js"]:::middleware
        SocketAuthMW["socket.auth.middleware.js"]:::middleware
    end

    %% External & DB
    MySQL["MySQL Database"]:::db
    Cloudinary["Cloudinary Storage"]:::external
    ArcjetService["Arcjet Security Service"]:::external

    %% Client to Server Connections
    NextJS -->|"HTTP/HTTPS"| AuthAPI
    NextJS -->|"HTTP/HTTPS"| MessageAPI
    NextJS -->|"WebSocket"| SocketServer

    UIComponents --> ZustandStores
    ZustandStores --> NextJS

    %% Middleware Connections
    AuthAPI -->|guarded by| AuthMW
    MessageAPI -->|guarded by| AuthMW
    AuthAPI -->|throttled by| ArcjetMW
    MessageAPI -->|throttled by| ArcjetMW
    SocketServer -->|guarded by| SocketAuthMW

    %% Server to DB & External
    AuthAPI -->|"mysql2/ORM calls"| MySQL
    MessageAPI -->|"mysql2/ORM calls"| MySQL
    SocketServer -->|"mysql2/ORM calls"| MySQL

    NextJS -->|"file upload"| Cloudinary
    ArcjetService -->|integrates| ArcjetMW

    %% Click Events
    click NextJS "https://github.com/sscoderin/chatrr/tree/main/app/(pages)/chat"
    click UIComponents "https://github.com/sscoderin/chatrr/tree/main/app/(pages)/chat/_components"
    click UIComponents "https://github.com/sscoderin/chatrr/tree/main/app/components"
    click NextJS "https://github.com/sscoderin/chatrr/blob/main/app/layout.tsx"
    click NextJS "https://github.com/sscoderin/chatrr/blob/main/app/globals.css"
    click ZustandStores "https://github.com/sscoderin/chatrr/blob/main/lib/store/useAuth.js"
    click ZustandStores "https://github.com/sscoderin/chatrr/blob/main/lib/store/useChat.js"
    click AuthAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/auth/signup/route.js"
    click AuthAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/auth/signin/route.js"
    click AuthAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/auth/logout/route.js"
    click AuthAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/auth/updateprofile/route.js"
    click MessageAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/message/send/route.js"
    click MessageAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/message/chats/route.js"
    click MessageAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/message/contacts/route.js"
    click MessageAPI "https://github.com/sscoderin/chatrr/blob/main/app/api/message/chathistory/route.js"
    click SocketServer "https://github.com/sscoderin/chatrr/blob/main/pages/api/socket.js"
    click ArcjetMW "https://github.com/sscoderin/chatrr/blob/main/middleware/arcjet.middleware.js"
    click AuthMW "https://github.com/sscoderin/chatrr/blob/main/middleware/auth.middleware.js"
    click SocketAuthMW "https://github.com/sscoderin/chatrr/blob/main/middleware/socket.auth.middleware.js"
    click MySQL "https://github.com/sscoderin/chatrr/blob/main/lib/database_connect.js"
    click MySQL "https://github.com/sscoderin/chatrr/blob/main/models/MessageModel.js"
    click MySQL "https://github.com/sscoderin/chatrr/blob/main/models/UserModel.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef backend fill:#D0FFD8,stroke:#333,stroke-width:1px;
    classDef middleware fill:#FFE4B3,stroke:#333,stroke-width:1px;
    classDef db fill:#C0C0C0,stroke:#333,stroke-width:1px;
    classDef external fill:#E8E8E8,stroke:#333,stroke-width:1px;
    classDef state fill:#B3E5FC,stroke:#333,stroke-width:1px;
```
