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>
96 lines
3.8 KiB
Markdown
96 lines
3.8 KiB
Markdown
# Service Layer Template
|
||
|
||
Standards for business logic services, commands, queries, policies, and specifications.
|
||
|
||
Enterprise default: phases deliver these layers for in-scope capabilities — CRUD-only services are insufficient ([definition-of-done.md](definition-of-done.md), [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md)).
|
||
|
||
## Responsibility
|
||
|
||
Services:
|
||
|
||
- Own domain rules and orchestration
|
||
- Validate invariants (via validators / specifications)
|
||
- Apply policies (authorization, entitlement, domain policy objects)
|
||
- Expose **Commands** (state changes) and **Queries** (reads without write side-effects)
|
||
- Write audit records
|
||
- Write outbox/domain events in the **same transaction** as state changes
|
||
- Call other services only via HTTP clients / events — never via foreign repos
|
||
- Receive dependencies via explicit injection (constructor / factory / FastAPI deps)
|
||
|
||
Services must **not**:
|
||
|
||
- Depend on FastAPI `Request` / response objects
|
||
- Emit raw SQL bypassing repositories (except rare documented cases)
|
||
- Perform provider I/O without going through provider adapters owned by the service
|
||
- Mutate another aggregate’s invariants across boundaries without explicit domain rules
|
||
- Duplicate another service’s business logic ([boundary-rules.md](boundary-rules.md))
|
||
|
||
## Commands
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Location | `app/commands/` or clearly named command methods on services |
|
||
| Naming | Verb phrases (`CreateMember`, `FreezeMembership`) |
|
||
| Effect | Single use-case state change; emit audit + outbox as required |
|
||
| Idempotency | Document for retried operations |
|
||
|
||
## Queries
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Location | `app/queries/` or query services / read methods |
|
||
| Effect | Read-only; no accidental writes or event emission |
|
||
| Lists | Support pagination, filtering, sorting, searching as API requires |
|
||
|
||
## Specifications
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Location | `app/specifications/` |
|
||
| Purpose | Reusable query predicates and business specification objects |
|
||
| Use | Repositories/services compose specs instead of duplicating filter logic |
|
||
|
||
## Policies
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Location | `app/policies/` |
|
||
| Purpose | Authorization, entitlement, and domain policy decisions reusable across commands |
|
||
| Note | Route-level permission deps remain; policies encode richer domain rules |
|
||
|
||
## Conventions
|
||
|
||
| Topic | Rule |
|
||
| --- | --- |
|
||
| Location | `app/services/` (+ commands/queries/policies/specifications) |
|
||
| Naming | `{Capability}Service` |
|
||
| Dependencies | Repositories, validators, specs, policies, event publisher, provider protocols |
|
||
| DTOs | Accept/return schema objects or typed domain results — not ORM leakage to API |
|
||
| Errors | Raise shared/domain exceptions with stable codes |
|
||
| Idempotency | Document for retried operations (OTP, webhooks, messaging) |
|
||
| DI | Explicit wiring; no hidden service locators for domain logic |
|
||
|
||
## Transaction & Events
|
||
|
||
1. State change + outbox row in one transaction ([ADR-006](../architecture/adr/ADR-006.md)).
|
||
2. Event types follow [event-template.md](event-template.md).
|
||
3. Failures calling remote systems must not corrupt local invariants; use async patterns where required (Communication pattern).
|
||
|
||
## Audit
|
||
|
||
- Record actor, action, entity, tenant, timestamp for sensitive mutations.
|
||
- Prefer dedicated audit tables where the service already has them.
|
||
|
||
## Testing
|
||
|
||
Service / command / query / policy / specification tests cover business rules with DB or fakes — see [testing-template.md](testing-template.md).
|
||
|
||
## Related Documents
|
||
|
||
- [Repository Template](repository-template.md)
|
||
- [API Template](api-template.md)
|
||
- [Mandatory Phase Artifacts](mandatory-phase-artifacts.md)
|
||
- [Project Principles](../development/project-principles.md)
|
||
- [Service Architecture](../architecture/service-architecture.md)
|
||
- [Event-Driven Architecture](../architecture/event-driven-architecture.md)
|