# 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) and [module-registry.md](../module-registry.md).
2. Define Objective / Scope / Out of Scope with [phase-template.md](phase-template.md).
3. Add entities ([entity-template.md](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](entity-template.md) |
| Repositories | [repository-template.md](repository-template.md) |
| Services | [service-layer-template.md](service-layer-template.md) |
| APIs | [api-template.md](api-template.md) |
| Events | [event-template.md](event-template.md) |
| Tests | [testing-template.md](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](service-template.md)
- [Master Prompt](master-prompt.md)
- [Module Boundaries](../architecture/module-boundaries.md)
- [Module Registry](../module-registry.md)
- [templates/module-template.md](../templates/module-template.md)