daniel/deepdrft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity
Files
ef8a0e9c6ed3562ce4a00fff2fc25b96cf056e6f
deepdrft/PLAN_authblocks_trackmanager.md
T

38 KiB
Raw Blame History

PLAN — AuthBlocks startup separation + TrackManager / ITrackService cleanup

Working plan for two connected workstreams. Standalone execution doc; not part of the themed PLAN.md roadmap. When this work lands, the relevant bodies move to COMPLETED.md per the CONTEXT.md §6 convention, and the ITrackService cross-cutting note in PLAN.md (line ~192) should be retired since this plan resolves it.

Status: awaiting Daniel's approval. Engineering is not dispatched until then.

Goal

Make DeepDrftAPI the AuthBlocks API host (own registration, migration/seed, and endpoint mounting; Manager keeps only web-side auth), and enforce a clean layer boundary on the SQL side: TrackRepository outputs entities; ITrackService / TrackManager outputs DTOs (via TrackConverter). The current ITrackService returns TrackEntity everywhere — that is the defect. The interface changes to return TrackDto for all query and mutation results, making TrackConverter the single authoritative entity→DTO conversion path and putting it inside the service layer where it belongs, rather than at scattered call sites.

Scope note — a third consumer the brief did not name

The brief lists CLI and UnifiedTrackService as the non-HTTP ITrackService consumers. There is a third: DeepDrftPublic consumes ITrackService in two places —

  • DeepDrftPublic/Services/TrackDirectDataService.cs (server-side SSR prerender; calls .GetPaged).
  • DeepDrftPublic/Controllers/TrackController.cs (the public api/track/page endpoint; calls .GetPaged).
  • Registered in DeepDrftPublic/Startup.cs as AddScoped<ITrackService>(sp => sp.GetRequiredService<TrackManager>()).

Whatever happens to ITrackService must keep DeepDrftPublic compiling. This is load-bearing for the wave plan below: under Daniel's clarified rule (repository → entity, service → DTO), an ITrackService signature change is no longer optional — the interface itself flips to DTO return types, so every consumer is in the blast radius, including all four projects (DeepDrftAPI, DeepDrftManager, DeepDrftCli, DeepDrftPublic). The public host returns TrackEntity to its own WASM client today; whether that wire format also moves to DTO is now an explicit decision point (see Workstream 2, Q2.3) rather than a settled scope-out — the layer rule applies system-wide, so the default is that Public aligns too.

Workstream 1 — AuthBlocks startup separation

Current state

