5c6a2e78cf
Register all active platform services and base features in core DB so admin can manage them, add delivery/hospitality/sports-center backend phases, update apps catalog and production deploy tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
93 lines
3.7 KiB
Markdown
93 lines
3.7 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), [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)
|