e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# 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)
|