​
Frontend Architecture Guide

Route vs feature ownership baseline: docs/architecture/frontend-ownership-matrix.md.

​
Current Runtime Layout

  • frontend/src/app/: route segments and page entrypoints.
  • frontend/src/components/: shared and feature UI components.
  • frontend/src/lib/, frontend/src/hooks/, frontend/src/contexts/: client-side utilities and state wiring.
  • frontend/src/features/org-admin/: canonical org-admin feature lane.

​
Refactor Direction

  • Organize by product feature ownership, not generic component buckets.
  • Keep route segments aligned with product surfaces:
  • user
  • org admin
  • super admin
  • simulation admin
  • Remove dead or duplicated surfaces only after validating the replacement route path.

​
Component Boundary Rules

  • Large page components should be split into:
  • container/orchestration component
  • presentational sections
  • feature-local hooks/helpers
  • Keep cross-feature shared UI in components/ui or components/shared.
  • Current split increments completed:
  • ScenarioLabPanel.tsx delegates derived-view logic to ScenarioLabPanelSelectors.ts.
  • PolicySettingsPanel.tsx delegates parsing/normalization helpers to policySettingsParsers.ts.

​
Test Placement Policy

  • Frontend tests are colocated (*.test.tsx, *.integration.test.tsx).
  • frontend/src/**/__tests__/ trees are disallowed.
  • Keep route smoke tests for critical user/admin flows.

​
Migration Safety

  • Preserve existing routes and navigation behavior until replacement pages are verified.
  • Prefer compatibility redirects over abrupt route removals.
  • Validate role-based access and admin navigation after structural moves.