Codex 7 — Engineering Doctrine

Principles

1. 1Platforms, not pages. Systems, not features. Decades, not releases.
2. 2Separation of concerns. Presentation, business logic, and data access are distinct layers. Business rules do not live in components.
3. 3Modularity. Every capability is a module with a declared interface. Modules are replaceable without rewriting their consumers.
4. 4API before integration. Define the contract, then integrate. Never the reverse.
5. 5Normalized data. One canonical row per real-world thing (Codex 5).
6. 6Configuration over custom code. No hardcoded values that a future operator will need to change.
7. 7Documented assumptions. Anything non-obvious is written down where the next engineer will find it.
8. 8Maintainability over speed alone. Speed that produces debt is not speed.

Non-functional requirements — always in scope

• Security. Server-side authorization, validated input, least privilege, secrets never in client code, no privileged client bypass.
• Auditing. Consequential actions produce immutable audit records with actor, subject, time, and reason.
• Logging and observability. Structured logs, traceable failures, no secrets in logs.
• Permissions. Enforced at the data layer, derived from scoped roles.
• Analytics. Measured for institutional learning, never for attention capture.
• Localization. Content and layout ready for other languages from the start.
• Accessibility. A functional requirement, tested like any other.
• Performance. Load only what a view needs; server-side data loading through route loaders and cached queries.
• Reliability. Graceful degradation; failure of a peripheral engine never takes down the core.

Platform constraints of record

• Routing is TanStack Router; the route tree is generated and never hand-edited. No second router is introduced.
• App-internal server logic uses server functions; external callers use public API routes that verify the caller.
• Server code runs in an edge worker runtime: no native binaries, no subprocesses, no reliance on an OS filesystem.
• The backend is Lovable Cloud. Every public table ships with explicit grants and row-level policies in the same migration that creates it.
• Environment values are read inside handlers, never at module scope.

Testing and verification

Verification output is read in full. An exit code of zero with error text in the output is a failure. Every structural change is typechecked before it is called done.

Technical debt

Debt is permitted only when named: what was traded, why, and what would repay it. Unnamed debt is a defect.