tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/tasks/complete/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md

5.6 KiB
Raw Blame History

TASK METADATA

  • Target Files: server/main.ts, server/main.test.ts, ui/components/SessionsPage.tsx, server/auth-session.ts, ui/mod.ts, infra/setup.ts, ui/utils/bip39_wordlist.ts (and copies), spire_ffi/Cargo.lock, ui/components/AdminInvitesPage.tsx, ui/components/AdminUserDetailsPage.tsx, deno.lock, ui/components/AdminRolesPage.tsx, ui/components/AdminAppsPage.tsx
  • Core Objective: Architect a phased, zero-regression modular decomposition plan to eliminate monoliths and enforce the Single Responsibility Principle.
  • Dependencies: None.
  • Additional Important Notes: Must preserve zero-dependency SDK purity (@auth-yes/sdk) and guarantee 100% backward compatibility with all quality gates (deno fmt, deno task lint, deno task check, deno task test).

2. Architectural Considerations & Risks

  • Risks:
    • Circular Dependencies: Moving components could introduce circular dependencies, especially between auth-session.ts and routing files.
    • Regression: Splitting monolithic files (e.g., main.test.ts) might cause tests to fail or miss edge cases if not carefully separated by domain tier.
    • Client-Side Breakage: Extracting inline JS strings from JSX (e.g., SessionsPage.tsx) to external vanilla JS files could break dynamic interactions if DOM elements are not correctly targeted or if loading sequence is altered.
  • Alternatives:
    • Instead of extracting completely to static files, use Deno Island architectures if supported, but given the strict instruction to use pure Hono SSR JSX (strictly no React) and vanilla JavaScript, static ES modules under ui/public/ui/ or ui/static/ is the optimal, native approach.

3. Proposed Implementation

The refactoring will be executed in a safe, phased approach to guarantee zero regressions:

Phase 1: UI Sessions Decomposition (Frontend)

  • Target: ui/components/SessionsPage.tsx
  • Actions:
    • Extract the Event Cockpit Deck logic into ui/components/sessions/EventCockpitDeck.tsx.
    • Extract the Workshop Launch Drawer logic into ui/components/sessions/WorkshopDrawer.tsx.
    • Extract the 1:1 Delegation Drawer logic into ui/components/sessions/DirectPassDrawer.tsx.
    • Extract the Scope Modal logic into ui/components/sessions/ScopeModal.tsx.
    • Move the 400+ lines of raw client-side JavaScript currently embedded in string templates (dangerouslySetInnerHTML) into a dedicated static vanilla JS module (e.g., ui/public/ui/sessions.js) and link it via a <script type="module" src="..."> tag.
  • Validation: Run UI unit tests, deno task lint, and visual checks to ensure all modals and JS interactions still work.

Phase 2: UI Admin Pages Decomposition (Frontend)

  • Target: ui/components/AdminInvitesPage.tsx, ui/components/AdminUserDetailsPage.tsx, ui/components/AdminRolesPage.tsx, ui/components/AdminAppsPage.tsx
  • Actions:
    • Refactor large admin pages (all > 490 lines) by extracting repeated layout structures, table rendering, and modal dialogs into reusable components (e.g., ui/components/admin/AdminTable.tsx, ui/components/admin/AdminModal.tsx).
    • Move embedded client-side javascript logic from these files into corresponding static vanilla JS modules in ui/public/ui/.
  • Validation: Visual validation of admin interfaces, deno task lint.

Phase 3: Server Route Modularization (Backend)

  • Target: server/main.ts and server/routes/
  • Actions:
    • Extract Admin CRUD routes (/api/admin/*) into a new file: server/routes/admin.ts.
    • Extract WebAuthn and Passkey logic (/api/login, /api/register, /api/passkeys) into server/routes/auth.ts.
    • Move ConnectRPC daemon orchestration and middleware/rate limiting setup into dedicated configuration modules (e.g., server/middleware.ts, server/rpc.ts).
    • Keep server/main.ts purely as the application entrypoint for mounting sub-routers.
  • Validation: Run deno task test to ensure all API endpoints resolve correctly.

Phase 4: Infrastructure Scripts Refactoring (DevOps)

  • Target: infra/setup.ts
  • Actions:
    • Split the 1000+ line setup script.
    • Extract CLI configuration/prompt logic into infra/setup/cli.ts.
    • Extract Docker compose generation/writing logic into infra/setup/compose.ts.
    • Extract environment variable handling into infra/setup/env.ts.
  • Validation: Run deno check infra/setup.ts and verify script execution against a dummy environment.

Phase 5: Test Suite Tier Separation (Testing)

  • Target: server/main.test.ts
  • Actions:
    • Split the 1,300+ line test monolith by domain.
    • Create server/tests/auth.test.ts for WebAuthn PRF and Cookie Domain scoping.
    • Create server/tests/forward_auth.test.ts for Tier 1/2 ForwardAuth tests.
    • Create server/tests/rpc.test.ts for Tier 3 ConnectRPC tests.
    • Create server/tests/events.test.ts for Event passes and Session delegation tests.
  • Validation: Run deno task test and ensure all hermetic tests pass without Docker.

Phase 6: Core Logic Refactoring (Utilities)

  • Target: server/auth-session.ts and ui/mod.ts
  • Actions:
    • Split server/auth-session.ts: Move ForwardAuth ingress logic to server/forward_auth.ts, and Valkey/Postgres resolution to server/session_resolver.ts.
    • Split ui/mod.ts: Separate database queries and admin authorization checks from pure SSR page routing. Create ui/db_queries.ts and ui/auth_checks.ts.
  • Validation: Full suite deno task check, deno fmt, and deno task test.