Docker Swarm Stack Architecture
This is our multi-stack Docker Swarm setup. It leverages Docker Swarm to orchestrate containerized services across multiple nodes or on a single host. A central Traefik reverse proxy manages inbound requests by routing them to the appropriate service via domain-based rules.
Each stack is specialized, ranging from database services and bot development to rendering services and centralized logging. Below is a short overview diagram, followed by detailed service cards (with clickable links), and a draft list of business requirements.
Infrastructure Diagram
The diagram (img/infra_diagram.svg) highlights the major stacks,
services, and external integrations such as WhatsApp, operators, and customers
connecting to the system.
Traefik Stack
Central API Gateway & Reverse Proxy, handling domain-based routing for all microservices. Also includes ngrok to securely expose services to the public when needed.
Traefik
Routes traffic for all stacks using Docker & file providers. Primary entry point for domain-based requests.
ngrok-traefik
Exposes Traefik externally, generating secure public URLs for local services. Useful for remote testing or integration.
DB Stack
Provides a global MySQL/MariaDB database and a phpMyAdmin interface for management (reachable at storage.localhost).
mysqldb
Central MySQL/MariaDB instance used by multiple services across stacks.
phpMyAdmin (Global DB)
Convenient UI for administering the global database.
Bots Dev Stack
A suite of development-oriented bot services, each with its own domain. Redis is used as a shared caching layer for high performance. Some bots can also integrate with WhatsApp.
wtfast-dev-riccio
Bot accessible at devriccio.localhost. Supports "reply" flows and example docs at /docs.
wtfast-dev-ranni
Bot accessible at devranni.localhost. Another "reply" bot with docs at /docs.
wtfast-dev-machinga
Bot accessible at machinga.localhost
wtfast-officer
Bot accessible at officer.localhost. A web-based maintenance service (no separate docs link).
redis-cache
A shared Redis instance that provides caching for all bots to reduce latency.
Dashboard Stack
Laravel-based dashboard for system management and monitoring. Has its own dedicated database and phpMyAdmin interface.
dashboard-app
Laravel application served at dash.localhost. Used for internal management and monitoring tasks.
dashboard-db
MariaDB instance dedicated to the dashboard. Stores config, user data, and more.
phpMyAdmin (Dashboard)
Managing the dashboard-db. Usually accessible via a subdomain such as pma.render.localhost or similar.
Renderer Stack
Handles rendering and serves static/public files via Nginx. Includes a dedicated database and phpMyAdmin for data management.
renderer-backend
Core rendering service at render.localhost. Processes user requests and outputs. Docs at /docs.
renderer-nginx
Serves static/public files at media.localhost. Currently includes
images at .porcherface/1.png, 2.png, 3.png.
renderer-db
MySQL database used by the renderer-backend for job data. Integrates seamlessly with rendering processes.
renderer-pma
Dedicated phpMyAdmin instance for the renderer DB, accessible at pma.render.localhost.
Logger Stack
Centralized logging solution with a NestJS backend and a browser-based dashboard. Collects logs from all microservices and stores them in a dedicated database.
wapiulogger-mariadb
Database for all system logs, ensuring historical records and analytics.
wapiulogger-pma
phpMyAdmin interface for inspecting and managing the logger DB.
wapiulogger-backend
A NestJS service that receives log data, persists it, and exposes an API for log retrieval or analysis.
wapiulogger-frontend
The logging dashboard at logger.localhost. Contains search, filter, and real-time stream features. May also have docs at /docs.
Websites Stack
Collection of static websites. Contains waPiu's website and this documentation
www
The main website at www.localhost. Contains a single page placeholder.
docs
This document
Connections & Data Flows
Services are deployed in Docker Swarm, connected by dedicated networks. Traefik handles inbound requests and routes traffic to each stack via domain name rules. Some key flows:
- ngrok → Traefik: External public URLs for development/testing.
- Traefik → devriccio/devranni/machinga/officer: Bot requests at respective domains.
- Traefik → dash.localhost: Dashboard management interface.
- Traefik → render.localhost/media.localhost: Render services and static file hosting.
- Traefik → logger.localhost: Logging dashboard UI.
- Redis cache: Shared among bots for quick data lookups.
- Dashboard DB, Renderer DB, Logger DB: Each stack has a dedicated database for isolation and performance.
- phpMyAdmin: Various PMA interfaces for direct DB management.
- External Integrations (WhatsApp, operators, customers): Real-time messaging, logs, or web traffic from outside the cluster.
System Requirements (Draft)
Below is a static listing of our preliminary business requirements (BR) and associated details. This is a placeholder for a future automated docs pipeline.
| Requirement Code |
Description | Requirements | Infrastructures |
|---|---|---|---|
| BR01-01 | Our services must be reachable using WhatsApp |
|
|
| BR01-02 | Our services must be reachable using RCS |
|
|
| BR02-01 | Our services must be able to respond with an automated chatbot |
|
|
| BR02-02 | Our services must be able to send marketing and service campaigns |
|
|
| BR02-03 | Our services must allow customers to reply individually to users |
|
|
| BR02-04 | Our services must be highly customizable |
|
|
| BR03-01 | Our services must ensure maximal uptimes and operational resilience |
|
|
| BR03-02 | Our services must ensure fault tolerance |
|
|
| BR03-03 | Our services must ensure fast responses |
|
|
| BR03-04 | Our services must ensure data safety |
|
|
| BR03-05 | Our services must ensure data persistence |
|
|
| BR03-06 | Our services must ensure communication safety |
|
|
| BR04-01 | Our services must be able to deploy continuously |
|
|
| BR04-02 | Our services must be able to fix immediately |
|
|
| BR04-03 | Our services must be able to release continuously |
|
|
| BR04-04 | Our services must be able to adapt to tech changes |
|
|
| BR05-01 | Our services must log all processed data |
|
|
| BR05-02 | Our services must transmit customers relevant data |
|
|
| BR05-03 | Our services must allow customers to use their data |
|
|
| BR05-04 | Our services must ensure all customer data is protected |
|
|
| BR06-01 | Our services must be able to integrate anytime with external actors |
|
|
| BR06-02 | Our services must ensure low integration downtimes |
|
|
| BR06-03 | Our services must ensure integration protection |
|
|
| BR06-04 | Our services must ensure retrocompatibility |
|
|
| BR07-01 | Our services must provide a user-friendly interface for non-technical users |
|
|
| BR07-02 | Our services must facilitate guided onboarding |
|
|
| BR07-03 | Our services must provide up-to-date documentation & tutorials |
|
|
| BR07-04 | Our services must offer support channels |
|
|