# Engineering Constitution This document freezes the engineering governance for ALLA OS after the Business Constitution (`BU-R.0`, `BU-R.0.1`, `BU-R.1`), Architecture Constitution (`AR.1`, `AR.2`), and Workspace UI Constitution are in place. It defines how future implementation work must be designed, coded, reviewed, tested, and delivered. --- ## 1. Purpose and Precedence ### Purpose - keep implementation aligned with the Relationship-Driven Sales Workspace blueprint - preserve current production foundations while enabling controlled extension - prevent duplicate services, APIs, projections, UI systems, and business logic - give engineers and AI agents one shared delivery model ### Governance precedence Future work must follow this order: 1. business constitution and business blueprint documents 2. architecture transition and epic technical design documents 3. this Engineering Constitution 4. workspace UI/UX governance 5. existing approved foundations and feature implementations If two sources conflict, the higher item in this list wins unless a newer accepted ADR explicitly replaces it. ### Mandatory inputs before implementation Every implementation task must review: - `AGENTS.md` - `docs/standards/project-foundations.md` - `docs/standards/architecture-rules.md` - `docs/standards/ui-ux-rules.md` - `docs/standards/task-review-checklist.md` - `docs/standards/task-catalog.md` - relevant `docs/adr/**` - relevant `docs/business/**` - relevant `docs/security/**` - relevant `docs/implementation/**` - relevant existing foundations under `src/features/foundation/**` - relevant existing feature implementations under `src/features/**` No implementation may bypass this review-first rule. --- ## 2. Feature Architecture Rules ### Feature ownership model - each domain or shared capability must have one owning feature or foundation - route handlers are HTTP boundaries, not business owners - shared cross-cutting behavior must live in a foundation before a second feature reimplements it - new CRM work must extend `src/features/crm/**` or `src/features/foundation/**` instead of creating parallel top-level domains ### Approved feature structure Default structure for app-owned features: ```text src/features// api/ types.ts service.ts queries.ts mutations.ts components/ schemas/ server/ ``` Allowed additions when justified: - `adapters/` for migration seams or projection adapters - `lib/` for feature-local pure helpers - `constants/` for feature-local stable constants - `hooks/` for feature-local client hooks ### Layer responsibilities - `api/types.ts`: public TypeScript contracts for UI and service consumers - `api/service.ts`: client-facing API client wrappers only - `api/queries.ts`: React Query key factories and query options - `api/mutations.ts`: centralized mutation configs and invalidation behavior - `components/`: UI composition only - `schemas/`: request payload validation and form schemas - `server/`: business logic, persistence orchestration, scope enforcement, data shaping ### Public and internal modules - only `api/**`, `components/**`, and explicitly shared helpers are public to outside consumers - `server/**` is internal to the owning feature unless consciously reused by another server-side feature - client components must not import database or server-only modules - cross-feature imports should target stable public contracts, not incidental internals ### Shared module rules - shared UI belongs in `src/components/**` or an approved foundation/shared area - shared business logic belongs in the owning foundation or feature server layer - do not create shared modules only to avoid choosing ownership ### Cross-feature dependency rules Allowed direction: - app routes -> feature API/services/components - route handlers -> auth/session/validation -> owning feature server services - feature server services -> foundations and lower-level shared security/utilities - projections/read models -> source services or approved dataset layers Forbidden direction: - source domains depending on projection-only domains for write behavior - features reaching directly into another feature's UI internals - client code importing Drizzle, server-only services, or auth enforcement modules - projection code becoming the write owner of business lifecycle state ### Feature registration rule Before creating a new feature, confirm that the need cannot be satisfied by extending: - an existing CRM feature - an existing foundation - an existing report, approval, PDF, storage, audit, or security layer If a new feature is still required, document why reuse was insufficient. --- ## 3. Service Layer Standards ### Service composition The service layer owns business rules. It may be split into: - business services - query services - projection services - application/orchestration services - domain-specific helper adapters ### Frozen service rules - route handlers stay thin - services own business lifecycle rules - services enforce server-side scope, pricing visibility, and permission-sensitive behavior - services may call foundations and approved sibling services when reuse is explicit - services must not contain UI concerns - services must not authorize with raw role strings alone ### Business ownership boundaries - `Customer` owns relationship anchor behavior - `Lead` owns early demand signal behavior - `Opportunity` owns project pursuit and won/lost outcome behavior - `Quotation` owns commercial document lifecycle - `Approval` owns approval workflow execution - future `Activity` owns shared operational work records - `Timeline`, `Calendar`, `My Day`, `Manager`, and `Executive` are read-model or workspace consumers, not primary write owners ### Transaction boundary rules - one service owns the transaction for one business mutation - downstream side effects such as audit logging, notifications, event publishing, or artifact updates must happen from the owning service flow - avoid multi-route, UI-driven orchestration for business-critical mutations ### Query and projection service rules - query services return read-ready data and may combine multiple foundations - projection services are read-only and rebuildable - projection services must not become hidden write paths - report services must reuse the report foundation dataset and builder layers ### Internal repository rule This repo does not use a heavyweight repository architecture. Allowed pattern: - lightweight persistence helpers or adapters inside `server/` - Drizzle queries close to the owning service Forbidden pattern: - introducing a parallel abstract repository layer across the app without a project-level decision --- ## 4. Repository and Persistence Standards ### Ownership - each table or schema area must have a clear owning feature or foundation - only the owning server service should perform write orchestration for its tables - cross-feature readers should prefer owning services or approved read models before querying tables directly ### Persistence rules - use Drizzle ORM for database access - keep SQL and query composition inside server services or approved dataset modules - reuse existing dataset and export services for reporting work - do not move domain logic into route handlers just because Drizzle is easy to call there ### Backward compatibility - preserve existing production contracts while extending them - use additive migration patterns first - dual-read or adapter-first strategies are preferred for high-risk transitions such as Activity and projection work --- ## 5. API Standards ### Boundary - Route Handlers under `src/app/api/**` are the default HTTP boundary - new CRM APIs belong under `/api/crm/**` - settings or foundation APIs belong under their existing route families ### Route handler contract Every route handler should: 1. require session or organization access 2. validate permissions 3. parse and validate request input 4. build access/security context when needed 5. call the owning server service 6. map response 7. log audit or security events where applicable ### Naming and path rules - use plural resource names for collection routes - use nested child routes only when the child lifecycle is truly parent-scoped - use action routes only for explicit domain transitions such as `mark-won`, `submit-approval`, `complete`, `cancel` - avoid generic verb-heavy route families when a resource-oriented route can express the behavior ### Validation - use Zod for request validation at the boundary - reuse feature schemas where possible - validation error messages should be business-readable and not leak backend detail ### Response rules - preserve current stable contract shapes inside an existing route family - new routes should prefer predictable JSON responses with clear success, data, and meta sections when not constrained by an existing family - list routes should return pagination metadata when pagination exists - API responses must remain ISO-8601 UTC for datetime fields ### Authorization - use `requireSession()`, `requireSystemRole()`, or `requireOrganizationAccess()` - CRM routes must apply resolved CRM access and scope enforcement - UI visibility never replaces server authorization ### Filtering, sorting, and search - filters should be explicit, typed, and documented in feature contracts - use URL-driven filter state for shareable list screens - keep filtering semantics aligned between on-screen data and exports ### Versioning strategy - preserve compatible route contracts whenever possible - prefer additive fields and child routes over breaking replacements - introduce a new route shape only when compatibility cannot be preserved cleanly --- ## 6. Business Event, Projection, and Timeline Rules ### Event philosophy - business events are immutable facts emitted after successful state changes - events are not a replacement for audit logs - events may fan out to timeline, calendar, dashboard, notification, reminder, or future automation ### Publisher ownership - source-domain services publish their own events - do not centralize event publishing in UI or ad hoc route helpers - preserve current approval notification compatibility while expanding the event model ### Event contract rules - use lowercase dot-separated event names - include `schemaVersion` - include organization, entity, actor, primary record, related records, and visibility context - event payloads must avoid leaking pricing-sensitive or unauthorized commercial data ### Projection rules - `Timeline` and `Calendar` are generated projections only - projections are read-only and rebuildable - projections never own lifecycle state - phase 1 projection services should favor query-time generation or cacheable read models before new authoritative tables ### Projection ownership - activity projections belong to the Activity and projection layers - milestone projections remain owned by their source domain semantics - dashboard and reports consume projections or source datasets but do not become source-of-truth mutations ### Idempotency and dedupe - event publication and subscribers must support safe retry behavior - notification or projection consumers must guard against duplicate fan-out - approval events require extra care because notification publishing already exists --- ## 7. UI Engineering Rules ### Required UI inputs All user-facing work must review: - `layout.md` - `docs/standards/ui-ux-rules.md` - relevant business terminology docs - nearby production screens in the same route family Major workspace surfaces must also reference: - `BU-R.0` - `BU-R.0.1` - `BU-R.1` - `AR.1` - `AR.2` - the latest workspace UI/UX design note ### Frozen UI rules - preserve the existing dashboard shell - use `PageContainer` for dashboard page framing - reuse shadcn/ui primitives and app wrappers - reuse existing table, form, filter, dialog, sheet, badge, and status patterns before creating new ones - new business-role workspaces live under `/dashboard/crm/*`, not `/dashboard/workspaces` - no code-first implementation for major new workspace surfaces without an approved design note ### Data and state rules - server components first - use React Query for server-state fetching - use server prefetch plus `HydrationBoundary` for data-heavy app pages - use `nuqs` for shareable URL state - use TanStack Form plus Zod for new forms ### UX state rules Every surface must define: - loading states - empty states - error states - disabled and pending action states - permission-aware visibility behavior - responsive behavior ### Accessibility rules - semantic controls and accessible names are required - keyboard navigation must remain usable for tables, dialogs, sheets, tabs, and menus - focus behavior must be predictable - status cannot be conveyed by color alone --- ## 8. Code Quality Standards ### Naming - use business terms frozen by the business and architecture constitutions - keep active production terminology aligned with `opportunity`, not historical `enquiry`, unless touching historical-only documentation - use clear, explicit function and file names over vague generic helpers ### File and folder naming - keep file names lowercase kebab-case unless a framework convention requires otherwise - use stable feature-local names such as `service.ts`, `queries.ts`, `mutations.ts`, `types.ts` - avoid creating near-duplicate files with ambiguous suffixes like `service2`, `new`, or `final` ### TypeScript rules - strict typing is required - avoid `any` - define public contracts explicitly in `api/types.ts` or equivalent shared contracts - keep server-only and client-safe types clearly separated when necessary ### Error handling - expected business or authorization failures should produce explicit typed or status-aware errors - do not leak SQL or infrastructure internals to business-facing surfaces - centralize reusable failure behavior where patterns already exist ### Logging and audit - use the audit foundation for business mutations, exports, and sensitive denials - use ordinary console logging only for operational debugging or unexpected failures - logs must not become a substitute for governed audit events ### Validation - validate at the boundary - revalidate critical business invariants inside services when necessary - do not trust client-side validation alone ### Comments - comments should explain non-obvious business or security rules - avoid comments that restate the code ### Technical debt policy - prefer preserve -> extend -> controlled refactor -> replace - small cleanup is encouraged when it improves safety or clarity - unrelated rewrites are prohibited --- ## 9. Database and Migration Standards ### Migration strategy - additive, backward-compatible migrations are preferred - schema changes must preserve current production behavior until replacement paths are proven - high-risk data model changes must document migration and coexistence strategy first ### Schema ownership - schema changes must be owned by the relevant feature or foundation - projection schemas, if introduced later, must remain clearly separate from source-of-truth tables ### Rollback strategy - every risky migration must define rollback or safe-disable behavior - do not require emergency manual data surgery as the normal rollback path ### Seed strategy - foundation seeds remain the source for governed options and bootstrap records where already used - new seed data must be deterministic and documented ### Explicit non-changes rule Documentation-only tasks must not silently modify schema, migrations, or runtime persistence behavior. --- ## 10. Testing Standards ### Minimum testing lens Each implementation must define the right mix of: - unit tests - service tests - route handler or API tests - permission and scope tests - projection and event tests where applicable - regression tests for preserved behavior - manual verification scenarios ### Required test themes - happy path behavior - permission denial behavior - scope enforcement behavior - pricing visibility behavior for quotation-derived outputs - audit/event side effects when applicable - cache freshness after CRUD mutations ### Projection and event testing - timeline and calendar work must verify ordering, filtering, visibility, and dedupe behavior - event-driven work must verify idempotency and compatibility with existing notification flows ### UAT checklist baseline - loading state visible - empty state helpful - error state actionable - successful mutation refreshes the affected UI without manual browser refresh - mobile and desktop layouts remain usable --- ## 11. Delivery Rules ### Epic lifecycle Each epic must define: - objective - non-goals - reviewed history and foundations - API and service boundaries - security and pricing rules - audit and event behavior - verification plan - rollout and rollback notes when risk is non-trivial ### Feature lifecycle For feature implementation: 1. review requirements and historical context 2. identify reuse targets 3. confirm architecture and security boundaries 4. define smallest viable extension 5. implement in the owning layer 6. self-review architecture, UI, data freshness, and security 7. validate 8. document results ### Review gates - architecture review - business rule review - security and permission review - UI consistency review for user-facing work - regression and backward-compatibility review ### Release and rollback baseline - document migrations and toggles when present - document impacted routes or surfaces - document known compatibility seams - document rollback or safe-disable path for non-trivial changes --- ## 12. Definition of Done ### Feature - required review completed - foundations reused or non-reuse rationale documented - implementation stays within approved architecture - permissions, scope, and pricing visibility enforced server-side where applicable - audit and event behavior handled where required - loading, empty, error, disabled, and success states covered for user-facing work - validation completed and recorded - documentation updated if governance or reusable patterns changed ### Epic - feature-level done conditions met for each delivered slice - sequence and dependency assumptions remain compatible with `AR.2` - cross-feature duplication was not introduced - migration or rollout notes recorded for future slices ### Bug Fix - root cause identified - fix scoped to the owning layer - regression risk checked - validation performed against the failing scenario ### Refactor - ownership and behavior preserved unless explicitly approved otherwise - backward compatibility risks documented - no unrelated behavior churn introduced --- ## 13. AI Engineering Rules AI contributors must follow the same governance as human contributors. ### Mandatory AI rules - review before implementation - reuse before creation - preserve before refactor - never duplicate business logic, lifecycle logic, projection logic, or permission logic - identify existing services, routes, and components before adding new ones - keep route handlers thin - keep business logic in services - keep projections read-only - record assumptions and validation results ### AI implementation checklist Before writing code, confirm: - business constitution reviewed - architecture constitution reviewed - engineering constitution reviewed - workspace UI constitution reviewed when UI is involved - relevant ADRs reviewed - related implementation history reviewed - relevant foundations inspected - existing pattern search completed - reuse plan chosen - validation plan defined --- ## 14. Code Review Checklist ### Architecture - does the change extend the right owning feature or foundation? - does it avoid parallel services, APIs, or UI systems? - does it preserve route-handler-thin and service-owned business logic? ### Business - does it follow frozen domain ownership and terminology? - does it avoid moving responsibility into the wrong layer? ### Security - are permission, scope, and pricing rules enforced server-side? - are raw role-string checks avoided? - are denials audited when needed? ### Performance and data freshness - are query keys and invalidation complete? - are projections or datasets using the approved read paths? - does the UI refresh correctly after mutation? ### Accessibility and UI consistency - does the surface reuse approved page, table, form, dialog, and state patterns? - are loading, empty, error, and responsive states covered? ### Maintainability and backward compatibility - are contracts explicit? - does the change avoid hidden coupling and duplicate logic? - are compatibility seams, rollout notes, or follow-up risks documented? --- ## 15. Engineering Decision Matrix Use this matrix before choosing implementation strategy. ### Preserve Use when: - the existing module already owns the behavior - the change is additive or corrective - replacement would create unnecessary migration risk ### Extend Use when: - the existing module is the correct owner - new capability fits the current architecture - a controlled addition avoids parallel systems ### Controlled Refactor Use when: - current ownership is correct but the structure blocks safe extension - refactor reduces duplication or clarifies a reusable seam - compatibility can be preserved during the change ### Replace Use only when: - preserve, extend, and controlled refactor are insufficient - replacement rationale is explicit - migration and rollback strategy are documented - governance review accepts the risk ### Explicit rule If a task cannot explain why it is preserving, extending, refactoring, or replacing, it is not ready for implementation. --- ## 16. Official ENG.0 Outcome ENG.0 freezes one engineering model for future ALLA OS implementation: - review-first - reuse-first - service-owned business logic - route-handler-thin API boundaries - resolved-access security enforcement - projection-as-read-model, not source-of-truth - shared UI shell preservation - explicit validation, audit, and delivery discipline No future implementation epic may bypass this constitution.