MIZ OKI 3.0 – Frontend Production Contract (Final)

Version: 1.0.0 (FINAL) Authority: ABSOLUTE Enforcement: CI/CD + Code Review Status: ACTIVE

📜 Preamble

This document represents the final, non-negotiable architectural contract for the MIZ OKI 3.0 Frontend ("Command Center UI").

It supersedes all previous emails, Slack messages, Jira tickets, and rough drafts. If code contradicts this document, the code is wrong.

Goal: To deliver a production-grade, neuromorphic AI command center that relies 100% on real Cloud Run microservices and 0% on mock data.

🏛️ The 4 Immutable Laws

Law 1: Zero Mock Data Policy

"If it's fake, it breaks the build."

• PROHIBITED: Math.random(), setTimeout loops for data, hardcoded JSON arrays, faker.js, "sample data" fallbacks.
• REQUIRED: All data must originate from a cellFetch() call to a live Cloud Run endpoint.
• EXCEPTION: None. If a backend service is down, the UI must show an error state, not fake data.

Law 2: The Registered-Cell Architecture

"The Frontend is a window, not a brain."

• The frontend contains no business logic.
• The frontend visualizes the registered-cell backend (39 registered cells — docs/architecture/CELL_REGISTRY.md is the number authority).
• All state management happens in Firestore (via Boss Agent), not Redux/Context.
• Cell Registry: The frontend must recognize and route to all 32 production cells + 3 orchestrators; fleet totals and cell numbering come only from docs/architecture/CELL_REGISTRY.md.

Law 3: SRPVDAL Cognitive Cycle

"Respect the flow."

• The UI must visualize the Sense → Reason → Decide → Act → Learn cycle.
• Data fetching must align with these stages.
  • Sense: Cell 1 (Discovery)
  • Reason: MOA/KG
  • Decide: Cell 15 (Strategy)
  • Act: Cell 16 (Execution)
  • Learn: Cell 23 (Audit/Feedback)
• Do not mix stages (e.g., don't trigger "Action" from a "Sense" component without passing through "Reason" and "Decide").

Law 4: E-SHKG is the Brain

"The Graph holds the truth."

• User state, session history, and knowledge are stored in the E-SHKG (Knowledge Graph).
• The frontend queries the KG (Cell 3/24) to understand "what is happening."
• It does not rely on ephemeral local storage for critical state.

🛠️ Technical Directives

1. Data Fetching Strategy

• Library: @tanstack/react-query (aka React Query v5).
• Client: All calls must use lib/api/client.ts -> cellFetch<T>().
• Hooks: Custom hooks (e.g., useSRPVDALState, useOmnichannelMetrics) must wrap cellFetch.
• Caching: Rely on React Query's staleTime and gcTime.

2. URL & Environment Standardization

• Format: https://[service-name]-698171499447.us-central1.run.app
• Variables:
  • NEXT_PUBLIC_BOSS_AGENT_URL
  • NEXT_PUBLIC_CELL01_URL ... NEXT_PUBLIC_CELL32_URL
• Validation: App must crash at build time if these are missing.

3. Component Architecture

• Server Components (RSC): Use for initial layout and static shell.
• Client Components: Use for all interactive elements and data fetching.
• Strict Mode: React.StrictMode must be enabled.
• Linting: eslint-plugin-no-restricted-syntax must block Math.random.

4. Error Handling

• Global Boundary: A top-level Error Boundary must catch unhandled rejections.
• Cell Failures: Individual components must handle 404/500 errors gracefully (UI Skeleton -> Error Message -> Retry Button).
• No Silent Failures: Errors must be logged to console (and ideally telemetry).

👮‍♂️ Enforcement Mechanisms

1. The PR Checklist

Every Pull Request must strictly adhere to the Pull Request Template. * [] No Mock Data detected? * [] Uses cellFetch? * [] Types exported? * [] Tested against LIVE Cloud Run cells (not localhost)?

2. Automated Guardians (CI/CD)

The .github/workflows/frontend-guard.yml workflow runs on every PR: 1. Mock Data Scan: Greps for forbidden patterns (faker, Math.random, setTimeout). 2. Type Check: Runs tsc --noEmit. 3. Lint: Runs npm run lint. 4. Environment Check: Verifies .env.template matches config.

📝 Governance

• Changes to this Contract: Require approval from the Lead Architect (User) AND the Boss Agent.
• Drift: If the code drifts from this contract, the Code is a Bug and must be fixed.

Signed & Sealed,

Command Center Architecture Team December 12, 2025