Skip to main content
Status: PROPOSED (requires Daniel’s line-by-line approval before touching root CLAUDE.md) Date: 2026-08-15 · References: DEC-C3, DEC-C4, DEC-E1..E8, ADR-19

​
Rationale

The Engage/CRM modules introduce two infrastructure concerns the current six port categories do not cover: job queues and notification channels. Per the constitution, ports exist only for named categories; therefore the list must be amended before any agent may define these interfaces.

​
Change 1 — Add two port categories (edit the “Ports” section of root CLAUDE.md)

Add to the closed list of allowed port categories:
  1. QueuePort — asynchronous job publication.
    • Contract (packages/core): publish(queue, payload, opts), schedule(queue, payload, runAt).
    • Consumers MUST follow /docs/standards/jobs.md (idempotency via core.processed_jobs, retry policy, dead letters).
  2. NotificationChannelPort — outbound delivery over one channel.
    • Contract (packages/core): send(recipient, renderedContent, opts) -> ProviderResult.
    • One adapter per channel (ResendEmailAdapter, FcmPushAdapter, InAppAdapter, WebhookAdapter; SmsAdapter arrives F1b behind its ADR).
    • Channel resolution is NEVER the adapter’s job: adapters deliver; /docs/standards/notifications.md governs routing.

​
Change 2 — New rule: per-module adapter binding (append to rules section as R21)

R21. Hexagonal architecture applies to the entire project WITHOUT exception. Adapter bindings are declared exclusively in each module’s composition root (makeDeps(ctx)); domain and application code MUST depend on ports only. Different modules MAY bind different adapters for the same port (e.g., messaging on QStash while loyalty stays on Vercel Queues) with rationale recorded in the module spec. Introducing a NEW vendor/dependency for any adapter still requires an ADR before first import (existing rule unchanged). Default binding for all modules at F1: Vercel Queues (QueuePort); Resend/FCM/in-app/webhook (NotificationChannelPort).

​
Change 3 — Register new/updated standards (edit the standards index in root CLAUDE.md)

  • ADD: /docs/standards/notifications.md (cascading channel resolution, priorities, traceability).
  • UPDATED (major): data.md (parametric tables, money, partitioning, data classification), events.md (correlation), jobs.md (queues/workers), api.md (module-scoped paths, permission naming), security.md (machine roles, national_id handling).

​
Non-changes (explicit)

  • The six existing port categories are unchanged.
  • R1–R20 are unchanged.
  • The closed-stack rule is unchanged; this amendment adds NO dependencies.