1---2name: architecture-principles3description: Project decision-making framework. All 23 principles (S1-S7, F1-F2, A1-A14) with one-liners and enforcement. Read this before starting any task. See reference.md for full rationale, examples, and edge cases.4---56# Architecture Principles — Quick Reference78When you face a design decision, find the applicable principle below. If the one-liner is enough, follow it. If you need rationale or examples for a novel situation, see [reference.md](reference.md).910## SDLC Principles (How Work Gets Done)1112| ID | Principle | One-liner | Enforced By |13|----|-----------|-----------|-------------|14| S1 | Done = verified | Unit tests + lint + end-to-end — not just "it compiles" | `task-completed-gate.sh` |15| S2 | Humans decide, machines verify | Operator = CPO/CTO; agents + hooks catch bugs | Review gates, hooks |16| S3 | Executable, not advisory | If there's no hook/gate enforcing it, it's a suggestion | `validate-patterns.sh`, gates |17| S4 | Understand WHY | Rationale enables generalization to novel situations | This document |18| S5 | Spec = contract | Post-approval, system delivers without further human intervention | Orchestrator workflow |19| S6 | Fail fast, fail early | Progressive gates catch issues at the earliest possible stage | Hooks → review → UAT |20| S7 | Knowledge compounds | Every deviation gets encoded as a hook, skill, or gotcha | `DEVIATIONS.md` → updates |2122## Foundation Principles (Architecture ↔ Process)2324| ID | Principle | One-liner | Enforced By |25|----|-----------|-----------|-------------|26| F1 | Prescriptive architecture | If an agent invents structure, that's an architecture gap — file it | Reviewer, orchestrator |27| F2 | Self-evident standards | Knowing layer relationships predicts naming, flow, shape, tests | Domain skills, A10 |2829## Architectural Principles (How Code Is Structured)3031| ID | Principle | One-liner | Enforced By |32|----|-----------|-----------|-------------|33| A1 | Thin routers, fat services | Routers wire deps + delegate. No `.select()` in routers. | `validate-patterns.sh` BLOCKS |34| A2 | DB config, code behavior | No-deploy changes = DB rows; test-requiring changes = code | Reviewer |35| A3 | Two data planes | Supabase REST+RLS for user CRUD; psycopg for high-volume/framework | Reviewer |36| A4 | React Query ≠ Zustand | Server state in React Query; client-only state in Zustand. Never duplicate. | Reviewer |37| A5 | Auth from getSession() | Never use Zustand auth store for API tokens | `validate-patterns.sh` BLOCKS in hooks |38| A6 | Tools = capability units | New capability = BaseTool subclass + service + DB row + registry | backend-patterns recipe |39| A7 | Cross-channel default | Every message feature works web + Telegram via shared chat_id | product-architecture checklist |40| A8 | Scoped access + RLS | Routers use `get_user_scoped_client`; services use scoped or system client; raw `get_supabase_client` blocked. RLS as defense-in-depth. | `validate-patterns.sh` BLOCKS |41| A9 | UUID FKs, not names | All inter-table refs use UUID FK with ON DELETE. Never agent_name TEXT. | `validate-patterns.sh` BLOCKS |42| A10 | Predictable naming | Entity "foo" → `foos` table, `foo_service.py`, `foo_router.py`, `useFooHooks.ts` | `validate-patterns.sh` (tools) |43| A11 | Design for N | Pluggable patterns; config over new infrastructure | Reviewer |44| A12 | Autonomy + safety rails | Approval tiers, RLS, audit logs — enable autonomy, don't restrict it | Reviewer |45| A13 | User config is first-class | Users can inspect and modify their settings and data | Reviewer |46| A14 | Pragmatic progressivism | Build abstractions when proven; don't over-engineer | Reviewer |4748## Using Principles in Your Work4950- **In code comments/commits:** cite by ID — `# Per A1, delegate to service`51- **In reviewer verdicts:** every BLOCKER cites a principle — `A8: Table missing RLS`52- **In specs:** ACs reference relevant principles — `AC-03: Cross-channel delivery [A7]`53- **Novel situation?** Read the full rationale in [reference.md](reference.md) for the closest principle54- **Nothing covers it?** That's an F1 gap — flag to orchestrator
tim-o-private