# lukasccb/bmms architecture

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

- Interactive diagram: https://gitdiagram.com/lukasccb/bmms
- Repository: https://github.com/lukasccb/bmms

## Overview

##### Project type and purpose
- This is a backend API service built with Laravel.
- Purpose: allow clients to register phone numbers in bulk (via .docx, CSV or JSON) and asynchronously dispatch WhatsApp messages to those numbers using the ZipWhats external API.

##### File structure
- Standard Laravel MVC layout:
– app/Http/Controllers (RegisterNumberController, BulkSendController)
– app/Jobs (SendMessageJob)
– app/Models (User, App, Number, SentHistory)
– routes/api.php, routes/web.php, etc.
- Configuration and environment: .env, config/*.php
- Storage of uploaded files: storage/app/private
- Database migrations/seeders under database/…
- Public entrypoint: public/index.php
- Queue processing: php artisan queue:work

##### README for additional insights
- Two endpoints:
– POST /api/add-bulk-number → parses uploaded file, persists Numbers in database
– POST /api/bulk-send-file → dispatches SendMessageJob jobs to the queue
- Worker processes the queue and calls the ZipWhats API for each number
- Uses Laravel’s built-in queue system, Eloquent ORM, and filesystem

##### Thoroughness
- Asynchronous paths and retry/failure flows if relevant.
- Notes for configuration points (e.g. .env values for queue connection, API keys).
- Don’t under-represent the Worker and external API – they are core to the bulk sending function.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Client"]:::client

    %% API Gateway / Load Balancer
    Gateway["API Gateway / Load Balancer"]:::internal

    %% Web Server
    WebServer["Web Server\n(public/index.php)"]:::internal
    click WebServer "https://github.com/lukasccb/bmms/blob/main/public/index.php"

    %% Laravel Application
    subgraph "Laravel Application"
        API_Routes["API Routes\n(routes/api.php)"]:::internal
        click API_Routes "https://github.com/lukasccb/bmms/blob/main/routes/api.php"

        Web_Routes["Web Routes\n(routes/web.php)"]:::internal
        click Web_Routes "https://github.com/lukasccb/bmms/blob/main/routes/web.php"

        subgraph "Controllers"
            RegisterCtrl["RegisterNumberController"]:::internal
            click RegisterCtrl "https://github.com/lukasccb/bmms/blob/main/app/Http/Controllers/RegisterNumberController.php"
            BulkCtrl["BulkSendController"]:::internal
            click BulkCtrl "https://github.com/lukasccb/bmms/blob/main/app/Http/Controllers/BulkSendController.php"
        end

        subgraph "Jobs"
            SendJob["SendMessageJob"]:::internal
            click SendJob "https://github.com/lukasccb/bmms/blob/main/app/Jobs/SendMessageJob.php"
        end

        subgraph "Models"
            NumberModel["Number Model"]:::internal
            click NumberModel "https://github.com/lukasccb/bmms/blob/main/app/Models/Number.php"
            SentHistoryModel["SentHistory Model"]:::internal
            click SentHistoryModel "https://github.com/lukasccb/bmms/blob/main/app/Models/SentHistory.php"
            UserModel["User Model"]:::internal
            click UserModel "https://github.com/lukasccb/bmms/blob/main/app/Models/User.php"
            AppModel["App Model"]:::internal
            click AppModel "https://github.com/lukasccb/bmms/blob/main/app/Models/App.php"
        end

        subgraph "Configuration"
            QueueConfig["Queue Config\n(config/queue.php)"]:::internal
            click QueueConfig "https://github.com/lukasccb/bmms/blob/main/config/queue.php"
            ServicesConfig["Services Config\n(config/services.php)"]:::internal
            click ServicesConfig "https://github.com/lukasccb/bmms/blob/main/config/services.php"
            FilesystemsConfig["Filesystem Config\n(config/filesystems.php)"]:::internal
            click FilesystemsConfig "https://github.com/lukasccb/bmms/blob/main/config/filesystems.php"
            CacheLoggingConfig["Cache & Logging Config\n(config/cache.php, config/logging.php)"]:::internal
            click CacheLoggingConfig "https://github.com/lukasccb/bmms/blob/main/config/cache.php"
        end
    end

    %% Infrastructure
    QueueBroker["Queue Broker\n(Redis/Database)"]:::queue
    QueueWorker["Queue Worker\n(artisan queue:work)"]:::internal
    click QueueWorker "https://github.com/lukasccb/bmms/tree/main/artisan"

    DB["Relational Database\n(MySQL/Postgres)"]:::persistent
    FileStorage["Filesystem Storage\n(storage/app/private)"]:::persistent
    click FileStorage "https://github.com/lukasccb/bmms/tree/main/storage/app/private"

    ExternalAPI["ZipWhats API"]:::external

    %% Data Flows
    Client -->|"HTTP POST"| Gateway --> WebServer --> API_Routes
    API_Routes -->|"POST /api/add-bulk-number"| RegisterCtrl
    API_Routes -->|"POST /api/bulk-send-file"| BulkCtrl

    RegisterCtrl -->|"store file"| FileStorage
    RegisterCtrl -->|"persist Number records"| DB

    BulkCtrl -->|"enqueue SendMessageJob"| QueueBroker
    QueueBroker -->|"job dispatch"| QueueWorker
    QueueWorker --> SendJob

    SendJob -->|"load Number"| DB
    SendJob -->|"invoke HTTP POST"| ExternalAPI
    ExternalAPI -->|"response status"| SendJob
    SendJob -->|"log SentHistory"| DB

    %% Optional synchronous read of web routes
    WebServer --> Web_Routes

    %% Class Definitions
    classDef internal fill:#D0E8FF,stroke:#026AA7,color:#026AA7;
    classDef persistent fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef queue fill:#FFE7BA,stroke:#D46A00,color:#D46A00;
    classDef external fill:#F0DFFF,stroke:#6B21A8,color:#6B21A8;
    classDef client fill:#EDEDED,stroke:#888888,color:#555555;
```
