# 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](service-template.md)) instead.

Registry field template: [templates/module-template.md](../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](../architecture/module-boundaries.md), [boundary-rules.md](boundary-rules.md), and [module-registry.md](../module-registry.md).
2. Run [Enterprise Phase Discovery](enterprise-phase-discovery.md); publish Discovery Record before coding.
3. Define Objective / Scope / Out of Scope / Business Analysis with [phase-template.md](phase-template.md).
3. Domain model: aggregates, entities, DTOs.
4. Add entities ([entity-template.md](entity-template.md)), repositories, specifications, policies, commands/queries, services, validators, permissions, events, APIs (incl. list page/filter/sort/search).
5. Additive Alembic migration in the **owning** service only; seeds/jobs/flags when required.
6. Tests + docs + handover with Definition of Done and Enterprise Completeness.
7. Update module registry “Current Phase” / version / events / permissions.
8. 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](entity-template.md) |
| Repositories | [repository-template.md](repository-template.md) |
| Specifications / Policies | [service-layer-template.md](service-layer-template.md) |
| Commands / Queries / Services | [service-layer-template.md](service-layer-template.md) |
| APIs / OpenAPI | [api-template.md](api-template.md) |
| Events | [event-template.md](event-template.md) |
| Tests | [testing-template.md](testing-template.md) |
| Artifacts | [mandatory-phase-artifacts.md](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](service-template.md)
- [Master Prompt](master-prompt.md)
- [Definition of Done](definition-of-done.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Boundary Rules](boundary-rules.md)
- [Module Boundaries](../architecture/module-boundaries.md)
- [Module Registry](../module-registry.md)
- [templates/module-template.md](../templates/module-template.md)
