TorbatYar/docs/ai-framework/module-template.md

Module Template

How to implement a module (bounded feature set) inside an existing service.

Use when the domain clearly belongs to an already-owned database/service (e.g. CRM sales engine phases inside crm, Accounting sub-phases inside accounting).

If the capability must be reused across many business domains, create an independent service (service-template.md) instead.

Registry field template: templates/module-template.md.

When to Add a Module vs a Service

Choose module	Choose service
Same aggregate ownership	Shared platform capability
Same DB already owns the data	New sole DB required
Extends existing permission prefix	New permission prefix {service}.*
Phase slice of an active service	Cross-module reuse (Loyalty, Communication)

Design Steps

1. Confirm ownership in module-boundaries.md and module-registry.md.
2. Define Objective / Scope / Out of Scope with phase-template.md.
3. Add entities (entity-template.md), repositories, services, validators, permissions, events, APIs.
4. Additive Alembic migration in the owning service only.
5. Tests + docs + handover.
6. Update module registry “Current Phase” / version / events / permissions.

Module Checklist

Architecture

• Stays within service boundary
• No cross-DB access
• No foreign model imports
• Provider contracts only if calling platforms

Ownership

Field	Value
Parent service
Permission prefix	(usually parent’s {service}.*)
Database	Parent DB
Public surface	APIs + events listed in phase doc

Implementation Layers

Layer	Standard
Models	entity-template.md
Repositories	repository-template.md
Services	service-layer-template.md
APIs	api-template.md
Events	event-template.md
Tests	testing-template.md

Tenant Awareness

• tenant_id on business tables
• Filters on all queries
• Isolation tests

Documentation

• Phase doc
• Module registry entry updated
• Event catalog / API reference if public surface changed
• Progress / next-steps
• Handover

Non-Responsibilities

List what this module must not own (copy from parent boundaries and phase Out of Scope):

Related Documents

• Service Template
• Master Prompt
• Module Boundaries
• Module Registry
• templates/module-template.md