moex-vibe/docs/features/frontend-infrastructure-hardening/plan.md

Frontend Infrastructure Hardening Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Stabilize frontend infrastructure and tooling so local development, contract freshness, and mock-based workflows are deterministic and do not rely on temporary compatibility layers.

Architecture: This feature is a small set of related infrastructure follow-ups executed in a controlled order: mock-mode docs and wiring, env validation, tooling consistency, and contract freshness. Each step should leave the project in a working state and avoid changing user-facing runtime behavior except where the infrastructure itself must be activated.

Tech Stack: Vite, MSW, Zod, Biome/ESLint, OpenAPI-generated types, existing frontend tooling scripts.

---

Task 1: Browser mock mode wiring

Files:

• Create/Modify: apps/frontend/mocks/browser.ts

• Modify: apps/frontend/public/mockServiceWorker.js

• Modify: apps/frontend/src/main.tsx

• Modify: apps/frontend/src/shared/config/env.ts

• Modify: apps/docs/docs/development/commands.md

• Modify: apps/docs/docs/frontend/overview.md

• Step 1: Add a browser MSW entry that reuses existing handlers

Ensure the browser worker uses the existing apps/frontend/mocks/handlers.ts instead of duplicating request logic.

• Step 2: Gate worker startup behind VITE_API_MOCK

Hook the browser mock startup into main.tsx so it activates only when the env flag explicitly asks for it.

• Step 3: Document the mock mode behavior

Document the developer-facing rule: mock mode is opt-in, backend-free dev is supported, and the default path still uses the real API.

Task 2: Env validation

Files:

• Modify: apps/frontend/src/shared/config/env.ts

• Modify: apps/frontend/src/main.tsx

• Test: any existing frontend startup/env tests, if present

• Step 1: Define the runtime env schema

Add a Zod schema for required VITE_* variables and keep optional values explicit.

• Step 2: Fail fast on invalid env

Call validation before app render so invalid configuration is visible at startup instead of failing later in a component or query path.

• Step 3: Verify startup messaging

Make sure the error path explains what is missing or invalid without leaking secrets.

Task 3: Tooling consistency

Files:

• Modify: apps/frontend/package.json

• Modify: apps/frontend/.eslintrc.cjs or apps/frontend/biome.json if the project already has a replacement config

• Modify: .gitea/workflows/ci.yml only if the current tooling commands need to be aligned

• Modify: apps/docs/docs/development/commands.md

• Step 1: Verify the command set matches the current toolchain

Keep lint, test, build, and codegen aligned with the real frontend structure and remove stale command references.

• Step 2: Align lint/format docs with reality

Update documentation so it describes the actual commands developers run today, not an earlier migration stage.

• Step 3: Confirm no stale tooling references remain

Remove or rewrite mentions of dead scripts, obsolete shims, or incorrect setup instructions.

Task 4: Contract freshness

Files:

• Modify: apps/frontend/src/shared/api/index.ts

• Modify: apps/frontend/src/shared/api/types.ts only through codegen, not manual edits

• Modify: the specific frontend entity API files that still depend on stale wrapper assumptions

• Modify: apps/docs/docs/frontend/api-client.md

• Modify: apps/docs/docs/frontend/overview.md

• Step 1: Reconcile the frontend contract entrypoints

Ensure the shared API surface points to the actual generated contract types and current public API entrypoints.

• Step 2: Remove stale contract wording from docs

Document the current source of truth for API types and avoid references to temporary compatibility layers.

• Step 3: Verify generated types are treated as generated

Make sure the plan keeps types.ts as generated output and avoids manual editing patterns.

Task 5: Verification

Files:

• Read: changed docs and frontend tooling files

• Step 1: Run the targeted frontend checks

Run:

npm run lint -w apps/frontend
npm run test -w apps/frontend
npm run build -w apps/frontend

Expected: all three commands pass after the infra hardening changes land.

• Step 2: Check mock mode manually

Run:

VITE_API_MOCK=true npm run dev -w apps/frontend

Expected: frontend starts with browser MSW available and does not require the backend for the basic local flow.