tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #55 from mrteye/plan-hypermedia-architecture-5555508364227023504

Browse Source 
docs(plan): add hypermedia architecture migration plan

migration from the legacy `server/` and `ui/` directories to a domain-oriented vertical slice architecture under `src/features/`. The plan spans four phases: Core Foundation, Base Slices, Real-Time Slices, and Architectural Testing.
This commit is contained in:
Tyler Gillispie 2026-08-27 17:17:16 -07:00 committed by GitHub
commit 9fdb97f3f4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 55 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md Normal file
View File

@ -0,0 +1,55 @@
# 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).