# zero-squared/open-chats architecture

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

- Interactive diagram: https://gitdiagram.com/zero-squared/open-chats
- Repository: https://github.com/zero-squared/open-chats

## Overview

##### Project type and purpose
- This is a full-stack, real-time chat platform (open-chats) implemented in Node.js/Express.
- It combines server-rendered UI (EJS templates under views), a RESTful API (controllers/api), static assets (public), and a WebSocket layer for live chats (sockets/index.js).

##### File structure
- Top-level components:
- app.js – entry point, configures Express, middleware, routes, and socket server.
- controllers – handles HTTP logic (main pages, admin, API).
- routes – maps URLs to controllers (mainRoutes.js, apiRoutes.js).
- models – data layer (chat, message, user, label, role, index.js for ORM/Mongoose).
- views & public – frontend: EJS templates + CSS/JS assets.
- sockets – real-time event handlers (socket.io integration).
- middleware & utils – session management, uploads, auth guards, config, ImageKit integration.
- setup – initial seed and configuration.
- Architectural choice: classic MVC augmented with a WebSocket “micro-layer” for live communication.

##### Key insights from README
- Requirements: Node v22, pnpm, pm2.
- Two modes: development (pnpm run dev) and production (pm2).
- .env files drive environment-specific config.

##### Main components
a. Frontend (Client Browser)
- EJS-rendered pages (home, login, register, profile, chats, admin).
- Static JS modules handle UI logic (public/js) and establish socket.io connections.
b. Backend (Express Server)
- HTTP layer:
- Routes → Controllers (mainController, chatViewController, adminController).
- API layer: REST endpoints (auth, chat, message, user, label, localization).
- WebSocket layer: sockets/index.js for real-time chat events.
- Middleware: session management, authentication checks, file uploads (multerUpload), locals injection.
- Utilities: config loader, session helpers, ImageKit API wrapper, message templates.
c. Database
- Models: user, role, chat, message, label.
- ORM or ODM (configured in models/index.js).
- Session store (if using a DB-backed session).
d. External services
- ImageKit (for avatar/storage).
- (Optionally) Email or push services if extended.
e. Deployment
- pm2 process manager.
- Environment variables (.env.dev, .env.prod).

##### Relationships & interactions
- Browser ↔ HTTP(S) Express
- GET pages, POST forms, AJAX/API fetches.
- Browser ↔ WebSocket Express
- Real-time chat events: send message, receive broadcast.
- Express → Database
- CRUD via models for users, chats, messages, labels.
- Express → External API (ImageKit)
- Upload and fetch images.
- Express (session middleware) ↔ session store (could be in-memory or DB).

##### Architectural patterns & design principles
- MVC for server-rendered views.
- Layered services: routing, controller, service/util, data access.
- Event-driven micro-layer for WebSocket.
- Separation of concerns: admin vs. user controllers, API vs. view controllers.
- Config-driven by environment variables.

