alla-allaos-fullstack/docs/implementation/task-b1-foundation-stabilization.md

Task B.1 Foundation Stabilization

1. Executive Summary

Task B.1 completed two goals:

1. Foundation Stabilization
2. Production Isolation

The foundation layer from Task B is now safer to use for Task C because:

• foundation seed data now exists for master options and document sequences
• production CRM routes no longer import legacy CRM mock services
• legacy CRM demo code has been isolated under dedicated crm-demo paths
• TypeScript compilation passes after the route and module isolation changes

No Customer, Contact, Enquiry, Quotation, Approval, KPI, Report, PDF, or Notification production module was added in this task.

2. Foundation Review

2.1 Schema Review

Reviewed tables introduced in Task B:

• ms_options
• document_sequences
• tr_audit_logs

Current strengths:

• all three tables consistently use organization_id
• ms_options supports soft delete through deleted_at
• ms_options has a unique constraint on (organization_id, category, code)
• document_sequences has a unique constraint on (organization_id, document_type, period, branch_id)
• tr_audit_logs supports before_data, after_data, and request_id

Current migration notes:

• ms_options does not yet enforce a foreign key from parent_id back to ms_options.id
• document_sequences does not yet enforce a foreign key to a branch model because branch is still abstraction-only
• tr_audit_logs does not yet enforce foreign keys to organizations or users
• tr_audit_logs could benefit from future read-oriented indexes such as (organization_id, entity_type, entity_id) once audit queries are introduced

Decision:

• no schema change was made in Task B.1 for the above notes because the task explicitly asked not to change schema unless necessary

2.2 Service Review

Reviewed foundation services:

• auth-context
• organization-context
• permission
• branch-scope
• master-options
• document-sequence
• audit-log

Review summary:

• naming is consistent with Task B expectations
• return shapes are now stable enough for Task C
• organization-first design is preserved across helpers
• error handling is explicit in permission, organization, branch, and seed flows

Implementation adjustments made in Task B.1:

• searchParams was extended so isolated demo routes no longer break type checks
• crm-demo compile issues were cleaned up without changing its business behavior
• production CRM route tree now uses placeholder or foundation-safe pages only

3. Seed Review

3.1 Foundation Seed Added

Seed script added:

• src/db/seeds/foundation.seed.ts

Package scripts updated:

• seed:foundation
• setup:db now includes seed:foundation

Seed behavior:

• loads DATABASE_URL from .env.local or .env
• reads organizations from the database
• throws a clear error if no organizations exist
• seeds foundation data for every organization found

3.2 Master Options Seeded

Seeded categories:

• crm_branch
• crm_customer_status
• crm_customer_type
• crm_enquiry_status
• crm_quotation_status
• crm_product_type
• crm_currency
• crm_payment_term
• crm_priority
• crm_lead_channel

Important notes:

• seeding is idempotent via on conflict
• crm_branch options are seeded first and reused by document sequence seed
• no organization id is hardcoded

3.3 Document Sequence Seeded

Seeded sequence types:

• customer -> CUS
• contact -> CON
• enquiry -> ENQ
• quotation -> QT
• approval -> APV

Behavior:

• seeded per organization
• seeded per seeded branch option
• idempotent via on conflict
• uses the current YYMM period
• throws clearly if required organization or branch data is unavailable

4. Production Isolation Review

4.1 Production-Ready Path

Production-safe CRM route path now lives under:

• src/app/dashboard/crm/**

Current production-safe routes:

• /dashboard/crm
• /dashboard/crm/customers
• /dashboard/crm/customers/[id]
• /dashboard/crm/enquiries
• /dashboard/crm/enquiries/[id]
• /dashboard/crm/quotations
• /dashboard/crm/quotations/[id]
• /dashboard/crm/approvals
• /dashboard/crm/settings/document-sequences
• /dashboard/crm/settings/templates
• /dashboard/crm/settings/master-options

Production-safe behavior:

• no route above imports @/features/crm-demo/**
• no route above imports mock query/service layers
• master-options remains connected to the real foundation path
• all other CRM production routes are explicit placeholders until Task C and later tasks build real modules

4.2 Legacy Mock Path

Legacy CRM mock module was moved to:

• src/features/crm-demo/**

Legacy demo route tree was moved to:

• src/app/dashboard/crm-demo/**

The old mock flow is still preserved for reference and manual comparison, but it is no longer the production path.

4.3 Route Separation

Production route:

• /dashboard/crm

Demo route:

• /dashboard/crm-demo

Separation achieved:

• production route tree does not import demo services
• demo route tree imports @/features/crm-demo/**
• demo links inside the moved module now point to /dashboard/crm-demo/**

5. Mock Modules Moved

Moved feature module:

• src/features/crm -> src/features/crm-demo

Moved route tree:

• src/app/dashboard/crm legacy implementation -> src/app/dashboard/crm-demo

Then recreated:

• src/app/dashboard/crm/** as production-safe placeholder/foundation routes

6. Files Added

Documentation

• docs/implementation/task-b1-foundation-stabilization.md

Foundation Seed

• src/db/seeds/foundation.seed.ts

Production CRM Placeholder Support

• src/features/foundation/components/crm-production-placeholder.tsx

Production CRM Routes

• src/app/dashboard/crm/page.tsx
• src/app/dashboard/crm/customers/page.tsx
• src/app/dashboard/crm/customers/[id]/page.tsx
• src/app/dashboard/crm/enquiries/page.tsx
• src/app/dashboard/crm/enquiries/[id]/page.tsx
• src/app/dashboard/crm/quotations/page.tsx
• src/app/dashboard/crm/quotations/[id]/page.tsx
• src/app/dashboard/crm/approvals/page.tsx
• src/app/dashboard/crm/settings/document-sequences/page.tsx
• src/app/dashboard/crm/settings/templates/page.tsx
• src/app/dashboard/crm/settings/master-options/page.tsx

Demo Route / Feature Path Created By Move

• src/app/dashboard/crm-demo/**
• src/features/crm-demo/**

7. Files Modified

• package.json
• src/lib/searchparams.ts
• src/features/crm-demo/api/service.ts
• src/features/crm-demo/components/customers-table.tsx
• src/features/crm-demo/components/enquiries-table.tsx
• src/features/crm-demo/components/quotations-table.tsx

8. Production Routes Verified

Verification result:

• production /dashboard/crm/** no longer depends on legacy CRM mock service imports
• master-options is the only CRM route currently wired to a real foundation-backed data path
• all remaining production CRM routes are intentionally placeholders so Task C can start cleanly

9. Remaining Risks

• production CRM modules still need real tables and route handlers before the placeholders can be replaced
• tr_audit_logs has no foreign keys or query indexes yet
• branch scope is still option-based abstraction and not a dedicated branch domain model
• document sequences are seeded by branch option id, so future branch modeling must preserve or migrate that relationship carefully
• crm-demo still contains legacy mock business logic by design, even though it is isolated from the production path

10. Task C Readiness

Task C can begin safely now because:

• production route tree is no longer tied to mock CRM state
• foundation seed data can be created repeatably
• document sequences can be initialized for real organizations
• production CRM paths are reserved for organization-first implementation
• TypeScript compilation passes after the isolation work

Recommended Task C entry point:

• build Customer and Contact on top of:
  • organization context
  • permission helpers
  • branch abstraction
  • master options
  • document sequence helper
  • audit log helper