Files

T

daniel-c-harvey 0708bb7352 docs: correct pending-registration route references to api/pendingregistration

2026-06-19 22:53:59 -04:00

34 KiB

Raw Permalink Blame History

CMS-PLAN.md — DeepDrftHome admin CMS

Forward-looking plan for the in-site Blazor CMS that replaces DeepDrftCli. Sits alongside PLAN.md (general roadmap) and CONTEXT.md (architecture orientation). Per CONTEXT.md §6, items move from here to COMPLETED.md when work lands; do not delete completed entries.

This document supersedes PLAN.md §2.4 (Web-side track upload) and its open question on authentication. The CMS is the home for that capability; once auth and the CMS surface land here, PLAN.md §2.4 should be archived to COMPLETED.md with a forward-pointer to this file.

§3 (Authentication model) commits to Cerebellum.AuthBlocks as the substrate, based on a read of the library at C:\Development\AuthBlocks\. All open questions are resolved — see §9 for the full resolution record.

1. Goal and motivation

Replace DeepDrftCli with a browser-based admin surface (the CMS) living inside DeepDrftWeb, gated by a login. The CMS owns all track-management operations: add, list, edit, delete. After the CMS is proven, DeepDrftCli retires.

Why now:

The CLI requires shell access to the host machine. Collective members without that access can't add content. The CMS removes that gating without weakening the architectural rule that the browser never reaches the database directly (the CMS still goes through the existing dual-database service boundary — it just runs server-side inside DeepDrftWeb, where direct service references are already permitted).
PLAN.md §2.4 already identified web upload as a near-term need but blocked on the authentication question. The CMS framing answers the wider question (auth is needed for the CMS as a whole, not just for upload) and unblocks the upload work.
The auth surface introduced here is the first identity surface in the product. It is a precondition for several speculative items in PLAN.md cross-cutting (favourites, listening history, per-user playlists). Designing it deliberately now is cheaper than retrofitting it later (feedback_design_for_adaptability).

Non-goals (explicit):

Public account signup. The CMS is for the collective, not the audience. Public-side identity (subscribe, favourites) is a separate future decision.
Replacing the unauthenticated public GET api/track/{id} read path. Listeners continue to stream without auth.
Reworking the dual-database split or the streaming substrate. The CMS is a new consumer of existing seams.

2. Solution structure

2.1 CMS host: `DeepDrftManager`

The CMS is now inlined as the primary content of DeepDrftManager, a dedicated ASP.NET Core Blazor Web App host. All CMS pages, components, view models, and layouts live directly in the host as Components/Pages/Cms/, Components/Pages/Tracks/, Components/Layout/CmsLayout.razor, and Components/Shared/. The prior separate DeepDrftCms RCL design was replaced with this inlined structure for simplicity and tighter integration.

What is in DeepDrftManager:

