TorbatYar/docs/development/project-principles.md

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).
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).
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).
17. Frontend/Backend separation is absolute. (ADR-002).
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 and ai-framework/quality-gates.md.

Related Documents

• Coding Standards
• Testing Strategy
• Architecture Overview
• Module Registry
• AI Development Framework
• ADR-013