# hisptz/whatsapp-server architecture

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

- Interactive diagram: https://gitdiagram.com/hisptz/whatsapp-server
- Repository: https://github.com/hisptz/whatsapp-server

## Overview

1. **What this repository is**
   - This is a Node.js/TypeScript service that exposes a WhatsApp API over HTTP using the **WPPConnect** library.
   - The architecture is centered around a small Express-style server layer, with the WhatsApp integration isolated in a service module.

2. **Process boundary**
   - The main runtime is a single server process launched from `src/index.ts`.
   - It listens on the configured `PORT` and serves API endpoints that act as a thin wrapper over WhatsApp functionality.

3. **HTTP/API layer**
   - `src/routes/index.ts` is the entry point for request routing.
   - This layer is responsible for exposing the API surface and delegating work downward rather than holding business logic itself.

4. **WhatsApp integration layer**
   - `src/services/whatsapp.ts` is the core integration boundary with WPPConnect.
   - This is where WhatsApp-specific operations are likely implemented and abstracted away from the routes.
   - `src/services/whatsapp.test.ts` indicates this service has direct unit coverage, suggesting it is the main behavior-bearing module.

5. **Types and contracts**
   - `src/interfaces/` contains shared TypeScript interfaces used across the server.
   - `src/schema/` likely contains request/response schemas or validation models that define the API contract.
   - These two folders separate static contracts from executable logic.

6. **Configuration**
   - Environment handling is centralized in `src/utils/env.ts`.
   - The only documented required runtime configuration is `PORT`, read from `.env` based on `.env.example`.
   - This suggests the app is mostly self-contained and does not depend on external infrastructure beyond the WhatsApp connection.

7. **Startup and wiring**
   - `src/index.ts` is the composition root: it likely loads env config, creates the server, and mounts routes/services.
   - For an architecture diagram, this should be the top node connecting configuration, HTTP server, and the WhatsApp service.

8. **Build and packaging**
   - The project is TypeScript-based and includes `tsconfig.json`, `webpack.config.ts`, and `postbuild.sh`, so it likely compiles/bundles before production startup.
   - `Dockerfile` shows it is intended to run as a containerized service in deployment.

9. **Development workflow**
   - `nodemon.json` indicates a watch-based local development mode.
   - `jest.config.ts` and the service test file show automated testing is part of the workflow, with tests focused on the WhatsApp service boundary.

10. **External dependency boundary**
    - The main external dependency is **WPPConnect**, which mediates the WhatsApp connection/session behavior.
    - There is no evidence in the tree of a database, message broker, cache, or other backend service, so the system appears to be a stateless API wrapper around WhatsApp connectivity.

11. **Recommended diagram shape**
    - Show four main blocks: **Configuration**, **HTTP Server/Routes**, **WhatsApp Service (WPPConnect integration)**, and **External WhatsApp network**.
    - Add **Types/Schemas** as supporting artifacts around the server/service boundary, and **Tests/Build/Docker** as non-runtime support components.

12. **Key architectural takeaway**
    - The repository is intentionally simple: a single-service API layer with clear separation between transport, integration, and shared contracts.
    - The most important boundary is between the HTTP routes and the WhatsApp service, with WPPConnect as the external integration point.

