# codingminions/whatsapp-lite architecture

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

- Interactive diagram: https://gitdiagram.com/codingminions/whatsapp-lite
- Repository: https://github.com/codingminions/whatsapp-lite

## Overview

##### Project type and purpose
- A full-stack, monolithic chat application written in Go
- Exposes HTTP endpoints for registration, login and serves HTML templates + CSS under /web
- Provides real-time messaging via WebSockets
- Persists users, sessions, and messages in a Postgres database

##### File structure
- cmd/server/main.go — the application entry point (starts HTTP & WS server)
- configs/ — global configuration loader (YAML + Go binding)
- internal/… — business logic, organized by domain (auth, user, conversation, websocket)
– handler.go → HTTP handlers
– service.go → domain logic
– repository.go → data access
– middleware.go (auth)
– websocket/hub.go, client.go → real-time hub
- pkg/… — shared utilities
– pkg/database/postgres.go → DB connection
– pkg/logger/logger.go → logging
– pkg/token/jwt.go → JWT generation/validation
– pkg/validator/validator.go → input validation
- migrations/ — SQL migrations for Postgres schema
- web/ — static assets and HTML templates
- test_*.go — integration/unit tests
- Makefile — bootstraps Postgres on macOS and runs the server

##### README
- Purpose: minimal real-time chat (1k concurrent users)
- Startup: `make postgres_setup_complete` → `go run cmd/server/main.go` → visit port 8080
- No external microservices; pure monolith

