Skip to the content.

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.