Main entry points: [`src/services/whatsapp.ts`](https://github.com/hisptz/whatsapp-server/blob/develop/src/services/whatsapp.ts) (WhatsApp service), [`src/index.ts`](https://github.com/hisptz/whatsapp-server/blob/develop/src/index.ts) (Server entry), [`src/routes/index.ts`](https://github.com/hisptz/whatsapp-server/blob/develop/src/routes/index.ts) (API routes), [`package.json`](https://github.com/hisptz/whatsapp-server/blob/develop/package.json) (Package config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_index["Server entry<br/>composition root<br/>[index.ts]"]
  node_src_routes_index["API routes<br/>http router<br/>[index.ts]"]
  node_src_services_whatsapp["WhatsApp service<br/>integration service<br/>[whatsapp.ts]"]
  node_src_utils_env["Env config<br/>config loader<br/>[env.ts]"]
end

subgraph group_contracts["Contracts"]
  node_src_interfaces_index["Interfaces<br/>type contracts<br/>[index.ts]"]
  node_src_schema_index["Schemas<br/>request/response schema<br/>[index.ts]"]
end

subgraph group_support["Support"]
  node_src_services_whatsapp_test["Service tests<br/>unit test<br/>[whatsapp.test.ts]"]
  node_package_json["Package config<br/>npm manifest<br/>[package.json]"]
  node_tsconfig_json["TS config<br/>build config<br/>[tsconfig.json]"]
  node_webpack_config["Webpack build<br/>bundle config<br/>[webpack.config.ts]"]
  node_jest_config["Jest config<br/>test config<br/>[jest.config.ts]"]
  node_nodemon_json["Dev watch<br/>dev config<br/>[nodemon.json]"]
  node_dockerfile["Container build<br/>deployment config"]
  node_postbuild_sh["Post build<br/>build script<br/>[postbuild.sh]"]
  node_env_example["Env example<br/>env template<br/>[.env.example]"]
end

subgraph group_external["External"]
  node_wppconnect{{"WPPConnect<br/>external library"}}
  node_whatsapp_network(("WhatsApp network<br/>external system"))
end

node_src_index -->|"loads config"| node_src_utils_env
node_src_index -->|"mounts routes"| node_src_routes_index
node_src_index -->|"starts service"| node_src_services_whatsapp
node_src_routes_index -->|"delegates"| node_src_services_whatsapp
node_src_routes_index -->|"validates with"| node_src_schema_index
node_src_routes_index -->|"types against"| node_src_interfaces_index
node_src_services_whatsapp -->|"uses types"| node_src_interfaces_index
node_src_services_whatsapp -->|"applies schema"| node_src_schema_index
node_src_services_whatsapp -->|"wraps"| node_wppconnect
node_wppconnect -->|"connects to"| node_whatsapp_network
node_src_services_whatsapp_test -.->|"covers"| node_src_services_whatsapp
node_package_json -->|"runs"| node_src_index
node_package_json -->|"tests"| node_src_services_whatsapp_test
node_tsconfig_json -->|"compiles"| node_src_index
node_webpack_config -->|"bundles for"| node_package_json
node_jest_config -->|"configures"| node_src_services_whatsapp_test
node_nodemon_json -->|"watches"| node_src_index
node_dockerfile -->|"packages"| node_package_json
node_postbuild_sh -->|"postprocesses"| node_webpack_config
node_env_example -.->|"documents"| node_src_utils_env

click node_src_index "https://github.com/hisptz/whatsapp-server/blob/develop/src/index.ts"
click node_src_routes_index "https://github.com/hisptz/whatsapp-server/blob/develop/src/routes/index.ts"
click node_src_services_whatsapp "https://github.com/hisptz/whatsapp-server/blob/develop/src/services/whatsapp.ts"
click node_src_utils_env "https://github.com/hisptz/whatsapp-server/blob/develop/src/utils/env.ts"
click node_src_interfaces_index "https://github.com/hisptz/whatsapp-server/blob/develop/src/interfaces/index.ts"
click node_src_schema_index "https://github.com/hisptz/whatsapp-server/blob/develop/src/schema/index.ts"
click node_src_services_whatsapp_test "https://github.com/hisptz/whatsapp-server/blob/develop/src/services/whatsapp.test.ts"
click node_package_json "https://github.com/hisptz/whatsapp-server/blob/develop/package.json"
click node_tsconfig_json "https://github.com/hisptz/whatsapp-server/blob/develop/tsconfig.json"
click node_webpack_config "https://github.com/hisptz/whatsapp-server/blob/develop/webpack.config.ts"
click node_jest_config "https://github.com/hisptz/whatsapp-server/blob/develop/jest.config.ts"
click node_nodemon_json "https://github.com/hisptz/whatsapp-server/blob/develop/nodemon.json"
click node_dockerfile "https://github.com/hisptz/whatsapp-server/tree/develop/Dockerfile"
click node_postbuild_sh "https://github.com/hisptz/whatsapp-server/blob/develop/postbuild.sh"
click node_env_example "https://github.com/hisptz/whatsapp-server/blob/develop/.env.example"

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_src_index,node_src_routes_index,node_src_services_whatsapp,node_src_utils_env toneBlue
class node_src_interfaces_index,node_src_schema_index toneAmber
class node_src_services_whatsapp_test,node_package_json,node_tsconfig_json,node_webpack_config,node_jest_config,node_nodemon_json,node_dockerfile,node_postbuild_sh,node_env_example toneMint
class node_wppconnect,node_whatsapp_network toneRose
```

## Components

### Runtime

Server process and request flow

- [Server entry](https://github.com/hisptz/whatsapp-server/blob/develop/src/index.ts): composition root · Bootstraps the process, loads config, and wires routes to services · `src/index.ts`
- [API routes](https://github.com/hisptz/whatsapp-server/blob/develop/src/routes/index.ts): http router · Thin HTTP surface that delegates requests into the service layer · `src/routes/index.ts`
- [WhatsApp service](https://github.com/hisptz/whatsapp-server/blob/develop/src/services/whatsapp.ts): integration service · Core WPPConnect-backed business boundary for WhatsApp operations · `src/services/whatsapp.ts`
- [Env config](https://github.com/hisptz/whatsapp-server/blob/develop/src/utils/env.ts): config loader · Centralized environment access for runtime settings such as PORT · `src/utils/env.ts`

### Contracts

Shared types and API schemas

- [Interfaces](https://github.com/hisptz/whatsapp-server/blob/develop/src/interfaces/index.ts): type contracts · Shared TypeScript interfaces used across the server · `src/interfaces/index.ts`
- [Schemas](https://github.com/hisptz/whatsapp-server/blob/develop/src/schema/index.ts): request/response schema · Validation and API contract definitions for inputs and outputs · `src/schema/index.ts`

### Support

Testing, build, and deployment artifacts

- [Service tests](https://github.com/hisptz/whatsapp-server/blob/develop/src/services/whatsapp.test.ts): unit test · Direct coverage for the WhatsApp integration boundary · `src/services/whatsapp.test.ts`
- [Package config](https://github.com/hisptz/whatsapp-server/blob/develop/package.json): npm manifest · Dependency and script definition for the Node.js service · `package.json`
- [TS config](https://github.com/hisptz/whatsapp-server/blob/develop/tsconfig.json): build config · TypeScript compiler configuration · `tsconfig.json`
- [Webpack build](https://github.com/hisptz/whatsapp-server/blob/develop/webpack.config.ts): bundle config · Bundling configuration for production packaging · `webpack.config.ts`
- [Jest config](https://github.com/hisptz/whatsapp-server/blob/develop/jest.config.ts): test config · Test runner configuration · `jest.config.ts`
- [Dev watch](https://github.com/hisptz/whatsapp-server/blob/develop/nodemon.json): dev config · Local watch-and-restart configuration · `nodemon.json`
- [Container build](https://github.com/hisptz/whatsapp-server/tree/develop/Dockerfile): deployment config · Container image definition for deployment · `Dockerfile`
- [Post build](https://github.com/hisptz/whatsapp-server/blob/develop/postbuild.sh): build script · Post-compilation packaging step · `postbuild.sh`
- [Env example](https://github.com/hisptz/whatsapp-server/blob/develop/.env.example): env template · Example runtime configuration variables · `.env.example`

### External

Outside dependencies and network boundary

- **WPPConnect**: external library · WhatsApp integration library used by the service
- **WhatsApp network**: external system · External WhatsApp service and session endpoint boundary

## Connections

- Server entry → Env config: loads config · Startup reads runtime configuration before binding the server
- Server entry → API routes: mounts routes · Composition root wires the HTTP routing layer
- Server entry → WhatsApp service: starts service · Server initialization prepares the WhatsApp integration boundary
- API routes → WhatsApp service: delegates · Routes forward API calls into the WhatsApp service
- API routes → Schemas: validates with · HTTP layer relies on schemas for request and response contracts
- API routes → Interfaces: types against · Routes share common interfaces with downstream logic
- WhatsApp service → Interfaces: uses types · Service logic relies on shared TypeScript interfaces
- WhatsApp service → Schemas: applies schema · Service inputs and outputs align with the API contract models
- WhatsApp service → WPPConnect: wraps · WhatsApp behavior is implemented through WPPConnect
- WPPConnect → WhatsApp network: connects to · Library mediates the actual WhatsApp session and network interaction
- Service tests → WhatsApp service: covers · Unit tests exercise the main integration service
- Package config → Server entry: runs · Package scripts start the server entrypoint
- Package config → Service tests: tests · Package scripts execute the unit test suite
- TS config → Server entry: compiles · TypeScript configuration governs source compilation
- Webpack build → Package config: bundles for · Build pipeline uses package metadata and scripts
- Jest config → Service tests: configures · Jest settings drive the test run
- Dev watch → Server entry: watches · Development mode restarts the main process on changes
- Container build → Package config: packages · Container build uses the Node.js application scripts
- Post build → Webpack build: postprocesses · Post-build script runs after bundling
- Env example → Env config: documents · Example environment variables correspond to runtime config
