# jamesnpe13/comms-app architecture

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

- Interactive diagram: https://gitdiagram.com/jamesnpe13/comms-app
- Repository: https://github.com/jamesnpe13/comms-app

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time messaging web application (“Comms-App”) built with a React SPA frontend and an Express/MySQL backend. It provides user registration, authentication (JWT), RESTful APIs for user and message management, and WebSocket-based real-time chat via Socket.IO.

##### Main Components
a. Frontend (client/)
- React SPA using React Router for navigation
- Context providers for Auth, Messaging, and Socket
- axiosInstance for REST calls to the backend
- Socket.IO client for real-time message delivery
- UI components (layout, panes, tiles, modals) and SCSS styling
b. Backend (server/)
- Express.js server handling REST endpoints (auth, users, messaging)
- Socket.IO server integrated into Express for bidirectional events
- Middleware chain for JWT authentication, role authorization, password hashing and error handling
- Controllers for business logic (authController, messagingController, usersController)
- Database layer with MySQL connection, migrations, and normalized tables (users, chat_rooms, messages, memberships)
c. Database
- MySQL instance (hosted locally or in managed service)
- Tables: users, chat_rooms, messages, room_memberships
- Indexed for efficient querying by timestamp and room
d. External Services & Deployment
- Vercel (or CDN) hosting static React build
- Railway (or similar PaaS) hosting Node/Express app
- Load balancer / API gateway (for horizontal scaling of stateless backend)
- Environment variables for secrets, database credentials, CORS origin

##### Interactions and Data Flow
- User opens React SPA → React Router loads pages (Login, Registration, Dashboard).
- On login/registration → axiosInstance sends REST call → Express authController → MySQL → returns JWTs.
- React stores tokens (browserStorage utility) and initializes Socket.IO connection with access token header.
- Real-time messaging:
- Client emits “join_room”, “send_message” events to Socket.IO server.
- Server validates token → emits message to room namespace → broadcast to subscribers.
- Clients listen for “receive_message” events to update UI.
- Protected API routes use authenticateToken and authorizeUser middleware.

##### Architectural Patterns & Design Principles
- Client-Server separation (SPA + REST + WebSockets)
- Layered architecture: Presentation (React), Application (Express controllers, middleware), Data (MySQL)
- Stateless backend (JWT allows horizontal scaling)
- Pub/Sub messaging via Socket.IO rooms
- Modular code organization (controllers, routes, middleware, database migrations)

