auth-yes/tasks/in-progress/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, Tooling & Safety Guards

Establish the authoritative infrastructure, transport toolkit, and invariant guards inside src/core/.

1. Create src/core/ directory.
2. Migrate and adapt foundational integrations from server/ (strictly read-only reference):
   • 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 checks).
4. Implement content_negotiation.ts to route between Datastar HTML, CLI/JSON clients, and shell strings.
5. Implement sse_adapter.ts for typed Datastar SSE streaming helper logic.
6. Implement error_fragments.tsx for standardized error toast and field-error JSX morph fragments.
7. Setup src/main.ts with serveStatic for /public/datastar-v1.x.js.
8. Add deno task lint:arch in scripts/lint_arch.ts (blocking document.getElementById and unescaped HTML) and integrate into deno.json.

Phase 2: Base Vertical Slices & Shared UI

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

1. Create src/shared/ui/ with distinctive fragment names (LayoutFragment, NavbarFragment, ToastFragment, DrawerShellFragment, PillGroupFragment, AccordionFragment).
2. Create src/features/auth/ and migrate /login, /register, and /recovery. Extract WebAuthn ceremony scripts into webauthn.ts with explicit data-ignore attributes.
3. Create src/features/admin/ and migrate admin routes, SQL queries, and fragments (AdminUserTableFragment, AdminAppCardFragment, RoleModalFragment).
4. Add pure JSX unit tests: auth.test.ts and admin.test.ts.

Phase 3: Real-Time Slices & Script Elimination

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

1. Create src/features/events/:
   • Migrate event routing, queries, and JSX fragments (EventCockpitDeckFragment, WorkshopPassDrawerFragment, GuestDrawerAttendeesFragment).
   • Implement stream.ts using src/core/sse_adapter.ts for live seat counters bound to Valkey Pub/Sub.
2. Create src/features/sessions/:
   • Migrate routing, queries, and fragments (SessionTableFragment, SessionHandoffCardFragment, DirectPassDrawerFragment).
   • Eliminate legacy SessionsScript.tsx completely, replacing interactive flows with Datastar reactive attributes (data-on-click, data-patch).
3. Add pure JSX unit tests: events.test.ts and sessions.test.ts.

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).

Phase 5: Legacy Deprecation & Final Cleanup

Execute cleanup only after Phase 4 architectural tests and existing test suites pass 100%.

1. Safely delete legacy server/ and ui/ directories.
2. Perform dead-code cleanup and dependency verification.
3. Verify all gates: deno fmt, deno task lint, deno task check, and deno test -A --no-check.