add-module

Before starting: git fetch origin && gh pr list --state open && git log origin/main --oneline -3 — if another agent has an open PR touching the same files you need, wait for it to merge or branch off it instead of main.

Help the user add a backend module to an existing Mozaiks application.

A module is deterministic backend logic: CRUD actions, domain data, business rules. It runs without AI. For AI-driven behavior, use a workflow instead. Modules support workflows — they provide the action surface that AI agents call.

---

What a Module Is

app/modules/{name}/
├── module.yaml              ← required: identity, permissions, actions; optional: capabilities[]
├── contracts/               ← optional companion manifests
│   ├── events.yaml          ← domain events this module may publish
│   ├── reactions.yaml       ← event reactions owned by this module
│   ├── notifications.yaml   ← notification rules derived from events
│   ├── settings.yaml        ← user/app settings schema
│   ├── admin.yaml           ← admin panels (omit if none)
│   └── profile.yaml         ← optional user profile page panels
├── runtime_extensions.yaml  ← optional: api_router / startup_service
└── backend/
    ├── __init__.py
    ├── handler.py        ← required — thin dispatch, one method per action
    ├── service.py        ← recommended — all business logic and event emission
    ├── repo.py           ← recommended — MongoDB access, no logic
    ├── policy.py         ← recommended — multi-tenancy query scoping
    ├── schemas.py        ← recommended — typed shapes + pure helpers
    └── {helper_files}.py ← optional — declared, justified, module-local support

Only module.yaml and backend/handler.py are required. Add companion manifests under contracts/ only when the module needs them.

Use contracts/reactions.yaml as the canonical event-reaction contract. The runtime rejects contracts/subscriptions.yaml; module changes must author contracts/reactions.yaml.

For SaaS apps: set actions[].entitlement_gate to a capability_id string on user-facing actions that require an active plan grant. ModuleExecutor checks EntitlementPort before dispatch and returns ENTITLEMENT_REQUIRED on denial. Non-SaaS apps use NoOpEntitlementAdapter — no configuration needed. Never set entitlement_gate on admin_internal actions.

Event/reaction contract summary:

• contracts/events.yaml declares the events this module may emit. module.yaml.actions[].emits must reference event types declared there.
• contracts/reactions.yaml uses schema_version: mozaiks.reactions.v1, root key reactions, event_type, and nested target.kind.
• Reaction targets use target.handler_method, target.capability_id, or target.notification_id depending on target.kind.
• contracts/notifications.yaml declares notification rules derived from events and is separate from reaction routing.

The runtime auto-discovers and registers all modules at startup. Module routes are auto-mounted at /api/modules/{name}/{action_id}. Pages should call those routes without query strings. Put list limits in page_size and filters or selected-row values in action payloads, form state, or the module action input schema.

Modules that need persistent app chrome access should expose a real page route and put navigation intent on that page. For example, a communications module that owns /messages should give the Messages page navigation.scope: global when it is a primary destination, or navigation.scope: profile when it is account-adjacent. Use app/config/shell.json -> shortcuts for built-in profile, auth, notification, and footer chrome rather than hardcoding menu entries. The page also owns chrome intent through shell_mode: use conversation for DM/chat/thread pages so the mobile bottom bar and footer do not compete with the composer, and workspace for inbox, queue, profile, or management surfaces.

Module runtime output must be production-honest. Do not return sample, demo, mock, fake, placeholder, random, or hardcoded KPI data from module actions. Summary/stat/metric/count actions must query repo/MongoDB state or return honest empty values (0, [], null). Trend/change fields require a real historical comparison or metrics snapshot; otherwise omit them or return null.