alla-allaos-fullstack/docs/standards/engineering-constitution.md

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:

src/features/<feature>/
  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.