go-whatsapp-web-multidevice: Instructions file for Codex

PROJECT KNOWLEDGE BASE

Generated: 2026-06-06 Commit: 8c4ea8f Branch: fix/chatwoot-postgres

OVERVIEW

Go WhatsApp Web Multi-Device is a Go 1.26.0 WhatsApp Web API server. MCP is not a separate mode: the rest command serves it at /mcp (streamable HTTP) whenever config.McpEnabled is true. It uses whatsmeow sessions, Fiber, plain Vue 3 modules, and SQLite-backed chat/session storage by default.

STRUCTURE

go-whatsapp-web-multidevice/
|-- src/                         # Go module root; run Go commands here
|   |-- main.go                  # go:embed views, then cmd.Execute
|   |-- cmd/                     # Cobra root, rest (mounts MCP), global app wiring
|   |-- config/                  # Mutable package globals bound from flags/env
|   |-- domains/                 # Interfaces and DTOs; see child AGENTS
|   |-- usecase/                 # Business orchestration; see child AGENTS
|   |-- validations/             # ozzo-validation plus table tests
|   |-- ui/                      # REST, MCP, websocket adapters
|   |-- infrastructure/
|   |   |-- whatsapp/            # Device manager, events, presence pulse, JID utilities
|   |   |-- chatstorage/         # chat/message/device SQL repository
|   |   `-- chatwoot/            # Chatwoot REST sync and direct PG import
|   |       `-- pgimport/        # Direct Chatwoot Postgres importer; see child AGENTS
|   |-- views/                   # Embedded Vue 3 plain JS UI
|   |-- statics/                 # Runtime media, QR codes, send items
|   `-- storages/                # Runtime SQLite DBs and history dumps
|-- docs/                        # OpenAPI, webhook payload, Chatwoot docs
|-- docker/                      # Multi-stage Alpine image and entrypoint
|-- gallery/                     # Project logo assets
`-- .github/workflows/           # Docker publish, release, latest promotion

WHERE TO LOOK

Task	Location	Notes
Add message type	src/domains/send/, src/usecase/send.go, src/ui/rest/send.go	REST is primary; MCP support is selective.
Add quoted reply support	src/domains/send/, src/usecase/send.go, src/views/components/Send*.js	Optional reply_message_id; use device-scoped quote lookup.
Add REST endpoint	src/ui/rest/, src/usecase/, src/domains/	Handler parses request, usecase validates/executes, domain owns DTO/interface.
Add MCP tool	src/ui/mcp/	Register in Add*Tools; resolve a device with resolveDeviceContext (src/ui/mcp/device.go).
Handle WhatsApp event	src/infrastructure/whatsapp/event_*.go	Register the concrete event in event_handler.go.
Presence behavior	src/infrastructure/whatsapp/event_handler.go, presence_pulse.go, src/cmd/helpers.go	Connect-time and scheduled pulse presence.
Add chat storage method	src/domains/chatstorage/interfaces.go, sqlite_repository.go, chatstorage_wrapper.go	Update domain, repository, and wrapper together.
Add DB migration	src/infrastructure/chatstorage/sqlite_repository.go getMigrations()	Append only. Current list has 29 migrations.
Add UI component	src/views/components/, src/views/index.html	Plain JS modules, no .vue single-file components.
Device management	src/infrastructure/whatsapp/device_manager.go	Central registry and purge/load/create logic.
Chatwoot integration	src/infrastructure/chatwoot/ and src/ui/rest/chatwoot.go	REST sync, public webhook, optional direct Postgres import.
Direct Chatwoot import	src/infrastructure/chatwoot/pgimport/	Direct Chatwoot schema writes; see child AGENTS.
Chatwoot link/retry state	src/infrastructure/chatstorage/sqlite_repository.go, src/infrastructure/whatsapp/webhook_forward.go	Message links, read/delete sync, and persistent forward retries.
CLI flags / config	src/cmd/root.go, src/config/settings.go, src/.env.example	Flags and env mutate config package globals.
Shared helpers	src/pkg/utils/, src/pkg/error/, src/pkg/sqlite/	Utilities, aliased package errors, and CGO/purego SQLite driver selection.
Docker/release	docker/golang.Dockerfile, .github/workflows/*.yaml	Multi-arch Docker, tag/manual workflows, generated GoReleaser configs.