Architecture Guidelines

This document records project-level defaults and recommendations.

Module Boundaries

  • Treat whatsapp-adapter-waha as a vendor integration runtime, not as the public API contract.
  • Put all project-specific validation, IDs, and payload shaping into whatsapp-adapter-api.
  • Keep whatsapp-adapter-app thin and make it call whatsapp-adapter-api, not whatsapp-adapter-waha.
  • Keep canonical docs in root docs/ and use whatsapp-adapter-docs only as a packaging/runtime module.

Auth

  • whatsapp-adapter-app uses SimpleAuth.
  • whatsapp-adapter-api uses bearer-token authorization for machine clients by default.

Storage

  • Start with CSV for the local group registry in whatsapp-adapter-api/data/groups.csv.
  • Move to PostgreSQL when concurrent writers, relations, or audit requirements become important.

WAHA Integration

  • Prefer WAHA groups and chats endpoints through a dedicated client wrapper in whatsapp-adapter-api.
  • Keep WAHA-specific response details at the edge and return a project-owned JSON shape from whatsapp-adapter-api.

Exceptions

  • Record important deviations in ADRs.