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, boundary-rules.md, and module-registry.md.
2. Run Enterprise Phase Discovery; publish Discovery Record before coding.
3. Define Objective / Scope / Out of Scope / Business Analysis with phase-template.md.
4. Domain model: aggregates, entities, DTOs.
5. Add entities (entity-template.md), repositories, specifications, policies, commands/queries, services, validators, permissions, events, APIs (incl. list page/filter/sort/search).
6. Additive Alembic migration in the owning service only; seeds/jobs/flags when required.
7. Tests + docs + handover with Definition of Done and Enterprise Completeness.
8. Update module registry “Current Phase” / version / events / permissions.
9. Do not stop at CRUD; do not pull future-phase features forward.

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
Specifications / Policies	service-layer-template.md
Commands / Queries / Services	service-layer-template.md
APIs / OpenAPI	api-template.md
Events	event-template.md
Tests	testing-template.md
Artifacts	mandatory-phase-artifacts.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
• Definition of Done
• Enterprise Phase Discovery
• Boundary Rules
• Module Boundaries
• Module Registry
• templates/module-template.md