Architecture Guidelines

This page records project-level defaults and intended boundaries.

Current Shape

  • the project uses one long-running integration worker plus one docs packaging module
  • root docs/ and root mkdocs.yml are the canonical documentation source
  • module-local Docker assets and scripts own runtime behavior

Integration Boundaries

  • inbound source: WhatsApp Adapter HTTP API
  • outbound destination: Jira Cloud HTTP API
  • no project-owned public API is published today
  • the docs service is packaging and operator-facing, not a business application UI

Storage Default

  • the worker persists local state in CSV files
  • this is intentional because the current workload is single-writer and operationally simple
  • move to PostgreSQL only when concurrency, querying, or auditability outgrow flat files

Runtime Defaults

  • schedule-driven worker, not ad-hoc scripts in repo root
  • root scripts orchestrate modules; module scripts own compose behavior
  • secrets flow through SOPS-encrypted secrets/ files into materialized .env.local and .env.server