##### Detailed elements
- app.js as the central orchestrator.
- middleware chain (session → user auth → locals).
- controllers split: view vs. API vs. admin.
- models cluster around the DB.
- static asset pipeline (public folder).
- setup/seed process as a side note.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client (Browser UI)"
        direction TB
        EJS["EJS Templates"]:::ui
        Static["Static Assets (CSS/JS)"]:::ui
        SocketClient["Socket.IO Client"]:::ui
    end

    %% HTTP/API Layer
    subgraph "HTTP/API Layer"
        direction TB
        App["app.js"]:::server
        subgraph "Routes"
            direction TB
            MainRoutes["mainRoutes.js"]:::server
            APIRoutes["apiRoutes.js"]:::server
        end
        subgraph "Controllers"
            direction TB
            ViewMain["mainController.js"]:::server
            ViewChat["chatViewController.js"]:::server
            ViewAdmin["adminController.js"]:::server
            subgraph "API Controllers"
                direction TB
                AuthAPI["authController.js"]:::server
                ChatAPI["chatController.js"]:::server
                LabelAPI["labelController.js"]:::server
                LocAPI["localizationController.js"]:::server
                MsgAPI["messageController.js"]:::server
                UserAPI["userController.js"]:::server
            end
        end
        subgraph "Middleware"
            direction TB
            SessionMW["session.js"]:::server
            AuthMW["user.js"]:::server
            LocalsMW["locals.js"]:::server
            UploadMW["multerUpload.js"]:::server
        end
        subgraph "Utilities"
            direction TB
            ConfigUtil["config.js"]:::server
            ImageKitUtil["imageKitApi.js"]:::server
            MessagesUtil["messages.js"]:::server
            SessionUtil["session.js"]:::server
            UsersUtil["users.js"]:::server
        end
    end

    %% Real-time Layer
    subgraph "Real-time Layer"
        direction TB
        SocketServer["sockets/index.js"]:::realtime
    end

    %% Data & External Layer
    subgraph "Data & External"
        direction TB
        DB["Database"]:::db
        SessionStore["Session Store"]:::db
        ImageKit["ImageKit API"]:::external
    end

    %% Connections
    EJS -->|renders via HTTP| App
    Static -->|assets served| App
    SocketClient ---|WebSocket| SocketServer
    App -->|uses routes| MainRoutes
    App -->|uses routes| APIRoutes
    MainRoutes -->|calls| ViewMain
    MainRoutes -->|calls| ViewChat
    MainRoutes -->|calls| ViewAdmin
    APIRoutes -->|calls| AuthAPI
    APIRoutes -->|calls| ChatAPI
    APIRoutes -->|calls| LabelAPI
    APIRoutes -->|calls| LocAPI
    APIRoutes -->|calls| MsgAPI
    APIRoutes -->|calls| UserAPI
    App -->|registers| SessionMW
    App -->|registers| AuthMW
    App -->|registers| LocalsMW
    App -->|registers| UploadMW
    ViewMain -->|queries| DB
    ViewChat -->|queries| DB
    ViewAdmin -->|queries| DB
    AuthAPI -->|CRUD| DB
    ChatAPI -->|CRUD| DB
    LabelAPI -->|CRUD| DB
    LocAPI -->|CRUD| DB
    MsgAPI -->|CRUD| DB
    UserAPI -->|CRUD| DB
    SocketServer -->|uses models| DB
    App -->|calls| ConfigUtil
    App -->|calls| SessionUtil
    App -->|calls| UsersUtil
    AuthMW -->|calls| SessionUtil
    UploadMW -->|calls| ImageKitUtil
    SocketServer -->|calls| MessagesUtil
    App -->|stores sessions| SessionStore
    App -->|calls external| ImageKit
    DB --- SessionStore

    %% Click Events
    click App "https://github.com/zero-squared/open-chats/blob/main/app.js"
    click MainRoutes "https://github.com/zero-squared/open-chats/blob/main/routes/mainRoutes.js"
    click APIRoutes "https://github.com/zero-squared/open-chats/blob/main/routes/apiRoutes.js"
    click ViewMain "https://github.com/zero-squared/open-chats/blob/main/controllers/mainController.js"
    click ViewChat "https://github.com/zero-squared/open-chats/blob/main/controllers/chatViewController.js"
    click ViewAdmin "https://github.com/zero-squared/open-chats/blob/main/controllers/adminController.js"
    click AuthAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/authController.js"
    click ChatAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/chatController.js"
    click LabelAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/labelController.js"
    click LocAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/localizationController.js"
    click MsgAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/messageController.js"
    click UserAPI "https://github.com/zero-squared/open-chats/blob/main/controllers/api/userController.js"
    click SocketServer "https://github.com/zero-squared/open-chats/blob/main/sockets/index.js"
    click DB "https://github.com/zero-squared/open-chats/blob/main/models/index.js"
    click SessionStore "https://github.com/zero-squared/open-chats/blob/main/models/index.js"
    click ConfigUtil "https://github.com/zero-squared/open-chats/blob/main/utils/config.js"
    click ImageKitUtil "https://github.com/zero-squared/open-chats/blob/main/utils/imageKitApi.js"
    click MessagesUtil "https://github.com/zero-squared/open-chats/blob/main/utils/messages.js"
    click SessionUtil "https://github.com/zero-squared/open-chats/blob/main/utils/session.js"
    click UsersUtil "https://github.com/zero-squared/open-chats/blob/main/utils/users.js"
    click SessionMW "https://github.com/zero-squared/open-chats/blob/main/middleware/session.js"
    click AuthMW "https://github.com/zero-squared/open-chats/blob/main/middleware/user.js"
    click LocalsMW "https://github.com/zero-squared/open-chats/blob/main/middleware/locals.js"
    click UploadMW "https://github.com/zero-squared/open-chats/blob/main/middleware/multerUpload.js"
    click Static "https://github.com/zero-squared/open-chats/tree/main/public/"
    click EJS "https://github.com/zero-squared/open-chats/tree/main/views/"
    click ImageKit "https://github.com/zero-squared/open-chats/blob/main/utils/imageKitApi.js"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef realtime fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#D2691E,stroke:#333,stroke-width:1px
    classDef external fill:#87CEEB,stroke:#333,stroke-width:1px
```
