Merge pull request #29 from mrteye/jul-monolith-audit-16234354212497883361

story(arch): draft monolith decomposition roadmap

tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md

@@ -0,0 +1,73 @@
+# 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`.