auth-yes/tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md

TASK METADATA

• Target Files: src/core/, src/features/, src/shared/, src/tests/arch/, server/ (legacy), ui/ (legacy). Note: sdk/ and spire_ffi/ must remain independent top-level root modules.
• Core Objective: Execute a multi-phase, non-overlapping architectural transition to a Datastar-driven Hypermedia paradigm and Vertical Feature Slicing.
• Dependencies: docs/HYPERMEDIA_ARCHITECTURE_BLUEPRINT.md, AGENTS.md.
• Additional Important Notes: The code does not need to maintain backwards-compatible bridges for legacy vanilla scripts during intermediate phases; optimize for a clean, uncompromised vertical slice architecture in src/.

---

Architectural Considerations & Risks

• Risks:
  • Moving from a separated server/ and ui/ structure to co-located src/features/ will require extensive routing and import refactoring.
  • Dropping legacy imperative DOM scripts in favor of Datastar requires strict adherence to data-ignore for WebAuthn micro-scripts so the DOM diffing engine doesn't wipe critical ceremony state.
  • Converting SSE streams to the typed adapter (core/sse_adapter.ts) might break existing real-time UI components if payload formats are mismatched.
• Alternatives:
  • Instead of moving to src/, we could restructure within server/. However, adopting src/features/ enforces a clean break from the legacy horizontally sliced architecture and clearly demarcates the new vertical hypermedia standard.

Proposed Implementation

Phase 1: Core Foundation & Datastar Engine

Establish the authoritative infrastructure and invariant guards inside the new src/core/ boundary.

1. Create src/core/ directory.
2. Migrate and adapt foundational integrations from server/:
   • db.ts: PostgreSQL connection pool and queries.
   • valkey.ts: Valkey connection and Pub/Sub broker.
   • spire_ffi.ts: Rust SPIFFE/mTLS FFI bindings.
3. Implement auth_guards.ts (enforcing max 16KB payload cap, rate limiting, and CSRF/Origin check).
4. Implement content_negotiation.ts to cleanly route between standard Datastar HTML requests, CLI/JSON clients, and shell strings.

Phase 2: Base Vertical Slices & Shared UI

Migrate domain-agnostic presentation atoms and standard CRUD-style feature slices.

1. Create src/shared/ui/ and migrate generic components (Layout, Navbar, Toast, DrawerShell, PillGroup, Accordion). Ensure Layout.tsx loads /public/datastar-v1.x.js.
2. Create src/features/auth/ and migrate /login, /register, and /recovery. Extract WebAuthn ceremony scripts into webauthn.ts and ensure target DOM nodes include data-ignore attributes.
3. Create src/features/admin/ and migrate admin routes, SQL queries, and fragments (RoleModals, AdminTables) for user and app management.

Phase 3: Real-Time Slices Migration

Migrate the complex, interactive features and eliminate legacy imperative scripts in favor of targeted SSE and Datastar morphs.

1. Create src/core/sse_adapter.ts for typed Datastar SSE streaming helper logic.
2. Create src/features/events/:
   • Migrate event routing, queries, and JSX fragments (EventCockpit, WorkshopDrawer).
   • Implement stream.ts using the new typed SSE adapter for live seat counters bound to Valkey Pub/Sub.
3. Create src/features/sessions/:
   • Migrate routing, queries, and fragments (SessionTable, HandoffCard).
   • Eliminate legacy SessionsScript.tsx completely, replacing interactive flows with Datastar attributes (data-on-click, data-signals).
4. Delete legacy server/ and ui/ directories once migration is fully verified.

Phase 4: Persistent Architectural Test Suite

Implement the invariant test harness defined in the blueprint to prevent regression.

1. Create src/tests/arch/.
2. Implement transport_efficiency.test.ts (asserts routine mutations return text/html in <2ms).
3. Implement sse_lifecycle.test.ts (asserts connection limits, draining, and memory stability for 100+ concurrent live listeners).
4. Implement proxy_buffering.test.ts (asserts X-Accel-Buffering: no is emitted).
5. Implement error_fragment.test.ts (asserts 4xx/5xx responses yield valid JSX morph fragments for #status-banner).
6. Implement content_negotiation.test.ts (asserts proper dual-mode REST vs Datastar handling) and xss_fuzzing.test.ts (fuzzes fragment rendering).