Files

T

daniel-c-harvey d96c41eafb docs: reconcile PLAN.md and CONTEXT.md with post-split solution state

2026-06-06 15:27:14 -04:00

21 KiB

Raw Blame History

DeepDrftHome — Project Context

Living orientation doc for what this repo is, how it is currently shaped, and where it appears headed. Sits alongside the root CLAUDE.md (operational guidance) — this file is the product/architecture view.

Status. The root CLAUDE.md is current — it reflects the post-split ten-project solution, net10.0, and the dual-app topology. This file (CONTEXT.md) was the lagging document and §2 / §4 / §7 below have been brought back into line with the root CLAUDE.md as of 2026-06-06. Folder-level CLAUDE.md files are still being swept (DOC_PLAN.md); treat framework-version and structural claims in any folder CLAUDE.md not yet rewritten as potentially stale until that sweep lands.

1. What this project is

DeepDrftHome is the home + listening surface for DeepDrft, a two-person electronic music collective based in Charleston, SC (per DeepDrftPublic.Client/Pages/Home.razor). The product is, at minimum:

A public-facing site (hero, about, "experience" features) at DeepDrftPublic.
A track gallery that browses a library of WAV recordings, plays them in-browser with a persistent dock-style player, and supports seek (including seek beyond what's been streamed so far).
A browser-based CMS (DeepDrftManager) for adding, editing, and deleting tracks — gated behind AuthBlocks login and the Admin role. This replaced the former DeepDrftCli Terminal.Gui admin tool, which has been retired.

The interesting engineering bet is the dual-database split: structured track metadata in PostgreSQL via EF Core, and binary media + per-vault indexes in a hand-rolled FileDatabase that lives on disk. The split is enforced through a dedicated authority host (DeepDrftAPI) so that the browser never reaches the database directly.

2. Solution shape (current)

Ten projects in DeepDrftHome.sln, plus an external NetBlocks referenced from C:\lib\NetBlocks\. The solution is split into two independent Blazor applications — the public site (DeepDrftPublic) and the CMS (DeepDrftManager) — both fronting a single dual-database authority host (DeepDrftAPI).

── Public application ──────────────────────────────────────────────────────
DeepDrftPublic              ASP.NET Core host. Blazor Web App (Server + WASM render
                            modes). Owns the browser-facing proxy controller for
                            api/track/* (metadata listing + audio streaming),
                            MudBlazor theme prerender, and TypeScript→JS audio interop
                            sources under Interop/. The public listening surface.
DeepDrftPublic.Client       Blazor WebAssembly assembly. All interactive public UI —
                            pages, the player stack, dark-mode plumbing, HTTP clients
                            for the backend. Consumed by DeepDrftPublic.

── CMS application ─────────────────────────────────────────────────────────
DeepDrftManager             ASP.NET Core host. Blazor Web App (InteractiveServer).
                            Hosts all CMS Razor components/pages (Components/Pages/Cms/,
                            Components/Pages/Tracks/, Components/Layout/CmsLayout.razor,
                            Components/Shared/ — inlined from the former DeepDrftCms RCL).
                            Gated by AuthBlocks login + hierarchical Admin role. All track
                            operations proxy via ICmsTrackService / CmsTrackService.

── Dual-database authority ─────────────────────────────────────────────────
DeepDrftAPI                 ASP.NET Core host. The single authority over both databases
                            (SQL metadata + FileDatabase binary). AuthBlocks API host
                            (registration, migration/seed, JWT endpoints). Seven track
                            endpoints (stream, vault write, upload, delete, paged list,
                            single metadata read, metadata update).
DeepDrftData                Class library. EF Core domain logic: DeepDrftContext,
                            TrackConfiguration, Migrations, TrackRepository, TrackService,
                            TrackManager. Consumed by DeepDrftAPI and tests.
DeepDrftContent             Class library. The FileDatabase implementation in full
                            (Models, Services, Utils, Abstractions, Constants),
                            WavOffsetService, AudioProcessor, content-side TrackService.
                            Consumed by hosts and tests.

── Shared ──────────────────────────────────────────────────────────────────
DeepDrftShared.Client       Razor Class Library. Shared Blazor components consumed by
                            BOTH DeepDrftPublic and DeepDrftManager (e.g. TrackCard,
                            TracksGallery) for consistency across public and admin surfaces.
DeepDrftModels              Shared contracts: TrackEntity, TrackDto, PagingParameters<T>,
                            PagedResult<T>, plus waveform DTOs. Every project references this.
DeepDrftTests               NUnit. Covers the FileDatabase, MediaVault, IndexSystem,
                            MediaVaultFactory, SimpleMediaTypeRegistry, utility code, model
                            behaviour, and the waveform loudness algorithm. References
                            DeepDrftContent.

NetBlocks (external)        Result patterns: Result, ResultContainer<T>, ApiResult<T>,
                            ApiResultDto<T>. Referenced via absolute path.

Naming history (for readers of older docs/commits): DeepDrftWeb → DeepDrftPublic, DeepDrftWeb.Client → DeepDrftPublic.Client, DeepDrftWeb.Services → DeepDrftData, DeepDrftContent.Services → DeepDrftContent (the host that previously owned the binary API is gone; its proxy duties moved into DeepDrftPublic, its authority duties into DeepDrftAPI). DeepDrftCli and the DeepDrftCms RCL have both been removed — the CLI retired in favour of the CMS, and the CMS RCL was inlined into DeepDrftManager.

Subdomain topology (deployment): deepdrft.com (public) and manage.deepdrft.com (CMS), behind nginx. CD infrastructure (Gitea workflows + installer scripts + systemd/nginx templates) has landed — see COMPLETED.md "Deployment Infrastructure."

3. Architectural decisions worth remembering

3.1 Dual-database, two hosts, one client

The system is partitioned so the browser never touches storage directly:

DeepDrftWeb.Client (WASM)
    │
    ├── HttpClient "DeepDrft.API"     ──►  DeepDrftWeb host   ──►  EF Core / SQLite
    │   (paged track metadata)
    │
    └── HttpClient "DeepDrft.Content" ──►  DeepDrftContent    ──►  FileDatabase / disk
        (audio bytes + offset stream)      (ApiKey required for PUT)

The two HttpClients are named, configured in DeepDrftWeb.Client.Startup, and base addresses are passed in from server-host configuration (ApiUrls:ContentApi). Read endpoints in DeepDrftContent (GET api/track/{id}) are unauthenticated — only mutating endpoints carry [ApiKeyAuthorize]. CORS is enforced per CorsSettings.AllowedOrigins.

3.2 Service projects vs. host projects

The split between DeepDrftWeb / DeepDrftWeb.Services (and the same for Content) is deliberate: the host projects own the HTTP surface, configuration, and DI wiring, while the Services projects are plain class libraries holding the domain logic. This is what lets DeepDrftCli reuse both DeepDrftWeb.Services.TrackService and DeepDrftContent.Services.TrackService without taking a dependency on either ASP.NET host. New domain logic should land in the *.Services projects unless it is genuinely host-specific (controllers, middleware, render-mode configuration, theme prerender).

3.3 FileDatabase as a first-class subsystem

The FileDatabase (in DeepDrftContent.Services/FileDatabase/) is the unusual piece. It is a port of a TypeScript system (see in-tree FileDatabase/README.md) and is the only place binary content lives.

A FileDatabase is a directory containing typed MediaVaults.
Each MediaVault has its own JSON index file that lists entries and their per-entry metadata.
Vaults are typed via MediaVaultType (Media | Image | Audio). The vault type is recorded in VaultIndex and rehydrated on startup.
Entry keys are user-supplied strings, sanitised to [a-zA-Z0-9] plus - and concatenated with the file extension to produce on-disk filenames.
Resources implement a binary hierarchy: FileBinary → MediaBinary (+ Extension/MIME) → AudioBinary (+ Duration, Bitrate) | ImageBinary (+ AspectRatio). DTO variants ship as base64-over-JSON.
An IndexWatcher (FileSystemWatcher) reloads a vault's index when an external process (e.g. the CLI) writes to it, so the web host stays consistent without restart.
Error-handling philosophy: load/register operations swallow exceptions and return null/false to match the TypeScript original. Callers must check return values, not catch.

The only authorised callers of FileDatabase APIs are the DeepDrftContent host and the CLI — anything that runs in the browser must go through the HTTP endpoints.

3.4 TrackEntity is a join, not a content blob

TrackEntity (in DeepDrftModels) holds only metadata. The link to binary content is the EntryKey string, which is the entry id inside the tracks audio vault in the FileDatabase. The current schema:

public class TrackEntity
{
    public long Id { get; set; }
    public required string EntryKey { get; set; }   // FileDatabase entry id, vault = "tracks"
    public required string TrackName { get; set; }
    public required string Artist { get; set; }
    public string? Album { get; set; }
    public string? Genre { get; set; }
    public DateOnly? ReleaseDate { get; set; }
    public string? ImagePath { get; set; }
}

Note: many existing docs (every folder CLAUDE.md, plus the FileDatabase README) still refer to the older MediaPath name. The migration 20250904233927_Initial.cs already ships the entry_key column, so MediaPath is purely a docs-staleness artefact.

3.5 Streaming-first audio playback

The player is not a fetch-then-play model. The flow is:

Client calls GET api/track/{id} on DeepDrftContent and receives the WAV bytes as a stream (HttpCompletionOption.ResponseHeadersRead).
StreamingAudioPlayerService reads the stream in adaptive 16–64 KB chunks and pushes each chunk into JS via AudioInteropService.processStreamingChunk.
The TypeScript StreamDecoder parses the WAV header, decodes chunks to AudioBuffers, and the PlaybackScheduler schedules them on a single Web Audio graph.
Playback starts as soon as a configurable minimum number of buffers is queued; UI duration is set from the parsed WAV header (not waiting for the full file).
Seek beyond buffer: if a seek target is past what's been decoded, the client issues a new GET api/track/{id}?offset={byteOffset} request. The server's WavOffsetService block-aligns the offset, synthesises a fresh 44-byte WAV header sized for the remaining data, and streams [new header][data from offset]. The player tears down and re-initialises its decoder for the new stream.

This is the seam where the FileDatabase's "everything is a complete blob in memory" model meets the browser's "I need to stream and seek" model. Keep this seam clean — it is the most architecturally load-bearing part of the playback path.

3.6 Theming, dark mode, and prerender

MudBlazor is the UI framework. Light and dark palettes are bespoke ("Charleston in the Day" / "Lowcountry Summer Nights") and defined inline in MainLayout.razor.
Dark mode toggles via a long-lived cookie (darkMode, 365 days), set client-side via JS interop.
During server prerender, DarkModeService (in DeepDrftWeb) reads the cookie and seeds DarkModeSettings.IsDarkMode, which carries the value into the WASM render via PersistentComponentState. This is what avoids a "wrong theme flash" on initial paint. The DarkModeSettings lives in DeepDrftWeb.Client.Common because it is consumed by both the server DarkModeService and client components.
Typography uses three Google Fonts (Bodoni Moda, Cormorant, DM Sans). The hand-rolled gas-lamp icon (lit/unlit) lives in DDIcons.cs and is what swaps in the dark-mode toggle.

3.7 TypeScript interop, not raw JS

The audio interop is authored in TypeScript under DeepDrftWeb/Interop/audio/ and compiled into wwwroot/js/audio/ via Microsoft.TypeScript.MSBuild. The split is intentional: AudioContextManager / StreamDecoder / PlaybackScheduler / SpectrumAnalyzer / AudioPlayer are each their own module, and index.ts glues them onto window.DeepDrftAudio for Blazor to invoke. The tsconfig.json is configured for ES module interop and is not copied to output.

In dev, the host serves the original .ts sources at /Interop/... for source-map debugging.

4. Where the system is today

Recent commits (newest first):

docs: archive play-state icon normalization; update DeepDrftPublic.Client CLAUDE.md
Consolidate play/pause icon logic into PlaybackIcons mapper and PlayStateIcon component
Reflect real playback state on gallery cards and toggle pause/resume
WASM State Fixes
CMS Home autoredirect to /tracks
WaveformSeeker Improvements / WaveformSeeker waves 1–3
(earlier: AudioPlayerBar responsive unification, CMS build-out, the two-app split, deployment infrastructure)

Observations:

The big structural moves have landed. Since the last revision of this doc, three large initiatives shipped: the two-app split (public/CMS separation with DeepDrftAPI as the dual-database authority), the browser CMS replacing the CLI (auth via AuthBlocks, stealth-routed /cms/*, full add/list/edit/delete parity), and CD infrastructure (Gitea workflows + host installer + systemd/nginx templates). The substrate is no longer the frontier — the product and presentation layers are.
The recent arc is player UX polish. The latest wave of work is the WaveformSeeker (loudness-profile seekbar), AudioPlayerBar responsive unification, and play-state icon normalization (a single PlaybackIcons resolver + PlayStateIcon component, gallery cards reflecting real playback state with pause/resume). Presentation iteration on a stable streaming core.
The "Track Gallery" is still the only real public content page. /tracks is the working listening surface; / is the (reskinned) marketing home. Nav (in Layout/Pages.cs) is still essentially Home + Track Gallery. The CMS adds admin surfaces under /cms but those are not public.
The metadata/streaming surface is consolidated on DeepDrftAPI. It exposes seven track endpoints (stream, vault write, upload, delete, paged list, single-metadata read, metadata update) plus waveform endpoints. DeepDrftPublic is a thin browser-facing proxy in front of it; the browser never reaches DeepDrftAPI or the databases directly.
In flight (working tree, not yet committed): an embeddable iframe player (EmbedLayout.razor, FramePlayer.razor, a new ITrackDataService seam) — a chrome-free single-track play surface for embedding off-site. Partial and not yet compiling; see PLAN.md "In-flight — Embeddable iframe player" for the open questions.

5. Likely directions (inferred, not committed)

Captured here so the next round of planning has a starting point — none of this is decided.

More vault types in active use. MediaVaultType.Image exists end-to-end (tests cover it) but the production surface only registers a tracks vault of type Audio. The path to releases/albums probably runs through images first (cover art via ImagePath, which is currently a free-form URL string).
More than one collection view. The TrackCard already conditionally renders ImagePath, Album, Genre, ReleaseDate — the data shape supports album-grouped or genre-filtered views without schema work.
Web upload — landed. (Historical note: this was a "likely direction" when the CLI was the only producer. It has since shipped.) The CMS (DeepDrftManager) now produces tracks via POST api/track/upload on DeepDrftAPI, proxied through the auth-gated CMS surface. The CLI has been retired. The dual-write rollback gap (PLAN.md §4.3) still stands.
Live/session content. The home page advertises "Live Sessions" and "Video Content (coming soon)". No data model exists for these yet; they would likely need new vault types (MediaVaultType.Media is the obvious home for video) and new entity tables.
Non-WAV formats. Today the producer side is WAV-only (AudioProcessor.ProcessWavFileAsync validates RIFF/WAVE/PCM). MimeTypeExtensions already knows mp3/flac/aac/ogg/m4a — the gap is a processor per format and a decoder strategy in the JS player (currently WAV-specific).
Search / filter on the gallery. TracksViewModel exposes SortBy / IsDescending but no filter. TrackService.GetPaged accepts only sort, not filter. Adding filter would be a natural next step on the same pagination contract.

6. Conventions that should hold

Plan docs at the repo root. CONTEXT.md (this file), and when work in flight warrants them, PLAN.md / TODO.md / COMPLETED.md. Completed PLAN.md items move to COMPLETED.md rather than being deleted.
*.Services libraries own domain logic. Host projects only do HTTP/wiring/render concerns. New repositories, services, processors, and storage code go in DeepDrftWeb.Services or DeepDrftContent.Services.
Shared contracts in DeepDrftModels only. If a type crosses a project boundary, it lives in DeepDrftModels. Project-specific DTOs (e.g. AudioBinaryDto for the content API) stay local to where they serialise.
No direct DB from network clients. The browser must not import EF or speak to SQLite. All access goes through the two API hosts. (The CLI is allowed direct DB access because it is not a network client.)
One source of truth per concept, multiple views over it. The dark-mode flow (cookie → DarkModeSettings → server DarkModeService for prerender + client DarkModeCookieService for runtime + persistent state across the boundary) is a small example of this: one truth, distinct rendering paths. New view modes for tracks should consume the same TrackEntity / PagedResult<TrackEntity> and differ only at the rendering layer.
Result types from NetBlocks. Services return Result, ResultContainer<T>, or ApiResult<T> rather than throwing for expected failure modes. Catch at the service boundary, surface via the result.

7. Staleness in existing docs (for doc-keeper to address)

Two layers of drift remain. The root CLAUDE.md and this CONTEXT.md are current; the lag is now in folder-level CLAUDE.md files and the in-tree FileDatabase README. DOC_PLAN.md holds the per-folder rewrite briefs, but note that DOC_PLAN.md itself was authored against the pre-split project names (2026-05-16) and is partly superseded — see the warning at the end of this section.

Project-rename drift (the big one). The two-app split renamed or removed most projects. Any folder CLAUDE.md still using the old names is wrong at the structural level, not just the framework-version level:

DeepDrftWeb → DeepDrftPublic; DeepDrftWeb.Client → DeepDrftPublic.Client; DeepDrftWeb.Services → DeepDrftData.
DeepDrftContent.Services (class library) is now just DeepDrftContent; the old DeepDrftContent host is gone — binary-API duties split between the DeepDrftPublic proxy and the DeepDrftAPI authority.
DeepDrftCli and the DeepDrftCms RCL are deleted. Any CLAUDE.md for them should be removed, not rewritten.

Known content drift to correct in the sweep:

Framework version: any folder CLAUDE.md still saying ".NET 9" / "ASP.NET Core 9.0" — reality is net10.0 across the board.
TrackEntity.MediaPath references (notably the FileDatabase/README.md) — the field is EntryKey, column entry_key.
The FileDatabase/README.md refers to ImageDirectoryVault (the type is ImageVault) and a "FileDatabase.csproj (.NET 9.0)" that no longer exists (FileDatabase is a subdirectory of DeepDrftContent).
DeepDrftData and DeepDrftContent are where most domain logic lives and are the highest-value targets for accurate CLAUDE.md coverage.

Already corrected (no longer stale):

DeepDrftPublic.Client/CLAUDE.md was rewritten in commit 9110b4b and reflects the current player stack, PlaybackIcons/PlayStateIcon, and the post-split structure.

DOC_PLAN.md caveat. DOC_PLAN.md predates the two-app split — its per-folder briefs reference DeepDrftWeb*, DeepDrftCli, and a SQLite backend (now PostgreSQL). Treat its intent (lead-with-truth, cross-reference root, no docs for build output) as still valid, but its project list and per-folder details need reconciling against the current ten-project solution before doc-keeper executes against it. Flag to Daniel whether to refresh DOC_PLAN.md first or let doc-keeper work from the root CLAUDE.md directly.

21 KiB Raw Blame History Unescape Escape