Frontend Architecture Governance

This document serves as the day‑to‑day governance guide for developers working on the MIZ OKI 3.0 frontend. It distils the key rules from the engineering standard and production contract into actionable guardrails.

Why this exists

MIZ OKI 3.0 integrates a complex microservice mesh (39 registered cells; 32-cell production core) with a real‑time dashboard and command console. To prevent drift, mock data regression or interface confusion, every engineer must follow this governance. It ensures that the frontend remains truthful, maintainable and aligned with backend evolution.

Key principles

• Truth over convenience – if a value appears on screen it must come from a cell. Avoid shortcuts like random numbers, placeholders or guesses.
• Single source of fetch logic – use cellFetch for all network calls. Do not embed base URLs or call fetch directly.
• React Query for queries, not streams – fetch once and cache or poll using React Query; for SSE use native EventSource.
• Canonical cell IDs – always refer to cells by their uppercase names (e.g. CELL01), and ensure the corresponding NEXT_PUBLIC_… environment variables exist.
• Client components – annotate any file that uses hooks or browser APIs with "use client";.
• No mock data in production – Math.random(), setTimeout, setInterval and hardcoded arrays for domain data are forbidden. UI state is fine.

Practical checklist for new work

1. Identify which cell(s) you need to talk to.
2. Use or add an API wrapper in apps/web/lib/api/.
3. Create a React Query hook in apps/web/hooks/api/.
4. Build a client component that consumes the hook. Show skeletons and errors.
5. Add navigation via SidebarNav if this is a new page.
6. Commit your changes and run the CI script; ensure no mock patterns are detected.

Governance enforcement

Pull requests must include the phrase “I confirm this PR introduces no mock data and complies with the Frontend Architecture Governance.” The CI workflow will scan for forbidden patterns. Non‑compliant code will be rejected.

Refer to docs/frontend-engineering-standard.md and docs/frontend-production-contract.md for detailed rules and context.