# 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).

## Related Documents

- [Coding Standards](coding-standards.md)
- [Testing Strategy](testing-strategy.md)
- [Architecture Overview](../architecture/architecture.md)
- [Module Registry](../module-registry.md)
- [AI Development Framework](../ai-framework/README.md)
- [ADR-013](../architecture/adr/ADR-013.md)
