# rodriguedev13/whatsapp-otp architecture

> Architecture diagram of the GitHub repository rodriguedev13/whatsapp-otp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rodriguedev13/whatsapp-otp
- Repository: https://github.com/rodriguedev13/whatsapp-otp

## Overview

This is a self-hosted WhatsApp OTP service: Laravel serves the user-facing dashboard and authenticated OTP API, while an internal Node sidecar manages the WhatsApp Web session and sends messages. The main transaction validates an API request, checks session readiness, then sends through the sidecar. Separate dashboard flows show status/QR and switch linked accounts; account login and API-key administration support those operations. The README documents the product boundaries and capabilities; source excerpts establish most calls, while links between the Laravel client and sidecar routes are HTTP-based.

Main entry points: [`app/routes/web.php`](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/routes/web.php) (Web routes), [`app/app/Services/WhatsAppEngineClient.php`](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Services/WhatsAppEngineClient.php) (Engine HTTP client), [`engine/src/routes.js`](https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/routes.js) (Engine endpoints), [`engine/src/whatsapp.js`](https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/whatsapp.js) (WhatsApp session engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_laravel["Laravel application"]
  node_web_routes["Web routes<br/>[web.php]"]
  node_api_routes["OTP API route<br/>[api.php]"]
  node_otp["OTP endpoint<br/>[OtpController.php]"]
  node_dashboard["Session dashboard"]
  node_engine_client["Engine HTTP client"]
  node_docs["Usage documentation<br/>[docs.blade.php]"]
end

subgraph group_access["Access and keys"]
  node_login["Login flow"]
  node_user["Admin user<br/>[User.php]"]
  node_api_key_admin["API-key management"]
  node_api_key_model["API-key records<br/>[ApiKey.php]"]
  node_key_auth["API-key authentication<br/>[ApiKeyAuth.php]"]
end

subgraph group_whatsapp["WhatsApp sidecar"]
  node_engine_server["Internal HTTP server<br/>[server.js]"]
  node_engine_routes["Engine endpoints<br/>[routes.js]"]
  node_wa_engine["WhatsApp session engine<br/>[whatsapp.js]"]
end

node_api_caller(("OTP integrator"))
node_admin(("Administrator"))
node_whatsapp_web["WhatsApp Web"]

node_web_routes -->|"routes to"| node_login
node_web_routes -->|"routes to"| node_dashboard
node_web_routes -->|"routes to"| node_api_key_admin
node_api_routes -->|"routes to"| node_otp
node_otp -->|"checks and sends"| node_engine_client
node_dashboard -->|"reads status, QR"| node_engine_client
node_admin -.->|"uses dashboard"| node_web_routes
node_api_caller -.->|"submits OTP"| node_api_routes
node_api_key_admin -->|"manages keys"| node_api_key_model
node_key_auth -->|"checks key"| node_api_key_model
node_login -.->|"authenticates"| node_user
node_engine_client -->|"HTTP requests"| node_engine_routes
node_engine_server -->|"mounts routes"| node_engine_routes
node_engine_server -->|"starts engine"| node_wa_engine
node_engine_routes -->|"dispatches operations"| node_wa_engine
node_wa_engine -.->|"controls session"| node_whatsapp_web
node_docs -.->|"documents API use"| node_api_caller

click node_web_routes "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/routes/web.php"
click node_api_routes "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/routes/api.php"
click node_otp "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/Api/OtpController.php"
click node_dashboard "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/DashboardController.php"
click node_engine_client "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Services/WhatsAppEngineClient.php"
click node_docs "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/resources/views/docs.blade.php"
click node_login "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/Auth/LoginController.php"
click node_user "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Models/User.php"
click node_api_key_admin "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/ApiKeyController.php"
click node_api_key_model "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Models/ApiKey.php"
click node_key_auth "https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Middleware/ApiKeyAuth.php"
click node_engine_server "https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/server.js"
click node_engine_routes "https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/routes.js"
click node_wa_engine "https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/whatsapp.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_routes,node_api_routes,node_otp,node_dashboard,node_engine_client,node_docs toneBlue
class node_login,node_user,node_api_key_admin,node_api_key_model,node_key_auth toneAmber
class node_engine_server,node_engine_routes,node_wa_engine toneMint
class node_api_caller,node_admin,node_whatsapp_web toneIndigo
```

## Components

### Laravel application

- [Web routes](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/routes/web.php): `app/routes/web.php`
- [OTP API route](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/routes/api.php): `app/routes/api.php`
- [OTP endpoint](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/Api/OtpController.php): `app/app/Http/Controllers/Api/OtpController.php`
- [Session dashboard](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/DashboardController.php): `app/app/Http/Controllers/DashboardController.php`
- [Engine HTTP client](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Services/WhatsAppEngineClient.php): `app/app/Services/WhatsAppEngineClient.php`
- [Usage documentation](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/resources/views/docs.blade.php): `app/resources/views/docs.blade.php`

### Access and keys

- [Login flow](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/Auth/LoginController.php): `app/app/Http/Controllers/Auth/LoginController.php`
- [Admin user](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Models/User.php): `app/app/Models/User.php`
- [API-key management](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Controllers/ApiKeyController.php): `app/app/Http/Controllers/ApiKeyController.php`
- [API-key records](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Models/ApiKey.php): `app/app/Models/ApiKey.php`
- [API-key authentication](https://github.com/rodriguedev13/whatsapp-otp/blob/master/app/app/Http/Middleware/ApiKeyAuth.php): `app/app/Http/Middleware/ApiKeyAuth.php`

### WhatsApp sidecar

- [Internal HTTP server](https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/server.js): `engine/src/server.js`
- [Engine endpoints](https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/routes.js): `engine/src/routes.js`
- [WhatsApp session engine](https://github.com/rodriguedev13/whatsapp-otp/blob/master/engine/src/whatsapp.js): `engine/src/whatsapp.js`

### Other components

- **OTP integrator**
- **Administrator**
- **WhatsApp Web**

## Connections

- Web routes → Login flow: routes to (evidence: `app/routes/web.php`)
- Web routes → Session dashboard: routes to (evidence: `app/routes/web.php`)
- Web routes → API-key management: routes to (evidence: `app/routes/web.php`)
- OTP API route → OTP endpoint: routes to (evidence: `app/routes/api.php`)
- OTP endpoint → Engine HTTP client: checks and sends (evidence: `app/app/Http/Controllers/Api/OtpController.php`)
- Session dashboard → Engine HTTP client: reads status, QR (evidence: `app/app/Http/Controllers/DashboardController.php`)
- Administrator → Web routes: uses dashboard (evidence: `README.md`)
- OTP integrator → OTP API route: submits OTP (evidence: `README.md`)
- API-key management → API-key records: manages keys (evidence: `app/app/Http/Controllers/ApiKeyController.php`)
- API-key authentication → API-key records: checks key (evidence: `app/app/Http/Middleware/ApiKeyAuth.php`)
- Login flow → Admin user: authenticates
- Engine HTTP client → Engine endpoints: HTTP requests (evidence: `app/app/Services/WhatsAppEngineClient.php`)
- Internal HTTP server → Engine endpoints: mounts routes (evidence: `engine/src/server.js`)
- Internal HTTP server → WhatsApp session engine: starts engine (evidence: `engine/src/server.js`)
- Engine endpoints → WhatsApp session engine: dispatches operations (evidence: `engine/src/routes.js`)
- WhatsApp session engine → WhatsApp Web: controls session (evidence: `README.md`)
- Usage documentation → OTP integrator: documents API use (evidence: `README.md`)