##### Capturing Essential Architectural Elements
- Authentication flow (login → token issuance → token storage → token refresh)
- Real-time messaging flow (join room, send/receive message)
- Data persistence (MySQL read/write)
- How future clients (e.g., mobile or desktop) could plug into the same REST + Socket.IO layer.
- Scalability: stateless servers behind a load balancer, CDN for frontend.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    Vercel["Vercel/CDN"]:::external
    LB["Load Balancer"]:::external
    Railway["Railway (Backend)"]:::external
    Mobile["Other Clients"]:::external

    %% Frontend Layer
    subgraph "Frontend (Client)" 
        clientDir["client/"]:::frontend
        App["App.js"]:::frontend
        Router["routeConfig.js"]:::frontend
        AuthCtx["AuthContext.js"]:::frontend
        MsgCtx["MessagingContext.js"]:::frontend
        SocketCtx["SocketContext.js"]:::frontend
        Axios["axiosInstance.js"]:::frontend
        Requests["requests.js"]:::frontend
        SocketClient["socket.js"]:::frontend
        Layout["Layout Components"]:::frontend
        Panes["Pane Components"]:::frontend
        UI["UI Tiles & Modals"]:::frontend
        Styles["SCSS Styles"]:::frontend
        Utils["Utility Functions"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Server)" 
        ServerEntry["server.js"]:::backend
        Routes["routes.js"]:::backend
        AuthMw["authenticateToken.js"]:::backend
        AuthzMw["authorizeUser.js"]:::backend
        HashMw["hashPassword.js"]:::backend
        ErrorMw["errorHandler.js"]:::backend
        AuthCtrl["authController.js"]:::backend
        MsgCtrl["messagingController.js"]:::backend
        UsersCtrl["usersController.js"]:::backend
        SocketServer["Socket.IO Server"]:::backend
        DBConn["DB Connection"]:::backend
        Migrations["Migrations"]:::backend
        Functions["Shared Functions"]:::backend
    end

    %% Database
    DB["MySQL Database"]:::db

    %% Interactions
    Vercel --> App
    App --> Router
    App --> AuthCtx
    App --> MsgCtx
    App --> SocketCtx
    App --> Layout
    App --> Panes
    App --> UI
    App --> Styles
    App --> Utils

    App --> Axios
    Axios -->|REST requests| LB
    LB --> ServerEntry
    LB -->|route ws| SocketServer

    SocketClient -.->|WebSocket events| SocketServer
    SocketServer -.->|WebSocket events| SocketClient

    ServerEntry --> Routes
    Routes --> AuthMw
    AuthMw --> AuthzMw
    AuthzMw --> HashMw
    HashMw --> ErrorMw
    ErrorMw --> AuthCtrl
    ErrorMw --> MsgCtrl
    ErrorMw --> UsersCtrl

    AuthCtrl --> DBConn
    MsgCtrl --> DBConn
    UsersCtrl --> DBConn
    DBConn -->|queries| DB

    ServerEntry --> Functions
    ServerEntry --> Migrations

    Mobile -->|REST| LB
    Mobile -.->|WebSocket| SocketServer

    %% Click Events - Frontend
    click clientDir "https://github.com/jamesnpe13/comms-app/tree/main/client/"
    click App "https://github.com/jamesnpe13/comms-app/blob/main/client/src/App.js"
    click Router "https://github.com/jamesnpe13/comms-app/blob/main/client/src/routeConfig.js"
    click AuthCtx "https://github.com/jamesnpe13/comms-app/blob/main/client/src/context/AuthContext.js"
    click MsgCtx "https://github.com/jamesnpe13/comms-app/blob/main/client/src/context/MessagingContext.js"
    click SocketCtx "https://github.com/jamesnpe13/comms-app/blob/main/client/src/context/SocketContext.js"
    click Axios "https://github.com/jamesnpe13/comms-app/blob/main/client/src/api/axiosInstance.js"
    click Requests "https://github.com/jamesnpe13/comms-app/blob/main/client/src/api/requests.js"
    click SocketClient "https://github.com/jamesnpe13/comms-app/blob/main/client/src/socket.js"
    click Layout "https://github.com/jamesnpe13/comms-app/tree/main/client/src/components/layout/"
    click Panes "https://github.com/jamesnpe13/comms-app/tree/main/client/src/components/panes/"
    click UI "https://github.com/jamesnpe13/comms-app/tree/main/client/src/components/ui/"
    click Styles "https://github.com/jamesnpe13/comms-app/blob/main/client/src/styles/main.scss"
    click Utils "https://github.com/jamesnpe13/comms-app/blob/main/client/src/utils/browserStorage.js"

    %% Click Events - Backend
    click ServerEntry "https://github.com/jamesnpe13/comms-app/blob/main/server/server.js"
    click Routes "https://github.com/jamesnpe13/comms-app/blob/main/server/routes/routes.js"
    click AuthMw "https://github.com/jamesnpe13/comms-app/blob/main/server/middleware/authenticateToken.js"
    click AuthzMw "https://github.com/jamesnpe13/comms-app/blob/main/server/middleware/authorizeUser.js"
    click HashMw "https://github.com/jamesnpe13/comms-app/blob/main/server/middleware/hashPassword.js"
    click ErrorMw "https://github.com/jamesnpe13/comms-app/blob/main/server/middleware/errorHandler.js"
    click AuthCtrl "https://github.com/jamesnpe13/comms-app/blob/main/server/controllers/authController.js"
    click MsgCtrl "https://github.com/jamesnpe13/comms-app/blob/main/server/controllers/messagingController.js"
    click UsersCtrl "https://github.com/jamesnpe13/comms-app/blob/main/server/controllers/usersController.js"
    click DBConn "https://github.com/jamesnpe13/comms-app/blob/main/server/database/connection.js"
    click Migrations "https://github.com/jamesnpe13/comms-app/blob/main/server/database/migrations/create_tables.js"
    click Functions "https://github.com/jamesnpe13/comms-app/blob/main/server/functions.js"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9,stroke-width:1px
    classDef backend fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef db fill:#FAD7A0,stroke:#D68910,stroke-width:1px
    classDef external fill:#E5E7E9,stroke:#7B7D7D,stroke-width:1px
```
