# Project Principles

These principles are mandatory for every implementation phase.

1. **Every feature must be tenant-aware.** Business data always carries and filters by `tenant_id`.
2. **Every business action must be auditable.** Persist audit metadata or equivalent domain events.
3. **Business logic only inside Services.** Controllers/routers stay thin.
4. **Repositories contain no business logic.** Persistence and queries only.
5. **Views / API handlers remain thin.** Validate, authorize, delegate, map responses.
6. **Every phase must include tests.** No phase complete without automated coverage for new behavior.
7. **Every phase must update documentation.** Code and docs ship together.
8. **No TODO in completed phases.** TODOs mean the phase is not done.
9. **No cross-tenant query.** Platform-admin exceptions must be explicit and logged.
10. **No direct JournalEntry creation.** Posting Engine only ([ADR-010](../architecture/adr/ADR-010.md)).
11. **Compliance is independent.** Compliance controls are not optional UI features.
12. **AI is independent.** Core business flows work when AI is off ([ai-architecture.md](../architecture/ai-architecture.md)).
13. **Everything event-ready.** Prefer outbox-backed domain events for cross-service effects.
14. **Everything API-first.** UI is a client, not the source of truth.
15. **Everything documented.** Registries, ADRs, contracts, and progress stay current.
16. **Database-per-service.** No cross-DB access ([ADR-001](../architecture/adr/ADR-001.md)).
17. **Frontend/Backend separation is absolute.** ([ADR-002](../architecture/adr/ADR-002.md)).
18. **No hardcoded brand or secrets.** Config/env/database only.
19. **Documentation before conflicting code.** If implementation conflicts with architecture, stop and fix docs/ADR first.
20. **Phase completion gate.** Follow the checklist in [docs/README.md](../README.md) and [ai-framework/quality-gates.md](../ai-framework/quality-gates.md).
21. **Enterprise Definition of Done.** Every phase must satisfy [ai-framework/definition-of-done.md](../ai-framework/definition-of-done.md). CRUD is never sufficient.
22. **Mandatory production artifacts by default.** Deliver applicable items from [ai-framework/mandatory-phase-artifacts.md](../ai-framework/mandatory-phase-artifacts.md) without waiting for the phase prompt to restate them.
23. **Boundary discipline.** Never own another service’s responsibilities, duplicate its logic, access its database, or pull future-phase features forward ([ai-framework/boundary-rules.md](../ai-framework/boundary-rules.md)).
24. **Enterprise Completeness verification.** Sign off [ai-framework/enterprise-completeness.md](../ai-framework/enterprise-completeness.md) before Complete; implement any missing current-phase requirement first ([ADR-018](../architecture/adr/ADR-018.md)).
25. **Enterprise Phase Discovery.** Before Implementation, run [ai-framework/enterprise-phase-discovery.md](../ai-framework/enterprise-phase-discovery.md): inventory roadmap, architecture, boundaries, prior handover, codebase, APIs, domain, events, permissions, aggregates, tests, and docs; promote missing current-phase capabilities into Scope ([ADR-019](../architecture/adr/ADR-019.md)).

## Related Documents

- [Coding Standards](coding-standards.md)
- [Testing Strategy](testing-strategy.md)
- [Architecture Overview](../architecture/architecture.md)
- [Module Registry](../module-registry.md)
- [AI / Enterprise Development Framework](../ai-framework/README.md)
- [Enterprise Phase Discovery](../ai-framework/enterprise-phase-discovery.md)
- [Definition of Done](../ai-framework/definition-of-done.md)
- [ADR-013](../architecture/adr/ADR-013.md)
- [ADR-018](../architecture/adr/ADR-018.md)
- [ADR-019](../architecture/adr/ADR-019.md)