Admin process — current architecture and proposed improvements
2026-10-21 status update: Read the current implementation review for as-built behavior. Since this proposal, the blog list adopted useCrudResource and an abortable adapter, the editor adopted useForm and useUnsavedChangesGuard, and blog deletion gained an editor confirmation plus list Undo window. Those changes partially address backend-switch and deletion proposals. The editor’s database watcher still reloads and resets form values without a dirty-switch guard; CDN sync and Dynamo concurrency proposals remain unimplemented. The target diagrams below remain proposals. Sources: blog adapter, blog editor, blog list, CDN client.
2026-11-05 implementation checkpoint: The admin now has a per-environment JSON manifest, authenticated progress endpoint, and retry of pending files in one process. The activity below remains a proposal for immutable source pinning, destination overwrite ownership, multi-process claims, bounded reads, and background execution. Media deletion intent is also implemented; the October discussion below is historical. See current admin, current media, and CDN sync runner.
Reviewed 2026-10-17 (America/Los_Angeles), working-tree source at HEAD 3316bf821f1f70251dac73ca4724142fdaf39a72.
Status: design proposal, not implemented or approved for deployment. Only the current-state diagram describes existing behavior. Target diagrams describe proposed responsibilities within the existing admin app, not new deployed services or implemented classes. The October 14 as-built review is a historical snapshot; this page rechecks the specific evidence below, not the entire earlier diagram set.
Current behavior and changes since the first review
The standalone Nuxt node-server still extends web-layer-admin, now through nuxt-layer-ui and nuxt-layer-base. Browser session state holds the shared token and database choice. Blog/messages use selected, cached store adapters. CDN tools use one configured MinIO bucket; the database selection chooses only the staged sync directory. Media owns a separate local library or forwards to a configured media API. Database selection does not migrate records or select a media library. [S1–S4, S8, S11]
The shared-token comparator now compares SHA-256 digests with timingSafeEqual. Admin-local media upload now registers onIngestRecipesHook; an explicit processing endpoint and bounded detail polling support re-running recipes. Media detail requests already discard stale responses. These are existing capabilities and must not be proposed as missing. CDN delete still calls DELETE immediately; media has confirmation and an eight-second Undo window. [S5, S9, S11, S12]
Current component relationships — verified
flowchart LR
UI["Admin browser pages"] --> Client["Session and adminFetch"]
Client --> Hook["Nitro request hook: select cached blog store"]
Hook --> Routes["Authenticated blog, messages and CDN routes"]
Routes --> Posts["Injected blog facade and BlogPostStore"]
Routes --> Messages["Selected MessageStore"]
Posts --> DB["SQLite / PostgreSQL / DynamoDB"]
Messages --> DB
Routes --> CDN["MinIO list, put, delete and staged sync"]
CDN --> Bucket["One configured bucket"]
Output["Selected .output directory"] --> CDN
UI --> MC["media-client"]
MC --> MR["Authenticated admin media routes"]
Hook -. "also runs for media requests" .-> MR
MR --> Local["Local MediaLibrary with on-ingest recipes"]
MR --> Remote["Configured media API forwarding"]
Evidence: S1–S4, S6–S8, S11. Hook execution precedes route-level authentication. The local/remote media arrows are alternative configuration branches. The bucket and DB nodes are persistence targets, not shared transactions. The diagram omits rendering-only layer dependencies described above.
Proposed component responsibilities
Keep the standalone admin deployment and current storage adapters. Move backend resolution and store initialization into authenticated feature execution; session validation and CDN/media operations should not require a blog database. Reuse cached stores behind a lazy accessor. Do not introduce a generic queue for normal CRUD.
flowchart LR
UI["Existing admin pages"] --> Context["PROPOSED: explicit operation target, dirty-state guard and request generation"]
Context --> Gate["Existing server token gate"]
Gate --> Feature["PROPOSED: authenticated feature dispatch"]
Feature --> Stores["Existing stores via PROPOSED lazy resolution"]
Feature --> CDN["Existing CDN adapter with PROPOSED pagination and bounded streams"]
Feature --> Media["Existing local or forwarded media boundary"]
CDN -. "PROPOSED durable sync mode" .-> Record["PROPOSED operation manifest and progress"]
Runner["PROPOSED resumable sync execution inside admin deployment"] -. "read and checkpoint" .-> Record
Runner -. "bounded object writes" .-> CDN
Solid arrows describe the intended target call chain; labels distinguish retained components from proposed changes. Dashed arrows are the optional durable-sync extension, not current runtime connections. The exact persistence adapter and runner lifecycle are undecided; no new table, class, scheduler, Lambda or queue is claimed to exist. Source motivation: S2–S4 and S8.
Backend-switch and mutation contract — proposed
A request must capture its resource ID, backend and session generation at dispatch. An asynchronous response may update UI state only if that context still matches. Abort where supported, but retain a generation check because abort does not guarantee server cancellation. The existing media detail counter is a local precedent, not a shared implementation. [S6, S7, S12]
sequenceDiagram
actor Operator
participant UI as Admin page
participant Session as Session and selection
participant API as Authenticated feature route
participant Store as Selected cached store
Operator->>UI: Choose another backend
alt Unsaved edit or mutation in flight
UI-->>Operator: Keep current context until save, discard or completion
else Switch permitted
UI->>Session: Set backend and advance request generation
UI->>API: Load with captured backend and token
API->>API: Authenticate, then validate backend
API->>Store: Resolve lazily and read
Store-->>API: Records
API-->>UI: Response for captured request
alt Backend and generation still match
UI->>UI: Apply records, errors and pending state
else Context changed again
UI->>UI: Ignore obsolete response
end
end
This sequence is entirely proposed. S3/S6/S7 show the current selector and reload paths. Dirty-edit handling must also cover new posts, pending saves, failed loads and records with identical IDs in different stores. A backend change must never silently retarget an already-started save or delete. Retain valid persisted selection; use configured default only for a fresh or invalid session. Separate the CDN bucket target from its staged build-source selector in the UI without implying that backend choice changes the bucket.
Recoverable CDN sync lifecycle — proposed
The current sync enumerates a directory, reads each complete file and performs sequential PUTs in the request. It returns only a final count or error and supplies no explicit content type. Listing sends one ListObjectsV2 request. [S8]
flowchart TD
Start["Authenticated sync request"] --> Plan["Capture bucket, source release and immutable file manifest"]
Plan --> Persist["Persist operation and per-file pending state"]
Persist --> Claim["Claim bounded execution lease"]
Claim --> Write["Stream next file with content type and checksum"]
Write --> Result{"Write and verification succeeded?"}
Result -- No --> Retry["Persist error and retry eligibility"]
Retry --> Resume["Resume same operation with bounded retry policy"]
Resume --> Claim
Result -- Yes --> Checkpoint["Persist file completion"]
Checkpoint --> More{"Pending files remain?"}
More -- Yes --> Write
More -- No --> Done["Persist completed result and show summary"]
This activity is proposed, motivated by S8. A lost response after successful PUT must be safe to retry. Source files must remain pinned to the recorded release/checksum; do not read a changing .output tree on resume. Persist the destination with the operation so selection or configuration changes cannot redirect it. Exhausted retries need a visible failed/partial state and explicit resume, not an endless loop. Use a process-restart-safe claim with lease expiry if multiple executions are possible. No automatic pruning is proposed.
Operation state does not make object writes and database checkpoints atomic. Define overwrite ownership: either serialize conflicting writes to the same key or use versioned objects with an explicit publication contract. The runner must survive HTTP disconnects and resume after process restart; choose durable persistence and lifecycle management before promising background execution. A bounded synchronous sync can remain the initial mode while this extension is designed.
Prioritized implementation roadmap — proposals only
| Order | Change and affected code | Acceptance evidence required before calling it complete |
|---|---|---|
| 1 | Authenticate before lazy store selection; reconcile runtimeConfig names in S1–S4 | Valid sign-in and unrelated CDN/media requests work with blog DB unavailable; unauthorized requests never construct a store; configured DB overrides reach the intended factory; existing cached reuse remains |
| 2 | Capture operation context and guard backend switching in S3/S6/S7 | Delayed old responses cannot replace records, errors or loading state; dirty new/existing edits survive cancelled switches; in-flight mutations retain their original backend; fresh-session default differs correctly from a valid persisted choice |
| 3 | Paginate CDN listing; preserve MIME metadata; bound upload and sync memory in S8/S9 | Multiple pages are reachable without omissions in a stable test bucket; continuation tokens cannot silently change listing scope; bounded reads, declared size limits, content types and partial failures are verified |
| 4 | Align deletion interaction across blog/messages/CDN using the existing media pattern in S12 | Accessible confirmation and pre-request Undo, correct focus restoration, explicit in-flight/failure state; navigation behavior is defined; no claim of server restoration after permanent deletion |
| 5 | Protect blog concurrent writes in S13 | Atomic slug ownership across create/rename/delete and conditional revision checks; concurrent same-slug writers yield one winner; stale update cannot resurrect a deleted record; equivalent contract across adapters |
| 6 | Add durable CDN sync only after persistence and overwrite decisions above | Kill/restart and lost-response tests resume the same manifest and destination without corrupting a newer write; failed items and retry budget are visible; audit records contain no secrets |
| 7 | Expand identity only if multiple independently authorized operators require it | Agreed actor/permission model, session lifecycle and attribution; shared-token support and migration explicitly decided; no invented identity service |
These are dependency-oriented work slices, not effort estimates or permission to alter schemas. Store contract changes need a migration/backfill/rollback design before any data mutation. Keep each slice separately reviewable. Existing unit test files can be extended; add failure/concurrency cases instead of assertions that merely mirror implementation. Application validation must cover the exact user-facing admin URL and all affected flows before completion claims.
Media Library integration boundary
Apply media reliability changes in the MediaLibrary and its adapters, not in a second admin-only pipeline. Existing on-ingest recipes, re-run processing and detail polling remain the entry points. Review the current on-ingest implementation before deciding what validation is missing; the October 14 statement about normal upload processing is no longer a sufficient baseline. [S11, S12, S14]
The earlier media proposal still needs explicit decisions: deletion intent and object manifest before catalog removal, name/generation ownership during cleanup, retries for audit/invalidation, and immutable attempt objects with atomic conditional publication. Current deletion still removes catalog state before deleting blobs, and the extracted materialize runner still writes the variant before conditional finalization. Job persistence and execution dispatch are distinct responsibilities. [S15–S17]
Attempt-key changes must account for parseMediaKey/variantKey, preview URLs, transfers and public delivery. Validation for directly uploaded objects needs a defined publication boundary; a proposed quarantine path must not be represented as implemented. Admin should display server-reported status rather than fabricate successful completion or duplicate recovery logic. These media changes require their own current-source design review and adapter tests.
UX, environment and evidence limits
For all proposed admin controls: reflow from 375px through desktop without page overflow; visible keyboard focus, named controls, announced operation/conflict state, WCAG 2.2 AA contrast and 400% zoom/reflow; at least 44px touch targets and no hover-only or gesture-only action. Compare delayed client Undo with durable server recovery honestly: client Undo can stop an unsent request, while server recovery adds persistence/retention costs and a different data contract. Neither is an implemented universal recycle bin.
The proposal keeps the current node-server host/Docker deployment. It does not deploy admin to AWS. Media forwarding remains optional; admin backend selection is not an AWS environment switch. Durable sync persistence and execution remain design decisions. No live services, credentials, database contents, application tests or browser paths were exercised for this document. Risks are source-based inferences, not reproduced incidents.
Source-to-diagram traceability
Paths and symbols below were rechecked for this proposal. Source line anchors belong to the October 17 checkout. Target arrows are proposed and have motivation evidence, not implementation evidence.
| ID | Supporting implementation | Relationship or design motivation |
|---|---|---|
| S1 | admin Nuxt config, layer config: extends, runtimeConfig, node-server | Current deployment/layers; proposed config alignment |
| S2 | admin-blog.ts: request hook | Current pre-auth selection and injected facade; lazy-resolution proposal |
| S3 | AdminDatabaseSelector.vue: onChange/onMounted; admin-session.ts: defaultAdminSession | Current choice/default; proposed switch contract |
| S4 | admin-database.ts: resolveAdminDatabase, store caches, outputSysEnvForDatabase | Current routing/cache and output mapping |
| S5 | admin-auth.ts: secureCompare; admin-handler.ts: requireAdminBlog/checkAdminSession | Current gate and digest comparison |
| S6 | blog edit page: loadPost, watcher, onSave/onDelete | Switch race, dirty-edit and mutation proposals |
| S7 | messages page: loadMessages/onDelete; message route | Current authenticated store use and immediate delete |
| S8 | minio-client.ts: listCdnObjects, putCdnObject, syncPublicAssetsToMinio; sync route | Current CDN graph; proposed pagination/streaming/durable activity |
| S9 | CDN page: onDelete | Immediate DELETE remains implemented |
| S11 | media-service.ts: getLocalLibrary, ingestMediaUpload, rerunMediaProcessing; process route | Existing local hook and authenticated re-run/forwarding |
| S12 | media page: detailRequest and deletion state; poller: createProcessingPoller | Existing stale-detail guard, Undo and bounded polling |
| S13 | blog-dynamodb.ts: createPost/updatePost/deletePost | GSI slug precheck and unconditional update motivate concurrency contract |
| S14 | on-ingest.ts: runOnIngestRecipes/onIngestRecipesHook | Current media processing baseline to preserve and separately review |
| S15 | media-library.ts: deleteAsset | Catalog-before-blob deletion remains current |
| S16 | materialize-job.ts: runMaterializeJob | Blob write before conditional job/child finalization |
| S17 | paths.ts: parseMediaKey/variantKey | Attempt-key compatibility constraint |
Validation record. Open implementation work is indexed in the canonical follow-up list.