allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

commit eng0

Browse Source
This commit is contained in:
phaichayon
2026-07-07 19:46:31 +07:00
parent 919d9e4f8a
commit f47fea5d6f
3 changed files with 1146 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/implementation/task-eng.0-engineering-governance-2026-07-07.md Normal file
View File

@@ -0,0 +1,70 @@
# Task ENG.0 Implementation Report - 2026-07-07
## Scope
- start and complete the documentation-only Engineering Governance phase
- review business, architecture, UI, standards, security, and current implementation patterns already frozen by BU-R and AR work
- produce the official engineering governance baseline for future implementation tasks
## Review Summary
Reviewed before drafting:
- `AGENTS.md`
- `plans/task-eng.0.md`
- `docs/standards/task-contract-template.md`
- `docs/standards/task-catalog.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `layout.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/business/relationship-sales-workspace-blueprint-v1.md`
- `docs/implementation/task-bu-r.0-business-blueprint-freeze-2026-07-07.md`
- `docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.md`
- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md`
- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md`
- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md`
- `docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md`
- `src/lib/auth/session.ts`
- `src/lib/auth/crm-access.ts`
- representative route/service/foundation patterns under:
- `src/app/api/crm/**`
- `src/features/crm/customers/**`
- `src/features/products/**`
- `src/features/users/**`
- `src/features/foundation/audit-log/**`
- `src/features/foundation/approval/**`
- `src/features/foundation/storage/**`
## What Was Produced
- official engineering governance baseline:
`docs/standards/engineering-constitution.md`
## Key Decisions Captured
1. ENG.0 freezes review-first and reuse-first implementation as mandatory, not optional advice.
2. Feature ownership, service boundaries, Route Handler patterns, and projection rules now follow one documented model aligned with current repo structure.
3. Business logic remains service-owned; projections remain read-only; route handlers remain thin.
4. Security enforcement is frozen around resolved CRM access, server-side scope enforcement, and pricing visibility checks.
5. UI implementation is frozen to existing dashboard shell, `PageContainer`, shadcn/ui reuse, and no-code-before-design for major new workspace surfaces.
6. Database, testing, delivery, AI implementation, and code review expectations are now documented in one standards file future tasks can cite directly.
7. Preserve -> Extend -> Controlled Refactor -> Replace is frozen as the engineering decision matrix for change strategy.
## Verification
- Documentation-only change.
- No schema, migration, API, service, UI, permission, or runtime business-logic files changed production behavior.
- No build or test command was required for this phase.
## Outcome
ENG.0 now gives ALLA OS an explicit Engineering Constitution aligned with:
- Business Constitution (`BU-R.0`, `BU-R.0.1`, `BU-R.1`)
- Architecture Constitution (`AR.1`, `AR.2`)
- Workspace UI Constitution
- current foundations and production code patterns already present in the repository

701
docs/standards/engineering-constitution.md Normal file
View File

@@ -0,0 +1,701 @@
# 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/<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.