Skip to content

Phase 1 Implementation Record: Registry & Context Engine

Date: 2026-01-05 Status: Complete Reference: architecture/GOLDEN/GOLDEN-SPEC-PLATFORM-CANONICAL.md Next: Phase 2 (Sidebar Refactor & Server Enforcement)

Summary of Completed Work

We have successfully scaffolded the "Registry-Driven Architecture" authorized by ADR-015. The core "Context Engine" is now live in the application, running alongside (but not yet fully controlling) the legacy navigation.

1. New Artifacts

Component Path Purpose
Context Switcher components/navigation/ContextSwitcher.tsx UI for switching Hat/Scope/Unit. Injected into TopHeader.
Context Provider lib/context/ContextStateProvider.tsx Client-side state machine. Wraps (app)/layout.tsx.
Graph Resolver lib/auth/graph-resolver.ts Server-side logic to build AuthzSnapshot (currently mocked).
Workbench Registry lib/registries/workbench-registry.ts Canonical definition of all routes and their permissions.
Server Action actions/auth-context.ts Bridge between Client Provider and Server Resolver.

2. Wired Connections

  • TopHeader now renders <ContextSwitcher /> if authenticated.
  • AppLayout is wrapped in <ContextStateProvider>.
  • NavigationSystem has a new method getAvailableItems(context) ready to be used.

Phase 2 Plan (Immediate Next Steps)

The underlying engine is ready. Now we must connect the Sidebar to listen to it.

  1. Refactor Sidebar: Update the main navigation component (likely RoleBasedNavigation.tsx or Sidebar.tsx) to consume context and call navigationSystem.getAvailableItems(state).
    • Result: Switching "Hat" in the header will instantly update the Sidebar menu.
  2. Mock Data Expansion: Expand graph-resolver.ts to include more mock scenarios (e.g., "Staff" view, "Board" view) for testing.
  3. Server Enforcement: Begin replacing requireRole in server actions with requireContext (Phase 3).

Known State

  • Legacy Nav: Still active. The Sidebar currently ignores the new Context Switcher.
  • Mock Data: The "Graph" is simulated in graph-resolver.ts. It correctly assigns Owner + Admin hats to dev users.