How hisptz/whatsapp-server works
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: whatsapp.ts WhatsApp service · src/index.ts Server entry · routes/index.ts API routes · package.json Package config
Components 17
Runtime
Server process and request flow
- Server entry · Bootstraps the process, loads config, and wires routes to services
src/index.ts - API routes · Thin HTTP surface that delegates requests into the service layer
src/routes/index.ts - WhatsApp service · Core WPPConnect-backed business boundary for WhatsApp operations
src/services/whatsapp.ts - Env config · Centralized environment access for runtime settings such as PORT
src/utils/env.ts
Contracts
Shared types and API schemas
- Interfaces · Shared TypeScript interfaces used across the server
src/interfaces/index.ts - Schemas · Validation and API contract definitions for inputs and outputs
src/schema/index.ts
Support
Testing, build, and deployment artifacts
- Service tests · Direct coverage for the WhatsApp integration boundary
src/services/whatsapp.test.ts - Package config · Dependency and script definition for the Node.js service
package.json - TS config · TypeScript compiler configuration
tsconfig.json - Webpack build · Bundling configuration for production packaging
webpack.config.ts - Jest config · Test runner configuration
jest.config.ts - Dev watch · Local watch-and-restart configuration
nodemon.json - Container build · Container image definition for deployment
Dockerfile - Post build · Post-compilation packaging step
postbuild.sh - Env example · Example runtime configuration variables
.env.example
External
Outside dependencies and network boundary
- WPPConnect · WhatsApp integration library used by the service
- WhatsApp network · External WhatsApp service and session endpoint boundary
Connections 20
- 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