Project Layout

This page is the canonical source of truth for repository and module layout in this project.

Repository Root

  • AGENTS.md
  • mkdocs.yml: canonical MkDocs configuration for project docs
  • docs/: canonical project-local documentation
  • script/: root orchestration scripts for local start, stop, deploy, and env materialization
  • .sops.yaml: SOPS creation rules for encrypted env files
  • secrets/: encrypted source of truth for module env files
  • whatsapp-adapter-waha/
  • whatsapp-adapter-api/
  • whatsapp-adapter-app/
  • whatsapp-adapter-docs/

Module Ownership

  • whatsapp-adapter-waha/ owns the vendor WAHA runtime, session storage, media storage, and recovery scripts.
  • whatsapp-adapter-api/ owns the stable external REST contract, raw OpenAPI files under whatsapp-adapter-api/openapi/, group registry, and WAHA integration logic.
  • whatsapp-adapter-app/ owns the operator-facing web experience, SimpleAuth integration, and operator workflows.
  • whatsapp-adapter-docs/ owns the deployable docs container packaging the canonical root docs/ source.
  • Cross-module orchestration belongs to root script/.

Dependency Direction

  • External clients call whatsapp-adapter-api.
  • Operators use whatsapp-adapter-app.
  • whatsapp-adapter-app calls whatsapp-adapter-api.
  • whatsapp-adapter-api calls whatsapp-adapter-waha.
  • whatsapp-adapter-waha stays behind the internal Docker network and is not the public contract.
  • whatsapp-adapter-docs publishes the canonical root docs and does not own documentation content.

Service Module Layout

Each service module contains:

  • Dockerfile
  • docker-compose.yml
  • .env.example
  • .env.local: materialized local runtime artifact
  • .env.server: materialized deploy runtime artifact
  • README.md
  • data/
  • logs/
  • conf/
  • scripts/<module>-start.sh
  • scripts/<module>-stop.sh
  • scripts/<module>-deploy.sh

Notes

  • Keep project docs in root docs/.
  • Keep encrypted module env files in secrets/local/<module>.env and secrets/prod/<module>.env.
  • Use the full project-prefixed module name for each deployable container directory.
  • Keep runtime state inside the owning module.
  • Update this page when module ownership or dependency direction changes.