# evolution-foundation/evolution-go architecture

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

- Interactive diagram: https://gitdiagram.com/evolution-foundation/evolution-go
- Repository: https://github.com/evolution-foundation/evolution-go

## Overview

Evolution Go is a Go-based WhatsApp API. Its principal workflow is an API client request entering authenticated HTTP routes, reaching a domain handler and service, and then operating through a WhatsApp instance; responses return through the API. The repository also documents real-time event transports, media storage, optional message persistence, and license activation. The map uses indexed imports and documented capabilities where source excerpts do not expose wiring; dashed links mark relationships that are documented but not verified in the sampled code.

Main entry points: [`pkg/routes/routes.go`](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/routes/routes.go) (HTTP routes), [`pkg/whatsmeow/service/whatsmeow.go`](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/whatsmeow/service/whatsmeow.go) (WhatsApp client runtime), [`pkg/events/interfaces/producer.go`](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/interfaces/producer.go) (Event producers), [`cmd/evolution-go/main.go`](https://github.com/evolution-foundation/evolution-go/blob/main/cmd/evolution-go/main.go) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_routes["HTTP routes<br/>[routes.go]"]
  node_auth["API auth<br/>[auth_middleware.go]"]
  node_instance_api["Instance API"]
  node_send_api["Send API<br/>[send_handler.go]"]
  node_message_api["Message API<br/>[message_handler.go]"]
  node_group_api["Group API<br/>[group_handler.go]"]
  node_user_api["User API<br/>[user_handler.go]"]
  node_chat_api["Chat API<br/>[chat_handler.go]"]
  node_community_api["Community API"]
  node_poll_api["Poll API<br/>[poll_handler.go]"]
end

subgraph group_domain["Messaging domains"]
  node_instance_svc["Instance lifecycle"]
  node_send_svc["Message sending<br/>[send_service.go]"]
  node_message_svc["Message operations<br/>[message_service.go]"]
  node_group_svc["Group operations<br/>[group_service.go]"]
  node_user_svc["User operations<br/>[user_service.go]"]
  node_chat_svc["Chat operations<br/>[chat_service.go]"]
  node_community_svc["Community operations"]
  node_poll_svc["Poll tracking<br/>[poll_service.go]"]
end

subgraph group_whatsapp["WhatsApp runtime"]
  node_wa["WhatsApp client runtime<br/>[whatsmeow.go]"]
end

subgraph group_persistence["Persistence and media"]
  node_postgres[("PostgreSQL")]
  node_instance_repo["Instance repository"]
  node_message_repo["Message repository"]
  node_media_store["MinIO media<br/>[media_storage.go]"]
end

subgraph group_operations["Events and operations"]
  node_event_bus["Event producers<br/>[producer.go]"]
  node_rabbit["RabbitMQ producer"]
  node_nats["NATS producer<br/>[nats_producer.go]"]
  node_webhook["Webhook producer"]
  node_websocket["WebSocket producer"]
  node_license["License management<br/>[c0.go]"]
  node_app["Application startup<br/>[main.go]"]
end

node_client(("API client"))

node_client -->|"sends request"| node_routes
node_routes -->|"applies auth"| node_auth
node_routes -->|"routes requests"| node_instance_api
node_routes -->|"routes requests"| node_send_api
node_routes -.->|"routes requests"| node_message_api
node_routes -.->|"routes requests"| node_group_api
node_routes -.->|"routes requests"| node_user_api
node_routes -.->|"routes requests"| node_chat_api
node_routes -.->|"routes requests"| node_community_api
node_routes -.->|"routes requests"| node_poll_api
node_instance_api -->|"calls"| node_instance_svc
node_send_api -->|"calls"| node_send_svc
node_message_api -->|"calls"| node_message_svc
node_group_api -->|"calls"| node_group_svc
node_user_api -->|"calls"| node_user_svc
node_chat_api -->|"calls"| node_chat_svc
node_community_api -->|"calls"| node_community_svc
node_poll_api -->|"calls"| node_poll_svc
node_instance_svc -->|"starts clients"| node_wa
node_send_svc -->|"uses WhatsApp"| node_wa
node_message_svc -->|"uses WhatsApp"| node_wa
node_group_svc -->|"uses WhatsApp"| node_wa
node_user_svc -->|"uses WhatsApp"| node_wa
node_chat_svc -->|"uses WhatsApp"| node_wa
node_community_svc -->|"uses WhatsApp"| node_wa
node_instance_svc -->|"reads and writes"| node_instance_repo
node_instance_repo -.->|"persists instances"| node_postgres
node_message_svc -->|"uses repository"| node_message_repo
node_message_repo -.->|"persists messages"| node_postgres
node_poll_svc -->|"stores votes"| node_postgres
node_wa -.->|"uses media storage"| node_media_store
node_app -.->|"serves API"| node_routes
node_app -.->|"initializes runtime"| node_wa
node_app -->|"starts heartbeat"| node_license
node_wa -.->|"emits events"| node_event_bus
node_event_bus -.->|"implements producer"| node_rabbit
node_event_bus -.->|"implements producer"| node_nats
node_event_bus -->|"implements producer"| node_webhook
node_event_bus -.->|"implements producer"| node_websocket

click node_routes "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/routes/routes.go"
click node_auth "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/middleware/auth_middleware.go"
click node_instance_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/handler/instance_handler.go"
click node_send_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/sendMessage/handler/send_handler.go"
click node_message_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/handler/message_handler.go"
click node_group_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/group/handler/group_handler.go"
click node_user_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/user/handler/user_handler.go"
click node_chat_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/chat/handler/chat_handler.go"
click node_community_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/community/handler/community_handler.go"
click node_poll_api "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/poll/handler/poll_handler.go"
click node_instance_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/service/instance_service.go"
click node_send_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/sendMessage/service/send_service.go"
click node_message_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/service/message_service.go"
click node_group_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/group/service/group_service.go"
click node_user_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/user/service/user_service.go"
click node_chat_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/chat/service/chat_service.go"
click node_community_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/community/service/community_service.go"
click node_poll_svc "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/poll/service/poll_service.go"
click node_wa "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/whatsmeow/service/whatsmeow.go"
click node_instance_repo "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/repository/instance_repository.go"
click node_message_repo "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/repository/message_repository.go"
click node_media_store "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/storage/minio/media_storage.go"
click node_event_bus "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/interfaces/producer.go"
click node_rabbit "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/rabbitmq/rabbitmq_producer.go"
click node_nats "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/nats/nats_producer.go"
click node_webhook "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/webhook/webhook_producer.go"
click node_websocket "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/websocket/websocket_producer.go"
click node_license "https://github.com/evolution-foundation/evolution-go/blob/main/pkg/core/c0.go"
click node_app "https://github.com/evolution-foundation/evolution-go/blob/main/cmd/evolution-go/main.go"

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_routes,node_auth,node_instance_api,node_send_api,node_message_api,node_group_api,node_user_api,node_chat_api,node_community_api,node_poll_api,node_client toneBlue
class node_instance_svc,node_send_svc,node_message_svc,node_group_svc,node_user_svc,node_chat_svc,node_community_svc,node_poll_svc toneAmber
class node_wa toneMint
class node_postgres,node_instance_repo,node_message_repo,node_media_store toneRose
class node_event_bus,node_rabbit,node_nats,node_webhook,node_websocket,node_license,node_app toneIndigo
```

## Components

### HTTP API

- [HTTP routes](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/routes/routes.go): `pkg/routes/routes.go`
- [API auth](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/middleware/auth_middleware.go): `pkg/middleware/auth_middleware.go`
- [Instance API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/handler/instance_handler.go): `pkg/instance/handler/instance_handler.go`
- [Send API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/sendMessage/handler/send_handler.go): `pkg/sendMessage/handler/send_handler.go`
- [Message API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/handler/message_handler.go): `pkg/message/handler/message_handler.go`
- [Group API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/group/handler/group_handler.go): `pkg/group/handler/group_handler.go`
- [User API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/user/handler/user_handler.go): `pkg/user/handler/user_handler.go`
- [Chat API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/chat/handler/chat_handler.go): `pkg/chat/handler/chat_handler.go`
- [Community API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/community/handler/community_handler.go): `pkg/community/handler/community_handler.go`
- [Poll API](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/poll/handler/poll_handler.go): `pkg/poll/handler/poll_handler.go`

### Messaging domains

- [Instance lifecycle](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/service/instance_service.go): `pkg/instance/service/instance_service.go`
- [Message sending](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/sendMessage/service/send_service.go): `pkg/sendMessage/service/send_service.go`
- [Message operations](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/service/message_service.go): `pkg/message/service/message_service.go`
- [Group operations](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/group/service/group_service.go): `pkg/group/service/group_service.go`
- [User operations](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/user/service/user_service.go): `pkg/user/service/user_service.go`
- [Chat operations](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/chat/service/chat_service.go): `pkg/chat/service/chat_service.go`
- [Community operations](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/community/service/community_service.go): `pkg/community/service/community_service.go`
- [Poll tracking](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/poll/service/poll_service.go): `pkg/poll/service/poll_service.go`

### WhatsApp runtime

- [WhatsApp client runtime](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/whatsmeow/service/whatsmeow.go): `pkg/whatsmeow/service/whatsmeow.go`

### Persistence and media

- **PostgreSQL**
- [Instance repository](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/instance/repository/instance_repository.go): `pkg/instance/repository/instance_repository.go`
- [Message repository](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/message/repository/message_repository.go): `pkg/message/repository/message_repository.go`
- [MinIO media](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/storage/minio/media_storage.go): `pkg/storage/minio/media_storage.go`

### Events and operations

- [Event producers](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/interfaces/producer.go): `pkg/events/interfaces/producer.go`
- [RabbitMQ producer](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/rabbitmq/rabbitmq_producer.go): `pkg/events/rabbitmq/rabbitmq_producer.go`
- [NATS producer](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/nats/nats_producer.go): `pkg/events/nats/nats_producer.go`
- [Webhook producer](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/webhook/webhook_producer.go): `pkg/events/webhook/webhook_producer.go`
- [WebSocket producer](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/events/websocket/websocket_producer.go): `pkg/events/websocket/websocket_producer.go`
- [License management](https://github.com/evolution-foundation/evolution-go/blob/main/pkg/core/c0.go): `pkg/core/c0.go`
- [Application startup](https://github.com/evolution-foundation/evolution-go/blob/main/cmd/evolution-go/main.go): `cmd/evolution-go/main.go`

### Other components

- **API client**

## Connections

- API client → HTTP routes: sends request (evidence: `README.md`)
- HTTP routes → API auth: applies auth (evidence: `pkg/routes/routes.go`)
- HTTP routes → Instance API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Send API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Message API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Group API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → User API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Chat API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Community API: routes requests (evidence: `pkg/routes/routes.go`)
- HTTP routes → Poll API: routes requests (evidence: `pkg/routes/routes.go`)
- Instance API → Instance lifecycle: calls (evidence: `pkg/instance/handler/instance_handler.go`)
- Send API → Message sending: calls (evidence: `pkg/sendMessage/handler/send_handler.go`)
- Message API → Message operations: calls (evidence: `pkg/message/handler/message_handler.go`)
- Group API → Group operations: calls (evidence: `pkg/group/handler/group_handler.go`)
- User API → User operations: calls (evidence: `pkg/user/handler/user_handler.go`)
- Chat API → Chat operations: calls (evidence: `pkg/chat/handler/chat_handler.go`)
- Community API → Community operations: calls (evidence: `pkg/community/handler/community_handler.go`)
- Poll API → Poll tracking: calls (evidence: `pkg/poll/handler/poll_handler.go`)
- Instance lifecycle → WhatsApp client runtime: starts clients (evidence: `pkg/instance/service/instance_service.go`)
- Message sending → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/sendMessage/service/send_service.go`)
- Message operations → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/message/service/message_service.go`)
- Group operations → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/group/service/group_service.go`)
- User operations → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/user/service/user_service.go`)
- Chat operations → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/chat/service/chat_service.go`)
- Community operations → WhatsApp client runtime: uses WhatsApp (evidence: `pkg/community/service/community_service.go`)
- Instance lifecycle → Instance repository: reads and writes (evidence: `pkg/instance/service/instance_service.go`)
- Instance repository → PostgreSQL: persists instances (evidence: `README.md`)
- Message operations → Message repository: uses repository (evidence: `pkg/message/service/message_service.go`)
- Message repository → PostgreSQL: persists messages (evidence: `README.md`)
- Poll tracking → PostgreSQL: stores votes (evidence: `pkg/poll/service/poll_service.go`)
- WhatsApp client runtime → MinIO media: uses media storage
- Application startup → HTTP routes: serves API (evidence: `cmd/evolution-go/main.go`)
- Application startup → WhatsApp client runtime: initializes runtime (evidence: `cmd/evolution-go/main.go`)
- Application startup → License management: starts heartbeat (evidence: `cmd/evolution-go/main.go`)
- WhatsApp client runtime → Event producers: emits events (evidence: `pkg/whatsmeow/service/whatsmeow.go`)
- Event producers → RabbitMQ producer: implements producer (evidence: `pkg/events/rabbitmq/rabbitmq_producer.go`)
- Event producers → NATS producer: implements producer
- Event producers → Webhook producer: implements producer (evidence: `pkg/events/webhook/webhook_producer.go`)
- Event producers → WebSocket producer: implements producer