Pages (.razor) under Components/Pages/Cms/ and Components/Pages/Tracks/, all routed under a single base path (/cms, confirmed in §2 Wave 1).
View models that compose TrackEntity editing state.
CMS-specific components (track-edit form, upload dropzone, confirmation dialogs), inlined directly.
A [HierarchicalRoleAuthorize("Admin")] attribute (from AuthBlocksWeb.HierarchicalAuthorize) on every CMS page component, so Admin and any descendant role are admitted by the bundled hierarchical role handler.
Controllers and minimal-API endpoints for CMS operations (POST api/cms/track, DELETE api/cms/track/{id}, PUT api/cms/track/{id}). Controllers are host-owned per the existing convention. Protected by [Authorize(Roles = "Admin")] — the JWT bearer middleware AuthBlocks installs validates the access token on each request.
The AddAuthBlocks(...) call in Program.cs and the matching await app.Services.UseAuthBlocksStartupAsync() post-build hook. This installs JWT bearer middleware, the hierarchical role authorization handler, the AuthDbContext, the EF migrations, and seeds system roles plus the configured admin user on first boot.
The app.MapAuthBlocks() call that registers /api/auth/*, /api/users/*, /api/roles/*, /api/user-roles/*, and /api/pendingregistration/* minimal-API endpoints. The CMS UI uses /api/auth/login, /api/auth/logout, /api/auth/refresh, and /api/auth/me; the rest are available if Wave 3 account-management ever lands.

Render mode: InteractiveServer for all CMS pages and routes. AuthBlocks's bundled UI (AuthBlocksWeb pages) is server-rendered MudBlazor with JwtAuthenticationStateProvider reading tokens from browser localStorage via JS interop. InteractiveServer is the right fit because: (a) it matches what the bundled login UI uses, (b) InputFile uploads are natively server-side, (c) CMS endpoints live in the DeepDrftManager process with direct access to services.

2.2 Solution changes

DeepDrftManager (ASP.NET Core host) is added to DeepDrftHome.sln as part of the two-app architectural split. This is the CMS host, containing inlined CMS Razor pages and components.
DeepDrftManager references three AuthBlocks packages (NuGet, published as Cerebellum.AuthBlocks* at version 10.3.16+):
- Cerebellum.AuthBlocks — the AddAuthBlocks/UseAuthBlocksStartupAsync/MapAuthBlocks integration surface, JWT services, hierarchical role authorization handler.
- Cerebellum.AuthBlocks.Web — the bundled MudBlazor login/logout/register pages, JwtAuthenticationStateProvider, TokenService (localStorage), and the HierarchicalRoleAuthorizeAttribute / HierarchicalRoleAuthorizeView used by the CMS pages.
- Cerebellum.AuthBlocks.Models — ApplicationUser, ApplicationRole, SystemRole constants. Transitively pulled by the other two; reference explicitly if DeepDrftData needs the entity types.
DeepDrftPublic.Client references Cerebellum.AuthBlocks.Web and calls AuthBlocksWeb.Client.Startup.ConfigureServices(builder.Services) to register AddAuthorizationCore(), AddCascadingAuthenticationState(), and AddAuthenticationStateDeserialization(). This is the prerender → WASM bridge for auth state, equivalent to what DarkModeSettings does today (see CONTEXT.md §3.6).
A new DeepDrftManager/environment/authblocks.json holds the JWT secret, issuer, audience, Mailtrap email connection, admin seed credentials, and Postgres connection string. Follows the same pattern as apikey.json — not in repo.
Infrastructure dependency: PostgreSQL. Both AuthDbContext (identity) and DeepDrftContext (track metadata) run on Postgres (§3.5 Option B confirmed). DeepDrftContext EF migrations must be rewritten from SQLite to Postgres before Wave 1 ships; any existing deepdrft.db rows require a one-time data migration. Local dev gains a docker-compose.yml Postgres service.

3. Authentication model

DeepDrft adopts Cerebellum.AuthBlocks (v10.3.16, source at C:\Development\AuthBlocks\, published as Cerebellum-prefixed NuGets) as a plug-and-play account system. AuthBlocks is built on ASP.NET Core Identity, hands us a complete user/role/registration substrate, and ships its own MudBlazor login UI. The CMS is the first consumer of this substrate in DeepDrftHome.

3.1 What AuthBlocks provides

Concretely, from reading the library source:

User store. Bundled. ApplicationUser : IdentityUser<long> and ApplicationRole : IdentityRole<long> (the long-keyed Identity entities) live in AuthBlocksModels. The AuthDbContext extends IdentityDbContext<...> with the full eight-table layout (users, roles, user_roles, user_claims, role_claims, user_logins, user_tokens, plus AuthBlocks's own pending_registrations and refresh_tokens) under an auth schema. EF migrations ship in the package and run automatically on UseAuthBlocksStartupAsync(). We bring nothing — we just call the extension methods.
Login / UI. Bundled. Cerebellum.AuthBlocks.Web ships server-rendered MudBlazor pages: /account/login, /account/logout, /account/register (registration-code flow), /account/super-register (admin-creates-user), plus admin pages under /user-admin/* for user, role, registration, and permission management. A RedirectToLogin component handles unauthenticated → login redirects with returnUrl preservation, and a LogoutButton is exposed for menus.
Session mechanism. JWT bearer, not cookie. Access tokens (default 60 min) plus refresh tokens (default 7 days) issued by AuthBlocks's minimal-API routes; stored in browser localStorage by TokenService; refreshed automatically by JwtAuthenticationStateProvider. Server-side, the standard [Authorize] / [Authorize(Roles=...)] attributes work because AuthBlocks configures JwtBearerDefaults.AuthenticationScheme as the default authenticate/challenge scheme.
Identity relationship. AuthBlocks sits on top of ASP.NET Core Identity (AddIdentityCore<ApplicationUser>().AddRoles<...>().AddEntityFrameworkStores<AuthDbContext>()), but does not install SignInManager (no cookie-based sign-in) and replaces the default role authorization handler with HierarchicalRolesAuthorizationHandler. Password hashing is the standard ASP.NET Core Identity IPasswordHasher<TUser> — provided, not BYO. Default password policy is relaxed (length 6, no required character classes); we can tighten via the standard Identity options if needed.
Hierarchical roles. SystemRole.Admin (id 1) is the parent of SystemRole.UserAdmin (id 2). Hierarchy is seeded on startup. [HierarchicalRoleAuthorize("UserAdmin")] admits any user assigned Admin or UserAdmin. The hierarchy is extensible by editing SystemRole.cs upstream — for v1 we use what's there.
Admin seeding. A single AdminUserSettings { UserName, Email, Password } on the options object causes UseAuthBlocksStartupAsync to create (or repair) one admin user on first boot, assigned the Admin system role. This is exactly the "seed the first admin at deploy time" capability the CMS needs.
Email. AuthBlocks's registration flow requires an outbound email provider (Mailtrap; EmailConnection.Host + EmailConnection.Token are required options). For v1 we wire this even though the CMS does not exercise the /account/register invitation flow — the options validator throws on startup if it is missing. Wave 3 account-management is when this matters; for Wave 1 we point it at a Mailtrap sandbox.

3.2 Account model

Committed: hierarchical-role accounts via AuthBlocks, seeded with one Admin user from config. This is the option-3 shape from the prior draft and it happens to be exactly what AuthBlocks gives us out of the box:

Real per-user accounts (ApplicationUser table). No shared password.
One seeded admin on first boot via AdminUserSettings. Username, email, password come from DeepDrftManager/environment/authblocks.json (gitignored, same pattern as apikey.json).
No public signup in Wave 1. The /account/register page that AuthBlocks bundles requires a registration code (generated by an admin via /api/pendingregistration). We do not surface /account/register in any nav until Wave 3 account management lands; the route exists but is uninteresting until then.
Mutation attribution. TrackEntity gains a nullable CreatedByUserId : long? column in the W1.2 migration. Populated on every CMS-originated mutation; null for historical CLI-added rows and for any pre-CMS data. Captures attribution from day one even though Wave 1 has exactly one user (feedback_design_for_adaptability).
Role gate. Every CMS page and every api/cms/* endpoint requires the Admin system role. We use Admin rather than introducing a new CmsAdmin role because the collective is small and the existing hierarchy already covers the case; if Wave 3 ever needs finer grain (e.g. a ContentEditor role that can edit but not delete), that is a SystemRole.cs edit upstream, not a redesign here.

3.3 Session and prerender bridge

AuthBlocks's JWT-in-localStorage posture interacts with Blazor's prerender → WASM handoff:

Server prerender of a CMS page asks AuthenticationStateProvider for state. Server-side, that is satisfied by the JWT bearer middleware reading the Authorization header — which is not present on the initial page navigation. The bundled JwtAuthenticationStateProvider runs client-side (it needs IJSRuntime to read localStorage), so during prerender, the user appears anonymous and [Authorize] pages redirect to /account/login.
Solution: CMS pages render as InteractiveServer (no prerender bypass needed since the same circuit handles auth). For the public site's InteractiveAuto pages, AuthBlocks's AddAuthenticationStateDeserialization() (called in DeepDrftWeb.Client.Startup) is the bridge — it carries serialized auth state from prerender into the WASM render and back. This is the same shape as the dark-mode PersistentComponentState bridge described in CONTEXT.md §3.6.
A "Sign in" link in the public-site nav points at /account/login; AuthBlocks's login page returns the user to ReturnUrl on success. The CMS landing page is the natural return target after CMS login.

3.4 Authorization wiring (concrete)

Razor pages in DeepDrftManager: @attribute [HierarchicalRoleAuthorize("Admin")] at the top of every /cms/* page. The bundled handler walks the role hierarchy.

Stealth routing (hard constraint). Non-admin and anonymous requests to any /cms/* route must return 404 Not Found, not a 401 and not a redirect to /account/login. The CMS must not acknowledge its own existence to an unauthorized caller. This is a deliberate departure from the bundled RedirectToLogin pattern: the login redirect is appropriate for intentional authenticated-but-wrong-role access (a signed-in non-admin clicking a CMS link they shouldn't have been shown), but it is wrong for anonymous discovery — a redirect to /account/login on a hit to /cms/tracks reveals that the route exists.

Candidate implementation shapes (decide at build time, not here):
- A custom IAuthorizationMiddlewareResultHandler registered for the /cms/* route prefix that maps AuthorizationFailure to a 404 StatusCodeResult instead of the default challenge/forbid behaviour.
- A custom authorization policy attached to the CMS routes whose handler returns failure via context.Fail(new AuthorizationFailureReason(..., "not found")) and is paired with a result handler that translates that reason to 404.
- A route-level endpoint filter / middleware on the /cms prefix that inspects auth state before the standard authorization middleware runs and short-circuits to 404 when the caller is not in the Admin hierarchy.
Whichever shape lands, the /account/login page itself stays publicly available (the public site links to it). The login page must not auto-redirect a signed-in non-admin to /cms/* either — the CMS surface is invisible from outside the trust boundary.
API endpoints in DeepDrftWeb: [Authorize(Roles = "Admin")] on the new api/cms/track controller. The hierarchical handler is registered globally so the standard [Authorize(Roles=...)] attribute participates in hierarchy walks too.
Anonymous public surface: unaffected. GET api/track/page and GET api/track/{id} remain unauthenticated. The public gallery, player, and home page do not require login. Auth state on the public side is "anonymous or signed-in admin"; signed-in state surfaces only as a "CMS" link in the nav.
Login UI: consume the bundled pages at /account/login, /account/logout. Do not author CMS-specific login pages. The bundled RedirectToLogin component is not used on /cms/* routes — those return 404 per the stealth-routing constraint above. /account/login is reached by direct navigation (the public-site nav, a bookmark, an admin invitation email), not by being redirected there from a CMS URL.
First-run experience: Daniel runs the app, AuthBlocks applies migrations against the Postgres auth schema, seeds Admin + UserAdmin roles, creates the admin user from authblocks.json. Daniel visits /account/login, authenticates, lands on /cms/tracks.

3.5 Database conflict — AuthBlocks is Postgres-only

This is the load-bearing surprise from the AuthBlocks reading. AuthBlocks's data layer hard-codes UseNpgsql(...) in AddAuthBlocksDataForWebApi, the bundled migrations are PostgreSQL-specific (NOW(), timestamp with time zone, identity columns via Npgsql:ValueGenerationStrategy), and the DbContext sets HasDefaultSchema("auth"). DeepDrft's existing metadata DB is SQLite. There is no clean "use SQLite for everything" path.

Three options, in order of preference:

Run Postgres alongside SQLite (recommended). Add a docker-compose.yml Postgres service for local dev; production deploys against a managed PG. SQLite continues to back DeepDrftContext (track metadata); Postgres backs AuthDbContext (identity). The two DbContexts never share a transaction — track mutations and audit attribution are recorded in SQLite with a CreatedByUserId : long? foreign-key-in-name-only to the Postgres auth.users.Id. Cost: a new infra dependency. Benefit: zero forks of AuthBlocks.
Migrate DeepDrftContext to Postgres too. Unify on a single DB engine. Requires rewriting EF migrations, re-seeding from deepdrft.db, and accepting Postgres in every dev environment. Larger lift; cleaner end-state.
Fork AuthBlocks to add SQLite support. Replace UseNpgsql with a provider-agnostic registration, rewrite migrations, maintain the fork. Highest cost, perpetual maintenance burden. Not recommended.

Recommendation: option 1 for Wave 1. It minimises change to DeepDrft and avoids touching DeepDrftContext. Capture option 2 as a deferred consideration if Postgres-for-auth-only feels operationally annoying after a few months of running it. Option 3 is a non-starter unless AuthBlocks gains upstream SQLite support.

Committed: Option B. Both contexts run on Postgres. The EF Core migration rewrite for DeepDrftContext is a Wave 1 prerequisite (W1.0, see §6).

3.6 What this section commits

Cerebellum.AuthBlocks (+ .Web, + .Models) is the auth substrate. We do not write our own user store, password hashing, login pages, or JWT plumbing.
The CMS is gated by the Admin system role via [HierarchicalRoleAuthorize("Admin")] on pages and [Authorize(Roles="Admin")] on API endpoints.
The login UI lives at /account/login (bundled). Logout at /account/logout. The CMS does not author its own.
One admin user is seeded from DeepDrftWeb/environment/authblocks.json on first boot.
TrackEntity.CreatedByUserId : long? is added in W1.2 for attribution.
Postgres becomes a runtime dependency for the auth context, alongside the existing SQLite track-metadata context (pending §3.5 confirmation).
Both DeepDrftContext (track metadata) and AuthDbContext (identity) run on PostgreSQL. EF migrations for DeepDrftContext are rewritten from SQLite to Postgres as Wave 1 prerequisite W1.0.

4. CMS pages and features

The CMS replaces what the CLI does today (add, list, delete) and grows the small set of operations the CLI never offered (edit, image upload). All routes are under /cms (see open question on prefix).

4.1 Wave 1 surface — parity with the CLI

These are the minimum to retire DeepDrftCli.

/cms/tracks — track list. The CMS's mirror of list. The [HierarchicalRoleAuthorize("Admin")] attribute gates the page; per §3.4 stealth routing, anonymous or insufficient-role hits return 404, not a redirect.

Reads the same PagedResult<TrackEntity> that the public gallery reads (GET api/track/page). Per user_one_source_multiple_views, the CMS list is a different rendering of the same VM — table layout with admin affordances (edit, delete buttons), sort columns, optional row-level selection for bulk operations (see Wave 2).
Empty state mirrors the CLI's "No tracks found in database."
Server-rendered. Pagination via the existing endpoint; no new API needed for read.

/cms/tracks/new — add track form. The CMS's mirror of add.

InputFile component for WAV selection (browser-side picker — no server file-path entry, that was a CLI affordance and is wrong for a web upload).
Form fields matching the CLI: track name (required), artist (required), album, genre, release date.
Submit posts to the new upload endpoint (see §5). On success, redirect to /cms/tracks with a flash-style confirmation.
Validation mirrors the CLI: .wav extension required, required fields enforced, release date format YYYY-MM-DD.
Streams the upload to the server rather than reading into memory client-side — large WAVs are common.

/cms/tracks/{id} — track detail / edit form. New surface (the CLI never had edit).

Loads the TrackEntity from the SQL side. Read-write for the metadata fields. Read-only for EntryKey (replacing the binary is a separate "replace audio" action — see Wave 2 open question).
Delete button with confirmation dialog. Calls the new delete endpoint (see §5).

4.2 Wave 2 surface — operations the CLI did not offer

These were never in the CLI but are natural admin needs that appear immediately once the CMS exists. Land after Wave 1 is stable.

Image upload / cover art. Pairs with PLAN.md §2.1 (image vault wired through). The CMS is where image uploads should live — same auth gate, same dual-write pattern as audio. If §2.1 hasn't landed by Wave 2, this is the trigger to land it.
Replace audio for an existing track. Re-upload a WAV against an existing TrackEntity.Id, keeping metadata. Writes a new vault entry, updates EntryKey, schedules the old entry for cleanup (see "dual-write rollback" in PLAN.md §4.3).
Bulk delete of selected rows in the list. UX is simple; the underlying delete endpoint already exists from Wave 1.
Search and filter in the CMS list. Folds into PLAN.md §2.3 — same GetPaged extension serves both surfaces.

4.3 Wave 3 surface — speculative `[speculative]`

Account management UI (if §3.2 option 2/3 is chosen and the collective grows beyond one user).
Audit log view — every CMS mutation written to a small log table, viewable in /cms/audit. Cheap to build once mutations are funnelled through the CMS endpoints; valuable once more than one user can mutate.
Dead-letter view — surface the DeadLetterLog (PLAN.md §4.3) so orphaned vault entries can be inspected and reaped from the CMS rather than via a maintenance script.

5. Server-side dual-write strategy `[open question on transport]`

The dual-write contract is unchanged from the CLI (see CONTEXT.md §3.4 and the existing CliService.HandleAddCommand flow): DeepDrftContent.Services.TrackService.AddTrackFromWavAsync writes the audio to the vault and returns an unpersisted TrackEntity, then DeepDrftWeb.Services.TrackService.Create saves to SQL. The question is where that orchestration runs in the CMS world.

Option A — In-process direct calls (recommended)

The CMS upload endpoint (POST api/cms/track) lives in DeepDrftWeb. DeepDrftWeb adds a project reference to DeepDrftContent.Services (it already exists as a class library — same way DeepDrftCli consumes it). The controller:

Saves the uploaded IFormFile to a temp file (the existing AddTrackFromWavAsync is file-path oriented).
Calls DeepDrftContent.Services.TrackService.AddTrackFromWavAsync(tempPath, ...). This writes to the FileDatabase on the same machine as the running DeepDrftWeb process — which means the vault path in DeepDrftWeb's config must point at the same disk location DeepDrftContent reads from.
On success, calls DeepDrftWeb.Services.TrackService.Create(trackEntity).
Deletes the temp file.
Returns the persisted entity (or an error if either step fails).

Pros: No API key dance. No extra HTTP hop. Mirrors the CLI's existing direct-call pattern exactly — same code path, same orchestration, same failure modes — just triggered by an HTTP request instead of a console command. The dual-write semantics that already exist (and the existing rollback gap from PLAN.md §4.3) carry over unchanged.

Cons: DeepDrftWeb now needs the vault path in its configuration and write access to the shared vault directory. If DeepDrftWeb and DeepDrftContent are ever deployed to different hosts, this option breaks. (Today they coexist on the same host; if that ever changes, option B becomes mandatory.)

Option B — HTTP proxy through `DeepDrftContent.PUT api/track/{id}`

The CMS upload endpoint reads the WAV from the browser, processes it server-side into an AudioBinaryDto, then PUTs it to DeepDrftContent with the API key. Then it calls DeepDrftWeb.Services.TrackService.Create for the SQL side.

Pros: Preserves the host-boundary discipline. DeepDrftWeb never touches the vault disk path. Deployable on separate hosts without change.

Cons: AddTrackFromWavAsync is currently file-path-oriented — to call it from DeepDrftWeb, we'd either need to extract the WAV-processing logic into a stream-oriented overload (worth doing anyway) or duplicate the audio processing in the CMS endpoint. The existing PUT api/track/{id} controller comment in DeepDrftContent/Controllers/TrackController.cs flags that the endpoint receives an already-processed AudioBinaryDto and that "if a file-upload flow is added in future, route it through TrackService instead" — which is itself a vote for option A or for a parallel processing path. Also adds an API-key round-trip per upload.

Option C — Mixed: in-process for audio, in-process for SQL, but with a `DeadLetterLog`

Same as option A but explicitly couples the CMS upload to landing the PLAN.md §4.3 dead-letter mechanism in the same wave. The argument: every web upload narrows the time gap between content-side success and SQL-side failure becoming a real production concern (CLI users hit Ctrl-C; web users get HTTP 502 and try again).

Recommendation

Committed: Option B. DeepDrftWeb proxies the WAV upload to a new POST api/track/upload endpoint on DeepDrftContent (see W1.4 below). DeepDrftWeb never references DeepDrftContent.Services directly and never touches the vault disk path. The host-boundary rule (service projects vs. host projects, CONTEXT.md §3.2) is preserved: binary storage is DeepDrftContent's domain.

Implication for W1.4: The existing PUT api/track/{id} on DeepDrftContent receives an already-processed AudioBinaryDto — it cannot accept a raw WAV file. A new POST api/track/upload endpoint is required on DeepDrftContent that accepts the raw WAV bytes (as multipart/form-data or streaming), runs DeepDrftContent.Services.TrackService.AddTrackFromWavAsync internally, and returns a TrackEntity (unpersisted). DeepDrftWeb's CMS controller calls this endpoint (with the existing API key), receives the entity, and calls DeepDrftWeb.Services.TrackService.Create to persist to SQL. Temp-file handling stays server-side in DeepDrftContent, not in DeepDrftWeb.

Idempotency and rollback (carried-over constraint)

Whichever option lands, the dual-write rollback gap (PLAN.md §4.3) is unchanged: if step 1 succeeds and step 2 fails, audio is orphaned. The CLI lives with this today and so does the CMS in v1. Bringing the dead-letter log forward to Wave 1 is a defensible choice — flag it.

6. Phase decomposition

Themes, not dates. The order between waves is sequential (each depends on its predecessor); within a wave, items can run in parallel against the wave's foundation.

Wave 1 — Auth + scaffolding + parity

Status: Landed 2026-05-18. See COMPLETED.md for full item details.

This wave delivered a logged-in collective member the ability to do everything the CLI does today from a browser. All sub-items (W1.0 Postgres migration, W1.1 RCL skeleton, W1.2 AuthBlocks + stealth routing) are complete.

Wave 2 — Operations the CLI never had

Goal: Make the CMS materially better than the CLI, not just equivalent.

W2.1 Image vault wiring. Fold in PLAN.md §2.1 if it has not landed independently. Image upload UI in the CMS, GET/PUT api/image/{entryKey} on DeepDrftContent, ImagePath semantics shift from URL to entry key.
W2.2 Replace audio. Re-upload WAV for an existing track. Old vault entry queued for cleanup via dead-letter log (see W2.4).
W2.3 Bulk delete + selection. Multi-row affordances on the list. No new endpoint — reuses the per-row delete in a loop.
W2.4 Dual-write rollback / dead-letter log. Land PLAN.md §4.3 here at the latest. Surface orphaned vault entries in a /cms/dead-letter view, with a "delete" action.
W2.5 Search and filter. Fold in PLAN.md §2.3. The CMS list and the public gallery both gain filter via the same GetPaged extension.

Wave 3 — Speculative

[speculative] items from §4.3 plus anything that emerges from Wave 1/2 usage. Do not commit until Daniel signals interest.

7. Constraints and integration points

Things this plan must honour without re-deciding them.

CONTEXT.md §3.2 (service projects vs. host projects). Controllers, middleware, auth wiring live in DeepDrftManager. CMS view models, pages, and components are inlined in DeepDrftManager. No domain logic in the host beyond HTTP concerns.
CONTEXT.md §3.4 (TrackEntity is a join, not a content blob). The new edit endpoint mutates SQL-side metadata only. Binary replacement is a separate operation against the vault.
feedback_no_direct_db_from_network_clients. The CMS runs server-side in DeepDrftManager and is therefore in the trusted process. The browser still does not reach the database — it talks to CMS endpoints, which call the existing services, which call the databases. The architectural rule is preserved.
user_one_source_multiple_views. The CMS list is a different rendering of the same PagedResult<TrackEntity> the public gallery uses. Do not introduce a parallel GetCmsTrackPage endpoint or a parallel VM. If the CMS needs additional fields, extend the existing VM, don't fork it.
feedback_design_for_adaptability. Capture CreatedByUserId on mutations from day one, even with one user. Do not introduce schema columns later as a retrofit.
CONTEXT.md §3.6 (dark-mode prerender bridge). AuthBlocks's AddAuthenticationStateDeserialization() (called in DeepDrftPublic.Client.Startup per §2.2) is the analogue of the dark-mode PersistentComponentState bridge — it carries serialized auth state across the prerender → WASM boundary. For pure-InteractiveServer CMS pages this is unused; it matters for the public-site InteractiveAuto pages that need to render "Sign in" vs "CMS" links consistently.
PLAN.md §0 (audit baseline). The streaming substrate is stable; the CMS does not touch it. Anything the CMS reads from DeepDrftContent goes through the existing GET api/track/{id} path.
Supersession of PLAN.md §2.4. When W1.4 lands, doc-keeper archives PLAN.md §2.4 to COMPLETED.md with a note "subsumed by CMS-PLAN.md Wave 1." This document is the authoritative roadmap for the upload capability.

8. Retirement plan for `DeepDrftCli`

The CLI does not get deleted on day one. Sequence:

Wave 1 lands. CMS reaches parity and is verified working.
Removal. DeepDrftCli project is removed from DeepDrftHome.sln. Its directory is deleted. The Terminal.Gui dependency goes with it. DeepDrftCli/CLAUDE.md is deleted. Stray obj/Debug/net9.0/ artefacts also disappear. The root CLAUDE.md and CONTEXT.md §2 lose the CLI entry — that is a doc-keeper task that lands with the removal commit.

No soak period. DeepDrftCli was an experiment; Wave 1 verification is the only gate before removal.

Committed: Terminal.Gui dropped entirely. The browser CMS subsumes the use case. DeepDrftCli is removed in step 2 above; the Terminal.Gui NuGet dependency goes with it.

9. Open questions for Daniel

All open questions are resolved. This section is retained as a record.

Resolved questions (in order of resolution):

Postgres strategy: Option B — both DeepDrftContext and AuthDbContext on PostgreSQL.
CMS structure: Inlined into DeepDrftManager host (not a separate RCL).
URL prefix: /cms.
Render mode: InteractiveServer with MudBlazor.
Dual-write transport: Option B — HTTP proxy through DeepDrftContent; new POST api/track/upload endpoint required.
CMS scope: Wave 1 = parity (add/list/edit/delete), Wave 2 = image upload / replace audio / bulk delete / dead-letter / search+filter.
CLI retirement: immediate on Wave 1 verification. No soak.
Terminal.Gui: dropped.
Email provider: Mailtrap sandbox for Wave 1.

10. Working with this file

Same conventions as PLAN.md. Items move to COMPLETED.md when they land; do not delete. Original "What / Why / Shape" body preserved. Open questions belong in the item that raises them — they expire when the item does. The exception is §9, which is a single rendezvous point for all blocking decisions; entries there are removed as Daniel answers them (and the marked-up sections elsewhere collapse to commitments at the same time).
Markers. [open question] = a decision point inside an otherwise-committed item. [speculative] = direction inferred, not committed. (Previous draft used [TBD pending Daniel's input] for whole sections that could not commit; the §3 auth section that carried it has since been resolved against the AuthBlocks source.)
Relationship to PLAN.md. When the CMS work touches an item in PLAN.md (notably §2.1 image vault, §2.3 search/filter, §2.4 web upload, §4.3 dead-letter), this document is the place to coordinate the joint landing. Cross-reference rather than duplicating the item's body.

34 KiB Raw Permalink Blame History