Architecture Enforcement Matrix V1

This matrix turns architecture principles into enforceable controls.

Use it to decide whether a rule is guidance only, warning-level, or CI-blocking.

Enforcement Levels

• AI Agent instruction and review guidance.
• ESLint warn Local warning, non-blocking.
• ESLint error Local hard failure.
• CI gate Required check for merge.

Matrix

Rule	AI	ESLint	CI	Current Target
Scope must be explicit (platform, org, customer)	Required in design/PR notes	Not automated yet	PR template/manual review	AI + review
Route files stay thin	Required	no-restricted-imports guards in src/app/* (mixed error/warn)	Lint + review	Phase 2 started
Route-local _components stay private to their route tree	Required	no-restricted-imports (error)	Lint check	Enforced
Surface component imports from routes go through public entrypoints	Required	no-restricted-syntax in src/app/* (error) with explicit stable sub-entrypoint exceptions	Lint check	Enforced for routes
No long relative climbs across boundaries	Required	no-restricted-imports (error)	Lint check	Enforced
Cross-feature access via public entrypoints only	Required	no-restricted-imports guards in src/app/* and src/features/* (warn)	Lint + review	Phase 2 started
No direct generated Convex API import from UI components/pages	Required	Enforced in specific app/component scopes (error)	Lint check	Enforced
App Convex hooks must go through wrappers	Required	no-restricted-imports (error)	Lint check	Enforced
Shared packages provide primitives; app code provides route-aware adapters	Required	Not automated yet	Review	AI + review
Naming conventions (kebab-case files, camelCase symbols, PascalCase components)	Required	camelcase (warn) + review	Lint + review	Warn phase
Tests default to apps/app/tests/*	Required	Warn when tests are in src/*	Lint check	Warn phase
Platform/org/customer auth boundaries cannot be collapsed	Required	Not automated yet	Review + auth test coverage	AI + review
Tenant ownership must be explicit in data model	Required	Not automated yet	Schema review + migration checklist	AI + review

Phase Plan

Phase 1: Active now

• Keep structural import boundaries strict.
• Keep Convex access wrappers strict.
• Keep naming and test-placement in warning mode to avoid migration thrash.

Phase 2: Tighten after structure stabilizes

• Add strict feature-boundary import rules for domain folders. (Started in warning mode)
• Add route-thinness static checks where feasible. (Started with route import guardrails)
• Promote selected warning rules to errors once noise is low.

Phase 3: Merge-gate maturity

• Add PR template checks for scope declaration and capability declaration.
• Add CI checks for architecture decision record presence on boundary-changing PRs.
• Keep migration-safe schema rollout checks mandatory for breaking changes.

PR Checklist (Short Form)

Include these five lines in PR descriptions for boundary-sensitive changes:

1. Scope: platform or org or customer
2. Data boundary touched:
3. Capabilities required:
4. Cross-feature entrypoint used:
5. Migration-safe rollout needed: yes/no