##### Main components & interactions
a. CLIENT LAYER
- Web Browser
– Loads static assets (CSS, JS if any) & HTML templates via HTTP GET
– Initiates WebSocket connection for real-time messaging
b. SERVER LAYER
- HTTP Server (Gin/Std-lib mux)
– Routes: /register, /login, /chat, /api/*
– middleware: JWT auth from pkg/token
– handlers in internal/auth, internal/user, internal/conversation
- WebSocket Hub
– Accepts WS handshake at /ws (internal/websocket/router.go)
– Maintains client registry (hub.go)
– Broadcasts direct & group messages to connected clients
c. SERVICE LAYER
- AuthService, UserService, ConversationService
– Encapsulate business rules
– Use pkg/validator for input checks
d. REPOSITORY LAYER
- Repository interfaces for users, sessions, messages, groups
- Implemented via pkg/database/postgres connection
e. DATABASE
- Postgres instance
- Tables: users, sessions, direct_messages, groups, group_members, group_messages
f. SUPPORTING UTILITIES
- Logger (pkg/logger)
- Config loader (configs/config.go reading config.yaml)
- Migrations folder (SQL scripts)

##### Architectural patterns & principles
- Layered architecture (Handler → Service → Repository)
- Separation of concerns
- Dependency injection via function parameters (e.g., pass repositories to services)
- Single binary monolith
- WebSocket “pub-sub” hub pattern

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client Layer"
    direction TB
    Browser["Web Browser"]:::client
    CSS["main.css"]:::client
    Index["index.html"]:::client
    Register["register.html"]:::client
    Login["login.html"]:::client
    Chat["chat.html"]:::client
  end

  %% Server Layer
  subgraph "Server Layer"
    direction TB
    HTTP["HTTP Server"]:::server

    subgraph "Auth Module"
      direction TB
      AuthHandler["Auth Handler"]:::server
      AuthMiddleware["Auth Middleware"]:::server
    end

    subgraph "User Module"
      direction TB
      UserHandler["User Handler"]:::server
    end

    subgraph "Conversation Module"
      direction TB
      ConvHandler["Conversation Handler"]:::server
    end

    subgraph "WebSocket Module"
      direction TB
      WSRouter["WS Router (/ws)"]:::server
      WSHandler["WebSocket Handler"]:::server
      Hub["WebSocket Hub"]:::server
      WSClient["WS Client"]:::server
    end
  end

  %% Service Layer
  subgraph "Service Layer"
    direction TB
    AuthService["AuthService"]:::business
    UserService["UserService"]:::business
    ConvService["ConversationService"]:::business
  end

  %% Repository Layer
  subgraph "Repository Layer"
    direction TB
    AuthRepo["Auth Repository"]:::data
    UserRepo["User Repository"]:::data
    ConvRepo["Conversation Repository"]:::data
    ConvTxRepo["Conversation Tx Repository"]:::data
  end

  %% Utilities
  subgraph "Utilities"
    direction TB
    Validator["Validator"]:::util
    JWT["JWT"]:::util
    Logger["Logger"]:::util
    DBConn["DB Connection"]:::util
    ConfigLoader["Config Loader"]:::util
    MakefileNode["Makefile"]:::util
  end

  %% Deployment & Setup
  subgraph "Deployment & Setup"
    direction TB
    Migrations["Migrations"]:::db
  end

  %% Tests
  subgraph "Tests"
    direction TB
    TestUsers["test_users.go"]:::util
    TestSave["test_save_message.go"]:::util
    TestTx["test_transaction.go"]:::util
  end

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

  %% Connections
  Browser -->|"HTTP GET/POST"| HTTP
  Browser -->|"WS Connect"| WSRouter
  HTTP --> AuthHandler
  HTTP --> UserHandler
  HTTP --> ConvHandler
  AuthHandler --> AuthService
  AuthMiddleware --> AuthHandler
  UserHandler --> UserService
  ConvHandler --> ConvService
  WSRouter --> WSHandler
  WSHandler --> Hub
  Hub --> ConvService

  AuthService --> Validator
  UserService --> Validator
  ConvService --> Validator
  AuthService --> AuthRepo
  UserService --> UserRepo
  ConvService --> ConvRepo
  ConvService --> ConvTxRepo

  AuthRepo -->|"SQL"| DB
  UserRepo -->|"SQL"| DB
  ConvRepo -->|"SQL"| DB
  ConvTxRepo -->|"SQL"| DB

  HTTP -->|"serve"| CSS
  HTTP -->|"serve"| Index
  HTTP -->|"serve"| Register
  HTTP -->|"serve"| Login
  HTTP -->|"serve"| Chat

  HTTP -->|"auth token"| JWT
  WSRouter -->|"validate token"| JWT

  ConfigLoader --> HTTP
  ConfigLoader --> Hub
  DBConn --> DB
  Logger -.-> HTTP
  Logger -.-> Hub
  MakefileNode -->|"runs migrations"| Migrations

  Migrations --> DB

  TestUsers --> HTTP
  TestSave --> ConvService
  TestTx --> ConvTxRepo

  %% Click Events
  click CSS "https://github.com/codingminions/whatsapp-lite/blob/main/web/static/css/main.css"
  click Index "https://github.com/codingminions/whatsapp-lite/blob/main/web/templates/index.html"
  click Register "https://github.com/codingminions/whatsapp-lite/blob/main/web/templates/register.html"
  click Login "https://github.com/codingminions/whatsapp-lite/blob/main/web/templates/login.html"
  click Chat "https://github.com/codingminions/whatsapp-lite/blob/main/web/templates/chat.html"
  click HTTP "https://github.com/codingminions/whatsapp-lite/blob/main/cmd/server/main.go"
  click ConfigLoader "https://github.com/codingminions/whatsapp-lite/blob/main/configs/config.go"
  click AuthHandler "https://github.com/codingminions/whatsapp-lite/blob/main/internal/auth/handler.go"
  click AuthMiddleware "https://github.com/codingminions/whatsapp-lite/blob/main/internal/auth/middleware.go"
  click AuthService "https://github.com/codingminions/whatsapp-lite/blob/main/internal/auth/service.go"
  click AuthRepo "https://github.com/codingminions/whatsapp-lite/blob/main/internal/auth/repository.go"
  click UserHandler "https://github.com/codingminions/whatsapp-lite/blob/main/internal/user/handler.go"
  click UserService "https://github.com/codingminions/whatsapp-lite/blob/main/internal/user/service.go"
  click UserRepo "https://github.com/codingminions/whatsapp-lite/blob/main/internal/user/repository.go"
  click ConvHandler "https://github.com/codingminions/whatsapp-lite/blob/main/internal/conversation/handler.go"
  click ConvService "https://github.com/codingminions/whatsapp-lite/blob/main/internal/conversation/service.go"
  click ConvRepo "https://github.com/codingminions/whatsapp-lite/blob/main/internal/conversation/repository.go"
  click ConvTxRepo "https://github.com/codingminions/whatsapp-lite/blob/main/internal/conversation/transaction_repository.go"
  click WSRouter "https://github.com/codingminions/whatsapp-lite/blob/main/internal/websocket/router.go"
  click WSHandler "https://github.com/codingminions/whatsapp-lite/blob/main/internal/websocket/handler.go"
  click Hub "https://github.com/codingminions/whatsapp-lite/blob/main/internal/websocket/hub.go"
  click WSClient "https://github.com/codingminions/whatsapp-lite/blob/main/internal/websocket/client.go"
  click Validator "https://github.com/codingminions/whatsapp-lite/blob/main/pkg/validator/validator.go"
  click JWT "https://github.com/codingminions/whatsapp-lite/blob/main/pkg/token/jwt.go"
  click Logger "https://github.com/codingminions/whatsapp-lite/blob/main/pkg/logger/logger.go"
  click DBConn "https://github.com/codingminions/whatsapp-lite/blob/main/pkg/database/postgres.go"
  click Migrations "https://github.com/codingminions/whatsapp-lite/tree/main/migrations/"
  click MakefileNode "https://github.com/codingminions/whatsapp-lite/tree/main/Makefile"
  click TestUsers "https://github.com/codingminions/whatsapp-lite/blob/main/test_users.go"
  click TestSave "https://github.com/codingminions/whatsapp-lite/blob/main/test_save_message.go"
  click TestTx "https://github.com/codingminions/whatsapp-lite/blob/main/test_transaction.go"

  %% Styles
  classDef client fill:#AED6F1,stroke:#1B4F72,color:#1B2631
  classDef server fill:#ABEBC6,stroke:#196F3D,color:#145A32
  classDef business fill:#F9E79F,stroke:#B7950B,color:#7D6608
  classDef data fill:#F5CBA7,stroke:#884EA0,color:#641E16
  classDef util fill:#D5D8DC,stroke:#2C3E50,color:#1B2631
  classDef db fill:#AEB6BF,stroke:#566573,color:#1B2631
```
