# onlybot12/project-botweb architecture

> Architecture diagram of the GitHub repository onlybot12/project-botweb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onlybot12/project-botweb
- Repository: https://github.com/onlybot12/project-botweb

## Overview

This is a multi-user WhatsApp gateway with a web dashboard and command-driven bot. Users register and authenticate, manage bot connections, pair WhatsApp sessions, configure features, and exchange messages through their bots. Admins manage users, plans, sessions, and broadcasts. The core runtime receives WhatsApp events and dispatches messages to bot behavior, including group tools and media downloads. The excerpts show the main authentication, connection, bot, and persistence links; unsampled dashboard and route internals are represented only where the tree or excerpts support them.

Main entry points: [`utils/botHandler.js`](https://github.com/onlybot12/project-botweb/blob/main/utils/botHandler.js) (Command handler), [`utils/whatsapp.js`](https://github.com/onlybot12/project-botweb/blob/main/utils/whatsapp.js) (WhatsApp sessions), [`utils/database.js`](https://github.com/onlybot12/project-botweb/blob/main/utils/database.js) (Database access), [`routes/admin.js`](https://github.com/onlybot12/project-botweb/blob/main/routes/admin.js) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and accounts"]
  node_server["HTTP server<br/>[server.js]"]
  node_authroutes["Auth routes<br/>[auth.js]"]
  node_authmw["Token auth<br/>[auth.js]"]
  node_dashboard["Dashboard UI"]
  node_adminui["Admin UI"]
end

subgraph group_conn["WhatsApp connections"]
  node_connroutes["Connection routes<br/>[connection.js]"]
  node_connroutes2["Connection routes 2<br/>[connection2.js]"]
  node_wa["WhatsApp sessions<br/>[whatsapp.js]"]
end

subgraph group_bot["Bot runtime"]
  node_botdispatch["Message dispatch<br/>[whatsapp.js]"]
  node_handler["Command handler<br/>[botHandler.js]"]
  node_scraper["Media downloader<br/>[scraper.js]"]
  node_analytics["Bot analytics<br/>[botAnalytics.js]"]
end

subgraph group_ops["Administration and state"]
  node_adminroutes["Admin routes<br/>[admin.js]"]
  node_dbutil["Database access<br/>[database.js]"]
  node_db[("JSON database<br/>[database.json]")]
  node_sessions[("Session files")]
  node_config["Bot and plans config<br/>[config.js]"]
end

node_user(("User"))
node_admin(("Admin"))
node_whatsapp{{"WhatsApp service"}}
node_mediaapi{{"Downloader API"}}

node_user -->|"requests pages"| node_server
node_server -->|"renders dashboard"| node_dashboard
node_server -->|"renders admin"| node_adminui
node_server -->|"routes auth"| node_authroutes
node_authroutes -->|"reads and writes"| node_dbutil
node_authroutes -->|"protects profile"| node_authmw
node_authmw -->|"loads user"| node_dbutil
node_user -->|"manages connections"| node_connroutes
node_user -->|"manages connections"| node_connroutes2
node_connroutes -->|"checks token"| node_authmw
node_connroutes2 -->|"checks token"| node_authmw
node_connroutes -->|"starts pairing"| node_wa
node_connroutes2 -->|"starts or restarts"| node_wa
node_wa -->|"opens sessions"| node_whatsapp
node_wa -->|"reads and saves"| node_sessions
node_wa -->|"updates status"| node_dbutil
node_whatsapp -->|"delivers events"| node_botdispatch
node_botdispatch -->|"dispatches messages"| node_handler
node_handler -->|"records interactions"| node_analytics
node_handler -->|"reads and writes"| node_dbutil
node_handler -->|"processes downloads"| node_scraper
node_scraper -.->|"requests media"| node_mediaapi
node_handler -->|"sends replies"| node_whatsapp
node_admin -->|"manages service"| node_adminroutes
node_adminroutes -->|"checks token"| node_authmw
node_adminroutes -->|"manages records"| node_dbutil
node_adminroutes -->|"restarts sessions"| node_wa
node_adminroutes -->|"sends broadcasts"| node_whatsapp
node_dbutil -->|"reads and writes"| node_db
node_authroutes -->|"uses trial limits"| node_config
node_handler -->|"uses bot settings"| node_config

click node_server "https://github.com/onlybot12/project-botweb/blob/main/server.js"
click node_authroutes "https://github.com/onlybot12/project-botweb/blob/main/routes/auth.js"
click node_authmw "https://github.com/onlybot12/project-botweb/blob/main/middleware/auth.js"
click node_dashboard "https://github.com/onlybot12/project-botweb/tree/main/views/dashboard"
click node_adminui "https://github.com/onlybot12/project-botweb/tree/main/views/admin"
click node_connroutes "https://github.com/onlybot12/project-botweb/blob/main/routes/connection.js"
click node_connroutes2 "https://github.com/onlybot12/project-botweb/blob/main/routes/connection2.js"
click node_wa "https://github.com/onlybot12/project-botweb/blob/main/utils/whatsapp.js"
click node_botdispatch "https://github.com/onlybot12/project-botweb/blob/main/utils/whatsapp.js"
click node_handler "https://github.com/onlybot12/project-botweb/blob/main/utils/botHandler.js"
click node_scraper "https://github.com/onlybot12/project-botweb/blob/main/lib/scraper.js"
click node_analytics "https://github.com/onlybot12/project-botweb/blob/main/utils/botAnalytics.js"
click node_adminroutes "https://github.com/onlybot12/project-botweb/blob/main/routes/admin.js"
click node_dbutil "https://github.com/onlybot12/project-botweb/blob/main/utils/database.js"
click node_db "https://github.com/onlybot12/project-botweb/blob/main/database/database.json"
click node_sessions "https://github.com/onlybot12/project-botweb/tree/main/database"
click node_config "https://github.com/onlybot12/project-botweb/blob/main/config.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_server,node_authroutes,node_authmw,node_dashboard,node_adminui,node_user toneBlue
class node_connroutes,node_connroutes2,node_wa toneAmber
class node_botdispatch,node_handler,node_scraper,node_analytics,node_mediaapi toneMint
class node_adminroutes,node_dbutil,node_db,node_sessions,node_config toneRose
class node_admin,node_whatsapp toneIndigo
```

## Components

### Web and accounts

- [HTTP server](https://github.com/onlybot12/project-botweb/blob/main/server.js): `server.js`
- [Auth routes](https://github.com/onlybot12/project-botweb/blob/main/routes/auth.js): `routes/auth.js`
- [Token auth](https://github.com/onlybot12/project-botweb/blob/main/middleware/auth.js): `middleware/auth.js`
- [Dashboard UI](https://github.com/onlybot12/project-botweb/tree/main/views/dashboard): `views/dashboard`
- [Admin UI](https://github.com/onlybot12/project-botweb/tree/main/views/admin): `views/admin`

### WhatsApp connections

- [Connection routes](https://github.com/onlybot12/project-botweb/blob/main/routes/connection.js): `routes/connection.js`
- [Connection routes 2](https://github.com/onlybot12/project-botweb/blob/main/routes/connection2.js): `routes/connection2.js`
- [WhatsApp sessions](https://github.com/onlybot12/project-botweb/blob/main/utils/whatsapp.js): `utils/whatsapp.js`

### Bot runtime

- [Message dispatch](https://github.com/onlybot12/project-botweb/blob/main/utils/whatsapp.js): `utils/whatsapp.js`
- [Command handler](https://github.com/onlybot12/project-botweb/blob/main/utils/botHandler.js): `utils/botHandler.js`
- [Media downloader](https://github.com/onlybot12/project-botweb/blob/main/lib/scraper.js): `lib/scraper.js`
- [Bot analytics](https://github.com/onlybot12/project-botweb/blob/main/utils/botAnalytics.js): `utils/botAnalytics.js`

### Administration and state

- [Admin routes](https://github.com/onlybot12/project-botweb/blob/main/routes/admin.js): `routes/admin.js`
- [Database access](https://github.com/onlybot12/project-botweb/blob/main/utils/database.js): `utils/database.js`
- [JSON database](https://github.com/onlybot12/project-botweb/blob/main/database/database.json): `database/database.json`
- [Session files](https://github.com/onlybot12/project-botweb/tree/main/database): `database`
- [Bot and plans config](https://github.com/onlybot12/project-botweb/blob/main/config.js): `config.js`

### Other components

- **User**
- **Admin**
- **WhatsApp service**
- **Downloader API**

## Connections

- User → HTTP server: requests pages
- HTTP server → Dashboard UI: renders dashboard
- HTTP server → Admin UI: renders admin
- HTTP server → Auth routes: routes auth
- Auth routes → Database access: reads and writes
- Auth routes → Token auth: protects profile
- Token auth → Database access: loads user
- User → Connection routes: manages connections
- User → Connection routes 2: manages connections
- Connection routes → Token auth: checks token
- Connection routes 2 → Token auth: checks token
- Connection routes → WhatsApp sessions: starts pairing
- Connection routes 2 → WhatsApp sessions: starts or restarts
- WhatsApp sessions → WhatsApp service: opens sessions
- WhatsApp sessions → Session files: reads and saves
- WhatsApp sessions → Database access: updates status
- WhatsApp service → Message dispatch: delivers events
- Message dispatch → Command handler: dispatches messages
- Command handler → Bot analytics: records interactions
- Command handler → Database access: reads and writes
- Command handler → Media downloader: processes downloads
- Media downloader → Downloader API: requests media
- Command handler → WhatsApp service: sends replies
- Admin → Admin routes: manages service
- Admin routes → Token auth: checks token
- Admin routes → Database access: manages records
- Admin routes → WhatsApp sessions: restarts sessions
- Admin routes → WhatsApp service: sends broadcasts
- Database access → JSON database: reads and writes
- Auth routes → Bot and plans config: uses trial limits
- Command handler → Bot and plans config: uses bot settings