DeepDrftManager/Program.cs does all four AuthBlocks responsibilities:

  1. builder.Services.AddAuthBlocks(options => { ... }) (lines 35–63) — EF Identity, JWT services, email sender, admin-seed config. Reads ConnectionStrings:Auth + all AuthBlocks:* keys.
  2. AuthBlocksWeb.Startup.ConfigureAuthServices(builder.Services, baseUrl) (line 68) — web-side cascading auth state + JWT client for the /account/login + /account/logout Razor pages.
  3. await app.Services.UseAuthBlocksStartupAsync() (line 119) — EF migrate + seed roles/admin.
  4. app.MapAuthBlocks() (line 143) — mounts /api/auth/*, /api/users/*.

DeepDrftManager.csproj references both AuthBlocksLib and AuthBlocksWeb. The authblocks.json secrets file is loaded into Manager's config (lines 23–24).

DeepDrftAPI/Program.cs has no AuthBlocks anything. It already loads environment/connections.json (line 46) for DefaultConnection (SQL metadata) and has a CORS policy ContentApiPolicy driven by CorsSettings.AllowedOrigins from appsettings.json (lines 22–37), applied via app.UseCors("ContentApiPolicy") (line 81).

Target state

  • Manager: keeps only step 2 (ConfigureAuthServices). Drops steps 1, 3, 4. Drops the AuthBlocksLib package reference; keeps AuthBlocksWeb. No longer loads authblocks.json for AddAuthBlocks, but see secrets migration below — it likely still needs the JWT validation subset.
  • DeepDrftAPI: gains steps 1, 3, 4. Becomes the AuthBlocks API host — auth endpoints live alongside track endpoints. Gains the AuthBlocksLib package reference, an Auth connection string, and the authblocks.json secrets. CORS policy widened to allow the Manager origin so the Manager's browser client can call /api/auth/* cross-origin.

Files touched

File Change
DeepDrftManager/Program.cs Remove AddAuthBlocks block (35–63), UseAuthBlocksStartupAsync (119), MapAuthBlocks (143). Keep ConfigureAuthServices (68). Adjust authblocks.json load (23–24) to the JWT-validation subset or remove if unused — see open question Q1.1.
DeepDrftManager/DeepDrftManager.csproj Remove AuthBlocksLib PackageReference. Keep AuthBlocksWeb.
DeepDrftManager/CLAUDE.md (doc-keeper, post-land) reflect Manager as web-auth-only. Not this plan's edit.
DeepDrftAPI/Program.cs Add AddAuthBlocks block reading Auth conn string + AuthBlocks:*. Add await app.Services.UseAuthBlocksStartupAsync() after Build(). Add app.MapAuthBlocks(). Add app.UseAuthentication()/UseAuthorization() if AuthBlocks endpoints require the auth middleware (verify — the ApiKey middleware is separate; see Q1.3).
DeepDrftAPI/DeepDrftAPI.csproj Add AuthBlocksLib PackageReference (match the version Manager used).
DeepDrftAPI/appsettings.json Add Manager's origin to CorsSettings.AllowedOrigins.
DeepDrftAPI/environment/connections.json Add the Auth connection string (gitignored; deployment + local).
DeepDrftAPI/environment/authblocks.json New: the JWT/email/admin secrets file (gitignored). Moved from Manager.
DeepDrftManager/environment/authblocks.json Remove, or reduce to the JWT-validation subset — see Q1.1.
*.example.json templates Update both hosts' example/templates to reflect the new shape (the Manager Program.cs header comment at lines 11–15 documents these; keep it accurate).

Migration path for secrets

authblocks.json today (Manager) carries: AuthBlocks:Jwt:{Secret,Issuer,Audience}, AuthBlocks:Email:{Host,Token}, AuthBlocks:Admin:{UserName,Email,Password}, AuthBlocks:SupportEmail.

  1. DeepDrftAPI gets the full file. It runs AddAuthBlocks + seed, so it needs all of it (JWT signing secret, email sender creds, admin seed creds). Place at DeepDrftAPI/environment/authblocks.json, loaded via CredentialTools.ResolvePathOrThrow exactly as Manager does today.
  2. The Auth connection string moves to DeepDrftAPI's connections.json. DeepDrftAPI already loads connections.json for DefaultConnection; add the Auth key alongside it. The Auth schema stays in its own database, separate from DefaultConnection, exactly as today.
  3. Manager's residual need is the open question — see Q1.1. The default position: Manager's ConfigureAuthServices is a client of the JWT (validates tokens read from browser localStorage, points its JWT client at the auth API base URL). If it needs the issuer/audience for client-side validation, Manager keeps a reduced authblocks.json with only the JWT validation subset (no signing secret, no email, no admin creds). If ConfigureAuthServices takes only a base URL (as the current call ConfigureAuthServices(services, baseUrl) suggests), Manager may need no authblocks.json at all. Engineering confirms against the AuthBlocksWeb API surface before deleting.

Open questions — resolved

Q1.1 — Does Manager still need any authblocks.json? Resolution: Default to "no signing secret, possibly a JWT-validation subset." The current ConfigureAuthServices(builder.Services, baseUrl) signature takes only a base URL, which strongly implies the web side does not need the signing secret. Engineering's first implementation step is to read the AuthBlocksWeb.Startup.ConfigureAuthServices signature and its downstream JWT client config: if it consumes AuthBlocks:Jwt:* from config, Manager keeps a reduced file with Issuer/Audience only; if it does not, Manager drops authblocks.json entirely. The signing secret (Jwt:Secret), email, and admin creds never stay on Manager. Capture the actual finding in the commit and update the Manager Program.cs header comment accordingly.

Q1.2 — Where do auth tokens get validated, given the Blazor circuit? Manager's existing comment (lines 145–155) documents that JWTs live in browser localStorage and never reach the Manager server on navigation — page authz is via AuthorizeRouteView, and the Manager API surface is AllowAnonymous at the endpoint layer. This is unchanged by the split. The browser holds the token and presents it to whichever API it calls. After the split, the auth issuing API is DeepDrftAPI, so the browser obtains its token from DeepDrftAPI's /api/auth/* and presents it to DeepDrftAPI's protected endpoints. Manager's job is only to host the login UI and the cascading auth-state provider that reads the stored token. No server-side token validation moves.

Q1.3 — Does DeepDrftAPI need UseAuthentication/UseAuthorization added? Resolution: Likely yes, and it must compose with the existing ApiKey middleware. DeepDrftAPI today authenticates track endpoints with a custom ApiKeyAuthenticationMiddleware (app.UseApiKeyAuthentication), not ASP.NET auth middleware. MapAuthBlocks mounts endpoints that expect JWT bearer auth, which requires app.UseAuthentication() + app.UseAuthorization() in the pipeline. Engineering adds these and verifies ordering: the ApiKey middleware must continue to gate only [ApiKeyAuthorize]-tagged track endpoints, and the JWT bearer scheme must gate the AuthBlocks endpoints — the two auth mechanisms coexist on one host. This is the highest-risk integration point in Workstream 1; flag for careful review. Confirm AddAuthBlocks registers the JWT bearer scheme (it does in Manager today, which is why Manager calls UseAuthentication).

Q1.4 — CORS. DeepDrftAPI's ContentApiPolicy already does AllowAnyMethod/Header/Credentials with specific origins. Add manage.deepdrft.com (prod) and the Manager's dev origin to CorsSettings.AllowedOrigins. Because the policy already AllowCredentials(), the cross-origin /api/auth/* flow (which may set cookies or carry the Authorization header) works without a new policy. No second CORS policy needed.

Workstream 2 — TrackManager / ITrackService cleanup

Current state

The defect: ITrackService returns TrackEntity everywhere (see DeepDrftData/ITrackService.cs), so the service layer leaks entities to its callers and TrackConverter is never reached on the read path. The layer boundary Daniel wants — repository → entity, service → DTO — is inverted in the current code: the converter exists but the entity-typed ITrackService surface bypasses it.

TrackManager : Manager<TrackEntity, TrackDto, TrackRepository, TrackConverter>, ITrackService. The BlazorBlocks Manager<> base (NuGet Cerebellum.BlazorBlocks.Data 10.3.30, namespace Data.Managers) exposes a DTO-shaped surface using TrackConverter (e.g. GetById → TrackDto). TrackManager also implements the entity-shaped ITrackService, bypassing the converter — these entity-typed methods are exactly what the new DTO-typed interface eliminates:

  • ITrackService.GetById — explicit impl (signature collides with base GetById → TrackDto).
  • GetAll, GetPaged, Create, Update — direct public methods hitting Repository and returning TrackEntity. These shadow/satisfy the entity interface and never touch the converter.
  • Delete(long) → Result — inherited from base; satisfies ITrackService.Delete by signature.

DeepDrftAPI consumers of ITrackService (entity-typed, converter-bypassing):

  • TrackController injects ITrackService _sqlTrackService; calls .GetPaged (GetPage endpoint), .GetById (GetMeta, and inside UpdateMeta), .Update (UpdateMeta). Returns raw TrackEntity / PagedResult<TrackEntity> over the wire.
  • UnifiedTrackService injects ITrackService; calls .Create(TrackEntity) (upload), .GetById(long) + .Delete(long) (delete orchestration).

Other consumers (out of DeepDrftAPI, in blast radius):

  • DeepDrftPublic — TrackDirectDataService.GetPaged, TrackController.GetPaged. Returns TrackEntity to its own client.
  • DeepDrftCli — CliService (Create, GetAll), GuiService (Create, Update, Delete, GetAll).

CmsTrackService (Manager, deserialization side) currently deserializes DeepDrftAPI responses as TrackEntity / PagedResult<TrackEntity>: ReadFromJsonAsync<TrackEntity> (upload at line 96, get-by-id at 229), ReadFromJsonAsync<PagedResult<TrackEntity>> (page at 180). Its ICmsTrackService public contract returns TrackEntity / PagedResult<TrackEntity> to the Blazor components.

Target state

Daniel's clarified rule (verbatim): "For workstream 2, ITrackService is where we need to output DTOs. The repository outputs entities, the Service outputs DTOs." This is a layer boundary, not a controller tweak:

  • TrackRepository → outputs TrackEntity (unchanged; it is the data-access layer).
  • ITrackService / TrackManager → outputs TrackDto for all query and mutation results, invoking TrackConverter internally. This is the change.

The new ITrackService shape:

public interface ITrackService
{
    Task<ResultContainer<TrackDto?>>             GetById(long id);
    Task<ResultContainer<List<TrackDto>>>        GetAll();
    Task<ResultContainer<PagedResult<TrackDto>>> GetPaged(int page, int pageSize, string? sortColumn, bool sortDescending, CancellationToken ct = default);
    Task<ResultContainer<TrackDto>>              Create(TrackDto newTrack);   // was Create(TrackEntity)
    Task<ResultContainer<TrackDto>>              Update(TrackDto track);      // was Update(TrackEntity)
    Task<Result>                                Delete(long id);             // unchanged
}

Consequences that fall out of this single rule:

  • The controller keeps injecting ITrackService and gets DTOs automatically. No change to which type it injects — only the endpoint response types change from TrackEntity to TrackDto. This is simpler than the prior plan (which had the controller switch to IManager<TrackEntity,TrackDto>).
  • UnifiedTrackService converts its unpersisted entity to a DTO before Create, and its UploadAsync now returns ResultContainer<TrackDto>.
  • CLI converts entity → DTO at its Create/Update call sites (it already builds entities), and its list/display collections bind TrackDto.
  • DeepDrftPublic — its TrackDirectDataService and own controller now receive PagedResult<TrackDto> from ITrackService, so its wire format to the WASM client changes accordingly. This was previously scoped out; it is now a decision point (Q2.3) — the rule applies system-wide, so the default is that Public aligns too.
  • CmsTrackService deserializes TrackDto / PagedResult<TrackDto> (unchanged from the prior plan).

Resolution of each design question

Q2.1 — ITrackService fate: change the interface to DTO return types. The direction is settled by Daniel's rule. It is neither "keep as-is" nor "split into two interfaces" — the three-direction exploration in the prior draft is retired. ITrackService stays as a single interface, owned by DeepDrftData, but its return types flip from TrackEntity to TrackDto (and its Create/Update inputs flip to TrackDto as well). This is the layer boundary Daniel stated: the repository is the entity surface; the service is the DTO surface; TrackConverter lives inside TrackManager and is the only place the conversion happens. Every consumer that previously received entities now receives DTOs and adjusts at its own boundary (controller: serialize the DTO; orchestration/CLI: convert their locally-built entities to DTOs before calling, and bind DTOs on the way back).

Q2.2 — TrackManager implementation. TrackManager : Manager<TrackEntity, TrackDto, TrackRepository, TrackConverter> — the BlazorBlocks base very likely already provides DTO-returning Create/Update/GetById/GetPaged that run TrackConverter. If so, the explicit entity-typed implementations currently in TrackManager.cs are removed in favor of the base-class DTO surface satisfying the new ITrackService:

  • ITrackService.GetById (the explicit interface impl, lines 37–48) — removed; base GetById → TrackDto now satisfies the interface directly (no signature collision once the interface is DTO-typed).
  • entity-typed GetAll (50–61), GetPaged (63–95), Create (97–108), Update (118–132) — removed in favor of the base DTO methods.
  • Delete(long) → Result — already inherited from the base; still satisfies the interface unchanged.

The one piece that must survive is the sort-column→expression mapping (the switch at TrackManager.GetPaged lines 77–86: TrackName/Artist/Album/Genre/ReleaseDate → OrderBy, nulls padded to end, default Id). This is product behavior, not boilerplate, and the base class may not carry it. Engineering's first step (B1) confirms against the Cerebellum.BlazorBlocks.Data 10.3.30 surface — which is not readable from this repo — whether the base paged method accepts a sort-column string and maps it, or only a pre-built PagingParameters<>:

  • If the base supports a sort-column string with a configurable mapping: configure the five columns there.
  • Otherwise: keep a DTO-returning GetPaged override on TrackManager that reuses the existing switch to build PagingParameters<TrackEntity>, calls Repository.GetPagedAsync, then converts the page to PagedResult<TrackDto> (per-item TrackConverter.Convert, or PagedResult.From<> — see the DeepDrftModels PagedResult.From<TOther> factory). Either way the switch stays in TrackManager.

This is the single most likely place Workstream 2 retains a hand-written method on TrackManager.

Q2.3 — Controller response types, and the DeepDrftPublic decision point. The controller keeps injecting ITrackService (no DI change in DeepDrftAPI's Program.cs for the track service). Because the interface is now DTO-typed:

  • GET api/track/page returns PagedResult<TrackDto>.
  • GET api/track/meta/{id} returns TrackDto.
  • PUT api/track/meta/{id} — the lookup now returns a TrackDto; the controller mutates the DTO's fields and passes the DTO to Update(TrackDto). EntryKey stays immutable (not in the request body).
  • POST api/track/upload — ActionResult<TrackEntity> becomes ActionResult<TrackDto> (see Q2.5).

On the Manager side, CmsTrackService deserializes TrackDto / PagedResult<TrackDto>, ICmsTrackService returns DTOs, and the Blazor components binding those results move from TrackEntity to TrackDto. Because TrackConverter mirrors the entity field-for-field, the JSON payload is identical — this is a type-level rename, not a payload change, so there is no serialization risk. Engineering enumerates the affected components by grepping the ICmsTrackService return types.

DeepDrftPublic — decision point. Under the prior plan Public was explicitly out of scope. Under Daniel's system-wide rule it is now in by default: TrackDirectDataService.GetPage and Public's own api/track/page controller call ITrackService.GetPaged, which now returns PagedResult<TrackDto>, so Public's ITrackDataService contract and its WASM client deserialization move from TrackEntity to TrackDto. The payload is again identical (converter mirrors the entity). Flagged for Daniel:

The brief's clarification names "the Service" generically, which means DeepDrftPublic's consumption of ITrackService is also affected — its public wire format would move to TrackDto. Recommended: align Public in the same pass (the change is mechanical and the payload is unchanged), so the layer rule holds uniformly and there is no lingering entity-on-the-wire path. If Daniel wants Public's wire deferred, the only way to keep it on entities is to convert TrackDto → TrackEntity at Public's own boundary (TrackDirectDataService and controller) — extra work to preserve the old shape, and a conversion in the wrong direction. Default: align Public.

Q2.4 — UnifiedTrackService. UnifiedTrackService.UploadAsync builds an unpersisted TrackEntity (from TrackContentService.AddTrackFromWavAsync), sets CreatedByUserId, then calls ITrackService.Create. Because Create now takes a TrackDto, it converts first:

unpersisted.CreatedByUserId = createdByUserId;
var dto = TrackConverter.Convert(unpersisted);          // entity → DTO
var saveResult = await _sqlTrackService.Create(dto);    // returns ResultContainer<TrackDto>
// saveResult.Value is a TrackDto with Id populated

UploadAsync's return type changes from ResultContainer<TrackEntity> to ResultContainer<TrackDto> — the controller serializes it as-is, so no second conversion is needed. The orphan-logging path is unchanged (it reads EntryKey, present on the DTO). DeleteAsync already only needs GetById (now returns TrackDto?, still carries EntryKey) and Delete(long) (unchanged) — its logic is untouched beyond the EntryKey source being a DTO.

Q2.5 — UploadTrack response type. With UnifiedTrackService.UploadAsync returning ResultContainer<TrackDto>, the controller's UploadTrack action returns the DTO directly: ActionResult<TrackEntity> → ActionResult<TrackDto>, and return Ok(result.Value) already serializes the DTO. CmsTrackService.UploadTrackAsync deserializes TrackDto; ICmsTrackService.UploadTrackAsync returns ResultContainer<TrackDto>. The upload caller in the Manager component uses Id, EntryKey, etc. — all present on the DTO.

Q2.6 — CLI change. CliService and GuiService (in DeepDrftCli) consume ITrackService directly: .Create(entity), .Update(entity), .GetAll(), .Delete(id). After the change:

  • Create (CliService.HandleAddCommand ~line 168, GuiService.ValidateAndAddTrackAsync ~line 654): both build a TrackEntity via TrackContentService.AddTrackFromWavAsync, then call Create. They must convert to DTO first — TrackConverter.Convert(trackEntity) — and read result.Value as a TrackDto (the displayed Id, TrackName, Artist, Album, Genre, ReleaseDate, EntryKey are all on the DTO).
  • Update (GuiService.ValidateAndUpdateTrackAsync ~line 712): builds an updated TrackEntity, calls Update. Convert to DTO before the call. Note GuiService constructs the entity by hand here; it could equally construct a TrackDto directly — engineering picks whichever is cleaner given the surrounding code, but TrackConverter.Convert keeps the call sites uniform.
  • GetAll / display (CliService.HandleListCommand, GuiService.RefreshTrackListAsync, _tracks field, DeleteTrackAsync/ShowEditTrackDialog/ShowTrackDetails selected-track handling): GetAll() now returns List<TrackDto>, so GuiService._tracks becomes List<TrackDto> and every display/selection site binds TrackDto. Field access is identical (same property names), so this is a type-declaration change, not a logic change. TrackConverter and TrackDto are already in DeepDrftData / DeepDrftModels, both referenced by the CLI — no new dependency.

The CLI is a deliberate local entity-space admin tool, but the entity now lives only between AddTrackFromWavAsync and the TrackConverter.Convert call; everything it reads back from the service is a DTO. This is consistent with the layer rule.

Q2.7 — PutTrack endpoint. No change. It writes AudioBinaryDto straight to FileDatabase and never touches ITrackService/TrackManager. Confirmed by reading the controller (lines 352–373).

Files touched (Workstream 2)

File Change
DeepDrftData/ITrackService.cs Signature change — all return types TrackEntity→TrackDto; Create/Update inputs TrackEntity→TrackDto; Delete(long) unchanged. Update doc comment to state the layer rule (repository → entity, service → DTO).
DeepDrftData/TrackManager.cs Remove the entity-typed ITrackService implementations (explicit GetById, and GetAll/GetPaged/Create/Update) in favor of the base-class DTO surface satisfying the DTO-typed interface. Preserve the sort-column→expression switch (lines 77–86): keep a DTO-returning GetPaged override that reuses it iff the base can't carry the mapping (B1 decides). Update the class doc comment — the dual-surface note is obsolete once there is one DTO surface.
DeepDrftAPI/Program.cs No change to the track-service registration — AddScoped<ITrackService>(sp => sp.GetRequiredService<TrackManager>()) stays; the controller keeps injecting ITrackService and now gets DTOs.
DeepDrftAPI/Controllers/TrackController.cs Keep injecting ITrackService. GetPage returns PagedResult<TrackDto>; GetMeta returns TrackDto; UpdateMeta mutates the looked-up TrackDto and calls Update(TrackDto); UploadTrack returns the DTO from UnifiedTrackService — ActionResult<TrackEntity> → ActionResult<TrackDto>.
DeepDrftAPI/Services/UnifiedTrackService.cs UploadAsync converts the unpersisted entity via TrackConverter.Convert before Create(dto); return type ResultContainer<TrackEntity> → ResultContainer<TrackDto>. DeleteAsync reads EntryKey off the TrackDto? lookup (logic otherwise unchanged).
DeepDrftManager/Services/CmsTrackService.cs Deserialize TrackDto / PagedResult<TrackDto> instead of entity.
DeepDrftManager/Services/ICmsTrackService.cs Return types TrackEntity→TrackDto, PagedResult<TrackEntity>→PagedResult<TrackDto>.
DeepDrftManager/Components/Pages/** (Tracks/Cms) Components binding ICmsTrackService results move from TrackEntity to TrackDto. Enumerate via grep before editing.
DeepDrftCli/Services/CliService.cs Create call site converts entity → TrackDto (TrackConverter.Convert); GetAll/list display binds TrackDto. Field access unchanged.
DeepDrftCli/Services/GuiService.cs Create/Update call sites convert to TrackDto; _tracks field and all display/selection sites bind TrackDto. Field access unchanged.
DeepDrftPublic/Services/TrackDirectDataService.cs, DeepDrftPublic/Controllers/TrackController.cs, Public's ITrackDataService + WASM client Decision point (Q2.3). Default: align to PagedResult<TrackDto> (mechanical; payload identical). If Daniel defers Public, these instead convert TrackDto → TrackEntity at Public's boundary to preserve the old wire shape.
DeepDrftData/CLAUDE.md, DeepDrftAPI/CLAUDE.md, DeepDrftCli/CLAUDE.md, DeepDrftPublic/CLAUDE.md (doc-keeper, post-land) folder docs that describe ITrackService / endpoints returning TrackEntity become DTO. Not this plan's edit.

Wave plan

Two workstreams are independent and can run in parallel (different files, no shared edits except both touch DeepDrftAPI/Program.cs — sequence those two edits or merge carefully). Within each workstream, tracks are ordered.

Wave A — AuthBlocks separation (Workstream 1)

  • A1 (sequential, first): Read AuthBlocksWeb.Startup.ConfigureAuthServices + AddAuthBlocks signatures from the AuthBlocksLib/AuthBlocksWeb packages. Resolve Q1.1 (Manager's residual authblocks.json) and Q1.3 (auth-middleware ordering) against the real API. Output: a one-paragraph confirmation appended to this section by engineering before code.
  • A2 (after A1): DeepDrftAPI gains AuthBlocks: csproj reference, AddAuthBlocks, secrets files (authblocks.json + Auth conn string), UseAuthBlocksStartupAsync, MapAuthBlocks, UseAuthentication/UseAuthorization, CORS origin. Verify ApiKey + JWT middleware coexist.
  • A3 (after A2, can overlap A2 tail): Manager loses AuthBlocks: remove AddAuthBlocks/seed/map, drop AuthBlocksLib csproj ref, reduce/remove authblocks.json per A1 finding. Keep ConfigureAuthServices.
  • A4 (after A2 + A3): End-to-end auth smoke: login from Manager UI obtains a token from DeepDrftAPI's /api/auth/*, protected DeepDrftAPI endpoints accept it, admin seed ran on DeepDrftAPI first boot.

Wave B — TrackManager / ITrackService (Workstream 2)

  • B1 (sequential, first): Read the Cerebellum.BlazorBlocks.Data 10.3.30 Manager/IManager surface. Resolve Q2.2 — does the base provide DTO Create/Update/GetById/GetPaged, and does its paged method carry the sort-column→expression mapping or must TrackManager keep a GetPaged override for it? Output: confirmation appended here before code.
  • B2 (after B1): DeepDrftData — flip ITrackService to DTO return/input types; remove the entity-typed TrackManager implementations in favor of the base DTO surface; keep the sort switch (as a GetPaged override if B1 requires it). This is the load-bearing edit — every B-track below depends on it compiling.
  • B3 (after B2): DeepDrftAPI — UnifiedTrackService.UploadAsync converts to DTO before Create and returns ResultContainer<TrackDto>; controller endpoints return DTOs; UploadTrack returns ActionResult<TrackDto>. No Program.cs DI change for the track service.
  • B4 (after B2): DeepDrftCli — convert at Create/Update call sites; GetAll/display bind TrackDto. Independent of B3 (different project), gated only on B2's interface change.
  • B5 (after B3): Manager — CmsTrackService + ICmsTrackService + consuming components move to TrackDto. The largest single track by file count.
  • B6 (after B2, decision-gated): DeepDrftPublic — align TrackDirectDataService, controller, ITrackDataService, and the WASM client to TrackDto (Q2.3 default), or add the TrackDto→TrackEntity conversion at Public's boundary if Daniel defers the public wire. Gated on Daniel's Q2.3 decision before it starts.
  • B7 (after B3 + B5): CMS smoke: track browser lists, edit saves, upload returns the new row, delete works — all through the DTO wire.

Parallelism

  • Wave A and Wave B run in parallel by different engineers. Wave A touches DeepDrftAPI/Program.cs (auth wiring); Wave B no longer touches Program.cs for the track service (the DI registration is unchanged), so the two waves now have no shared file — conflict risk is effectively zero. (Wave B does touch DeepDrftAPI in the controller and UnifiedTrackService, but not Program.cs.)
  • A1 and B1 (the package-surface reads) can both happen up front, in parallel, before any code.
  • Within Wave B, B2 is the gate: the interface flip must land first; B3/B4/B5/B6 fan out from it across DeepDrftAPI, DeepDrftCli, DeepDrftManager, and (decision-gated) DeepDrftPublic — they can run in parallel once B2 compiles, since they are different projects. This is the real cost of the layer-rule change: it is not a single-controller edit but a fan-out to every ITrackService consumer. DeepDrftPublic and CLI are in scope now (they were not in the prior draft).

Acceptance criteria

Workstream 1

  • DeepDrftManager builds without referencing AuthBlocksLib (only AuthBlocksWeb).
  • DeepDrftManager's Program.cs contains no AddAuthBlocks, UseAuthBlocksStartupAsync, or MapAuthBlocks call; it retains ConfigureAuthServices.
  • DeepDrftAPI references AuthBlocksLib, runs AddAuthBlocks + UseAuthBlocksStartupAsync on startup, and mounts /api/auth/* + /api/users/* via MapAuthBlocks.
  • On first boot against an empty Auth database, DeepDrftAPI applies AuthBlocks EF migrations and seeds roles + the admin user.
  • The signing secret, email creds, and admin creds exist only in DeepDrftAPI's environment/, never in Manager's.
  • DeepDrftAPI's CORS policy includes the Manager origin; a browser served by Manager can call DeepDrftAPI /api/auth/* without a CORS rejection.
  • ApiKey-protected track endpoints on DeepDrftAPI still enforce the ApiKey; AuthBlocks endpoints enforce JWT — neither auth path interferes with the other.

Workstream 2

  • ITrackService returns TrackDto for all queries and Create/Update; Create/Update take TrackDto; Delete(long) is unchanged. TrackRepository still returns entities.
  • TrackManager no longer has entity-typed ITrackService methods; the DTO surface (base class + any retained GetPaged override) satisfies the interface, and TrackConverter runs inside it.
  • GET api/track/page, GET api/track/meta/{id}, PUT api/track/meta/{id}, and POST api/track/upload produce DTOs (no raw TrackEntity crosses the wire from DeepDrftAPI).
  • CmsTrackService deserializes DTOs; ICmsTrackService and its consuming components are DTO-typed; the CMS track browser, edit, upload, and delete flows work unchanged from the user's view.
  • UnifiedTrackService.UploadAsync returns ResultContainer<TrackDto> and converts the unpersisted entity to a DTO via TrackConverter before Create.
  • DeepDrftCli compiles against the DTO interface: add/edit convert at the call site, list/display bind TrackDto, behavior is unchanged from the user's view.
  • DeepDrftPublic: per the Q2.3 decision — either its wire format is PagedResult<TrackDto> (default) or it converts at its own boundary to keep the existing shape. Either way the public gallery loads identically.
  • TrackConverter is the single entity↔DTO conversion path; it lives inside TrackManager / UnifiedTrackService, not at scattered controller or page call sites.

Test cases

Workstream 1

  1. Cold-start seed. Point DeepDrftAPI at an empty Auth DB, boot. Verify migrations applied, system roles present, admin user created with the seeded creds.
  2. Idempotent re-boot. Boot DeepDrftAPI a second time against the seeded DB. No duplicate admin, no migration error.
  3. Login round-trip. From Manager's login page, authenticate against DeepDrftAPI /api/auth/*; confirm a JWT is issued and stored client-side.
  4. Protected DeepDrftAPI endpoint with JWT. Call an AuthBlocks-protected endpoint with the issued token → 200; without it → 401.
  5. ApiKey endpoints unaffected. GET api/track/page with a valid ApiKey → 200; with none → 401. Confirm the JWT middleware does not start rejecting ApiKey-only requests.
  6. CORS preflight. Browser OPTIONS preflight from the Manager origin to DeepDrftAPI /api/auth/* returns the allow headers; a disallowed origin is rejected.
  7. Manager has no secrets. Grep Manager's deployed environment/ — no signing secret / admin password present.

Workstream 2

  1. Page endpoint shape. GET api/track/page returns PagedResult<TrackDto> JSON; Items carry the same field values as before (compare a row against its TrackEntity pre-change).
  2. Sort preserved. Each supported sortColumn (TrackName, Artist, Album, Genre, ReleaseDate) and sortDescending produce the same ordering as before the change — proves the sort-column→ expression mapping survived the move to the DTO path.
  3. Get-meta shape. GET api/track/meta/{id} returns TrackDto; 404 for a missing id; 500 path on a forced query error still returns 500.
  4. Update round-trip. PUT api/track/meta/{id} updates fields, clears optionals on null, leaves EntryKey immutable; subsequent get reflects the change.
  5. Upload returns DTO with Id. POST api/track/upload returns TrackDto with Id > 0 and the correct EntryKey; the CMS upload flow reads back the new row.
  6. CMS browser/edit/delete. Through the Manager UI: list paginates and sorts, edit saves, delete removes the row and the vault entry, upload adds a row — all against DTO responses.
  7. Public behaves identically. DeepDrftPublic's gallery loads and paginates the same as before, whichever Q2.3 branch was taken (DTO wire by default, or boundary conversion if deferred). Payload values match a pre-change capture.
  8. CLI behavior unchanged. DeepDrftCli list / add / GUI add+edit+delete operate the same from the user's view; the displayed fields (Id, Name, Artist, Album, Genre, ReleaseDate, EntryKey) are correct, now sourced from TrackDto.
  9. Converter is the only path. Confirm (by inspection/coverage) no DeepDrftAPI metadata response serializes a TrackEntity directly, and the conversion happens inside TrackManager / UnifiedTrackService, not in a controller or Razor component.

Risks / trade-offs

  • Highest risk (W1): ApiKey + JWT middleware coexistence on one host (Q1.3). If misordered, one auth scheme can short-circuit the other. Needs deliberate review and test cases 4–5.
  • Highest cost (W2): the consumer fan-out from B2, not the interface edit itself. Flipping ITrackService to DTO is a small file; the cost is that every consumer changes — DeepDrftAPI controller + UnifiedTrackService, DeepDrftCli (two services), DeepDrftManager (CmsTrackService
    • components), and DeepDrftPublic (decision-gated). Payload is identical field-for-field, so there is no runtime serialization risk, but the breadth is the real budget. This is a larger blast radius than the prior draft, which kept CLI and Public out — Daniel's system-wide rule pulls them in.
  • The sort switch is the one piece of real logic at risk (B1/B2). Everything else is a type rename; the sort-column→expression mapping is product behavior that must not be lost in the move to the DTO path. Test case W2-2 exists specifically to guard it.
  • Unknown until B1/A1: the BlazorBlocks Manager/IManager surface and the AuthBlocks package signatures are not readable from this repo. Both waves open with a package-surface read. For W2 the open question is narrow: does the base DTO GetPaged carry a configurable sort mapping, or must TrackManager keep a GetPaged override? The plan holds either way.
  • Open decision (W2): whether DeepDrftPublic's public wire format moves to TrackDto (default, recommended) or stays TrackEntity via a boundary conversion (Q2.3). B6 is gated on Daniel's call; the rest of Wave B does not depend on it.
Reference in New Issue View Git Blame Copy Permalink