Standard 115: The "Backend-First, Data-Rich" Methodology

ID: STD-115 Category: Development Status: Active

The 5-Domain Architecture

To maintain a disciplined and scalable codebase, we adhere to exactly five top-level domain modules. All other functions are submodules within these domains.

Vertical Application Domains (Business Functions)

1. Community: Resident Registry, Ownership, Occupancy, Contracts, Governance (Votes/Motions).
2. Operations: Maintenance, Work Orders, Asset Management, Hospitality, Utility, Procurement.
3. Finance: Ledger, Payables, Receivables, Budgeting, Reconciliation.

Cross-Cutting Domains (Central Services)

1. Unified: Central AI (Narrative/Babel), Identity, Security, Communications, Admin/God-Mode, Workflow.
2. Foundation: Core Infrastructure, Storage Adapters, Database Utilities, Auth Primitives.

The Sequence

1. Backend Core: Define Entities, Relationships, State Machines, and API Logic.
   • Goal: Logical completeness. (e.g., "The contract can transition from Draft to Signed.")
2. Data Inflation (The "Texture" Sprint): Expand schemas to include "Usual and Customary" fields beyond the MVP.
   • Goal: Operational realism. (e.g., "Tenants have pets, vehicles, and insurance policies.")
   • Action: Update Schemas & Seeding Scripts to generate dense, messy data.

3. Frontend Realization (The "Two-Pass" Strategy):

   • Pass 1: The Skeleton (Read-Only):
   • Goal: Rapid visual assembly of Workbenches using the Design System.
   • Action: Build List/Detail views populated with real data.
   • Constraint: Shift-Left Security (AuthZ checks) IS implemented in the backend, but Frontend "Submit" buttons are stubbed/disabled.
   • Result: A high-fidelity, navigable application (80% feel).
   • Pass 2: The Nervous System (Write/Auth):
   • Goal: Wire the brain to the hands.
   • Action: Connect AuthContext middleware to Server Actions and enable "Write" buttons.
   • Constraint: Only performed after the Domain Model is settled across related modules (e.g., Community + Finance).

4. Verification & Promotion (The "Testing" Sprint):

   • Sequence:
   • Design Tests: Write/Update Backend (Unit/Integration) and Frontend (E2E) suites.
   • Promote to TST: Merge to tst branch (Integration Environment).
   • Execute & Fix: Run suites in CI -> Identify Failures -> Automated/Manual Fix -> Retry.
   • Stabilize: Achieve "Green Build" in TST.
   • Architectural Synchronization (The "As-Built" Audit):
     • Scope: Compulsory update of ALL impacted blueprints.
     • Domain: Update 01_architecture/blueprints/domain_*.md (e.g., Community, Finance).
     • Capabilities: Update 01_architecture/blueprints/06_B_CAPABILITY_MATRIX.md.
     • Data: Update 07_data/dictionary/**/*.md (Schemas).
     • UX: Update 01_architecture/blueprints/BLP-SYS-043_UI_UX_FRAMEWORK.md (Widget/Dashboard patterns).
     • Action: Deprecate/Archive any artifact that conflicts with the "As-Built" reality.
   • Promote to STG: Merge to stg for User Acceptance (UAT).

Application

This standard applies to:

• Refactors: Assess if "Inflation" was skipped before redesigning UI.

Technical Rules of Engagement

1. The "Module First" Law

Business logic NEVER lives in apps/platform/src/app/actions.

• Anti-Pattern: Actions that return mock strings or perform raw data manipulation.
• Standard: Actions must strictly be a "Transport Layer" calling a Service method.
• Bad: export async function getData() { return [{id:1}]; }
• Good: export async function getData() { return service.getData(); }
• Requirement: You must create packages/modules/[domain]/src/[feature] BEFORE touching the frontend.

2. Frontend "Co-location" Standard

Avoid "Monolithic Page Files". Distribute complexity.

• Structure:

  /finance/billing/
  ├── page.tsx (Server Component: Fetches Data, passes to Shell)
  └── _components/
      ├── InvoicesTable.tsx (Client: Sort/Filter/interaction)
      ├── InvoiceStats.tsx (Client: Visuals)
      └── CreateInvoiceForm.tsx (Client: Form)
  

• Benefit: Clearer git diffs, reusability, and optimal hydration boundaries.

3. Server Action Domain Grouping

Prevent the "Flat File" explosion in src/app/actions.

• Structure:

  src/app/actions/
  ├── finance/
  │   ├── payables.ts
  │   └── receivables.ts
  └── operations/
      └── maintenance.ts
  

• Naming: Use [domain]-[feature].ts only if grouping folders are technically unfeasible (which they aren't).