# poravv/message-sender architecture

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

- Interactive diagram: https://gitdiagram.com/poravv/message-sender
- Repository: https://github.com/poravv/message-sender

## Overview

##### Project Type and Purpose
- Full-stack, multi-tenant messaging platform
- Backend: Node.js/Express + Baileys for WhatsApp integration
- Frontend: Bootstrap single-page UI for CSV upload, progress, status
- Queue-driven mass messaging with Redis session & lock management
- Auth: Keycloak (external identity provider)
- Deployment: Docker, Docker Compose (local), Kubernetes (production)
- CI/CD: GitHub Actions → GHCR image → Kubernetes deploy

##### Main Components
1. Frontend (public/index.html + public/app.js + styles.css)
2. Backend API (app.js, src/… modules)
– HTTP API layer (src/routes.js)
– Auth module (src/auth.js + Keycloak integration)
– Queue manager (src/queue.js, src/queueRedis.js)
– Session manager & locks (src/sessionManager.js, src/redisLock.js)
– Media & storage (src/media.js, src/storage/s3.js)
– Business logic (src/manager.js)
3. Redis (session store + queue datastore + distributed locks)
4. WhatsApp Gateway (Baileys library connecting to WhatsApp network)
5. External Services
– Keycloak (OIDC provider)
– AWS S3 (object storage for media, optional)
6. Infrastructure
– Docker & Docker Compose
– Kubernetes cluster (namespace `sender`)
- Deployment + Service + HPA (backend)
- ConfigMap, Ingress (TLS via cert-manager), PodDisruptionBudget
– Nginx Proxy Manager (external reverse proxy for multi-tenant domains)
– GitHub Actions CI/CD pipeline

##### Relationships and Data Flow
- User’s browser → HTTP(S) → Nginx Ingress → Backend API
- Backend API ↔ Keycloak (token introspection) for authorization
- API publishes tasks to Redis queue → Worker components consume FIFO
- Worker logic uses Baileys to send messages to WhatsApp servers
- Media files processed locally → optionally uploaded to S3 → URLs returned
- Session state and locks maintained in Redis for concurrency control
- Logs emitted to console/files, auto-rotated (Docker logging/drivers)

##### Architectural Patterns & Design Principles
- Layered architecture: API → business layer → infrastructure services
- Event-driven/queue-based decoupling for high throughput and retry logic
- Distributed locking (Redis) for session safety across replicas
- Twelve-factor: config via environment variables, stateless containers
- Containerized micro-deployment (monolithic code, but container-oriented)
- CI/CD with immutable images and declarative Kubernetes manifests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        Frontend["Frontend UI"]:::frontend
    end

    %% Server Side
    subgraph "Server/Infra"
        %% API Layer
        subgraph "Express API Server"
            API["Express API<br/>(app.js)"]:::app
            Routes["Routes<br/>(src/routes.js)"]:::app
            AuthMod["Auth Module"]:::app
            API --> Routes
            API --> AuthMod
        end

        %% Worker & Messaging
        subgraph "Worker Subsystem"
            QueueM["Queue Manager"]:::app
            SessionM["Session Manager"]:::app
            RedisLock["Distributed Locks"]:::app
            Manager["Messaging Manager"]:::app
            Media["Media Handler"]:::app
            RedisDB["Redis"]:::datastore
            S3["AWS S3"]:::datastore
            WhatsApp["WhatsApp Network"]:::external

            API -->|publishes tasks| QueueM
            API -->|session ops| SessionM

            QueueM -->|FIFO tasks| Manager
            Manager -->|socket| WhatsApp
            Manager --> Media
            Media -->|upload| S3

            SessionM --> RedisDB
            RedisLock --> RedisDB
            QueueM --> RedisDB
        end

        %% External Auth
        subgraph "External Services"
            Keycloak["Keycloak OIDC"]:::external
            WhatsApp
            S3
        end

        API <-->|OIDC tokens| Keycloak

        %% Infrastructure
        subgraph "Infrastructure"
            NginxProxy["Nginx Proxy Manager"]:::infra
            Ingress["K8s Ingress"]:::infra
            Docker["Docker & Compose"]:::infra
            K8s["Kubernetes Cluster"]:::infra
            CICD["GitHub Actions CI/CD"]:::infra

            Frontend -->|HTTPS| NginxProxy
            NginxProxy -->|HTTPS| Ingress
            Ingress -->|HTTPS| API

            CICD -->|build & push| Docker
            Docker -->|deploy| K8s
            K8s --> Ingress
        end
    end

    %% Click Events - Frontend
    click Frontend "https://github.com/poravv/message-sender/blob/main/public/index.html"
    click Frontend "https://github.com/poravv/message-sender/blob/main/public/app.js"
    click Frontend "https://github.com/poravv/message-sender/blob/main/public/styles.css"

    %% Click Events - API Server
    click API "https://github.com/poravv/message-sender/blob/main/app.js"
    click Routes "https://github.com/poravv/message-sender/blob/main/src/routes.js"

    %% Click Events - Auth Module
    click AuthMod "https://github.com/poravv/message-sender/blob/main/src/auth.js"
    click AuthMod "https://github.com/poravv/message-sender/blob/main/src/auth/index.js"
    click AuthMod "https://github.com/poravv/message-sender/blob/main/KEYCLOAK_CONFIG.md"
    click AuthMod "https://github.com/poravv/message-sender/blob/main/scripts/reset-auth.js"

    %% Click Events - Queue Manager
    click QueueM "https://github.com/poravv/message-sender/blob/main/src/queue.js"
    click QueueM "https://github.com/poravv/message-sender/blob/main/src/queueRedis.js"

    %% Click Events - Session & Locks
    click SessionM "https://github.com/poravv/message-sender/blob/main/src/sessionManager.js"
    click SessionM "https://github.com/poravv/message-sender/blob/main/src/redisClient.js"
    click RedisLock "https://github.com/poravv/message-sender/blob/main/src/redisLock.js"

    %% Click Events - Business Logic
    click Manager "https://github.com/poravv/message-sender/blob/main/src/manager.js"

    %% Click Events - Media & Storage
    click Media "https://github.com/poravv/message-sender/blob/main/src/media.js"
    click S3 "https://github.com/poravv/message-sender/blob/main/src/storage/s3.js"

    %% Click Events - Infrastructure Files
    click Docker "https://github.com/poravv/message-sender/tree/main/Dockerfile"
    click Docker "https://github.com/poravv/message-sender/blob/main/docker-compose.yml"
    click NginxProxy "https://github.com/poravv/message-sender/blob/main/nginx.conf.example"
    click K8s "https://github.com/poravv/message-sender/blob/main/k8s/namespace.yaml"
    click K8s "https://github.com/poravv/message-sender/blob/main/k8s/configmap.yaml"
    click K8s "https://github.com/poravv/message-sender/blob/main/k8s/backend-deployment.yaml"
    click K8s "https://github.com/poravv/message-sender/blob/main/k8s/ingress.yaml"
    click K8s "https://github.com/poravv/message-sender/blob/main/k8s/pdb.yaml"
    click CICD "https://github.com/poravv/message-sender/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef app fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef datastore fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
```
