Skip to the content.

Admin process architecture

Current source review (2026-10-21): Admin process — current implementation. The diagrams below remain the October 14 historical snapshot; target architecture is a proposal.

Historical snapshot: the diagrams below describe the October 14 source review. Source has since changed. See the October 17 current-state delta, proposed target and roadmap for rechecked admin boundaries, new processing UI and proposed improvements. This is not a full refresh of the original diagrams.

Source review: 2026-10-14 (America/Los_Angeles). HEAD: 029399ec3d8144ae824a024c86891b3bff44e801. Root package: 1.3.73. Admin package: 1.0.0.

This is an as-built source review, not a live deployment or security certification. Application behavior, existing unrelated edits and the preceding Media Library diagrams remain unchanged. Nothing was staged, committed or pushed.

Architecture summary

The admin is a separate Nuxt node-server app at core/admin. It extends web-layer-admin for sign-in, tab session state and blog UI/API. The host adds navigation, backend selection, message/CDN/media tools, and a Nitro request hook that attaches the blog API facade. It reuses core/web services and SQLite/PostgreSQL/DynamoDB store factories through #web-server.

Backend selection is explicit per request, with stores cached per backend. It does not move data. CDN tools use one configured MinIO bucket; selection changes only the staged sync source folder. Media Library is independent: local SQLite/filesystem or MEDIA_API_URL forwarding. See Media Library architecture.

Diagrams and source-to-diagram traceability

Nine Mermaid diagrams are embedded in Markdown, matching existing architecture docs. Each page provides source paths, exact symbols and line anchors. Component/activity/deployment flowcharts express UML concepts; class and sequence diagrams use native Mermaid notation. No inferred service or runtime class was invented.

Diagram Main source-to-diagram relationship
Components core/admin config extends layer; request hook injects facade; services consume cached stores
Class model AdminSession, AdminBlogApi, BlogPostStore, MessageStore and entity interfaces
Authentication Sign-in onSubmit → verifyAdminToken → checkAdminSession; adminFetchOptions handles 401
Database selection Selector setDatabase → page watchers → header → resolveAdminDatabase and cache
Blog Post handlers → host facade → parse/service → store and publication helpers
Messages Message handlers → listContactMessages/deleteContactMessage → MessageStore
CDN CDN handlers → list/put helpers or output-directory walk → S3 client
Lifecycle and deletion Session middleware, feature pages and their actual confirmation/delete paths
Deployment Nuxt node-server config, Compose, Dockerfile, host build helper and optional media forwarding

Entry points and operations

UI Endpoints Behavior
/admin GET /api/admin/session Validate candidate shared token
/admin/blog GET/POST /api/admin/posts List all statuses or create
/admin/blog/new and /admin/blog/:id GET/PUT/DELETE /api/admin/posts/:id Edit, publish/unpublish and delete
/admin/messages GET /api/admin/messages; DELETE /api/admin/messages/:id Review and remove
/admin/cdn GET/PUT/DELETE /api/admin/cdn/objects; POST /api/admin/cdn/sync Object administration and staged-file copy
/admin/media /api/admin/media/assets, assets/:id, assets/:id/materialize, jobs/:id DAM CRUD, metadata PATCH and processing

The bare root redirects to /admin. Admin pages render client-only because their session starts in sessionStorage. AdminNav links the five surfaces. State uses useState, refs and computed values; no dedicated Pinia admin store is evidenced.

Actual operational process

  1. The client plugin restores the versioned token/database pair from sessionStorage, migrating legacy keys. Storage errors fall back to in-memory state.
  2. Protected pages check token presence through middleware. Sign-in validates the candidate server-side before saving and follows a safe /admin redirect.
  3. Blog/messages/CDN calls use adminFetch, attaching Bearer and X-Admin-Database only to same-origin requests. Media uses media-client separately.
  4. The global Nitro request hook resolves a backend and attaches blog service closures using a cached store. Route handlers then enforce authentication and perform their operation.
  5. Database resolution uses a valid query db, then valid header, then configured default. Factories receive explicit dataBackend, overriding ambient DATA_BACKEND. Switching does not transfer data.
  6. Blog create/update parses fields and normalizes slug. Publication is a stored status change: draft→published stamps publishedAt; unpublish clears it. No deployment or approval workflow is triggered.
  7. Messages offer list/delete only. CDN uploads decode base64; sync sequentially reads files and overwrites corresponding bucket keys. DAM operations follow the separate media workflow.
  8. Current-token 401 responses through adminFetch clear the token and share an expired-session redirect. Responses for an older token preserve the newer login. Clear saved token removes only the token, retaining database choice.

Delete safeguards differ: blog uses native confirmation, messages/CDN delete immediately, and media delays DELETE with an eight-second Undo window. There is no common server recycle bin.

Data and persistence

SQL schemas contain independent posts and messages tables, with no user-owner or attachment relationships. Posts have unique slug and a draft/published check; messages index created_at. Domain interfaces are implemented by factory-returned store objects. Dynamo blog uses ID keys and slug/status indexes; slug lookup and record write are separate operations.

Session state is browser data, not a database entity. CDN object summaries are projections from bucket listing, not DAM catalog records. Sync returns uploaded/skipped/sourceDir; it does not create a durable job.

Environment differences

Environment Admin behavior
Host layer development Nuxt dev available with supplied authentication and DB configuration
Standalone Docker Node-server admin, mounted SQLite/media data, PostgreSQL, DynamoDB Local and MinIO
AWS No admin-app SAM deployment; a configured media forwarding URL can target public web media APIs

Build output is .output/admin. CDN reads the output mount read-only and maps sqlite→local, postgres→development, dynamodb→test. All selections target the same CDN bucket. Compose configures a dynamodb default, but the initial browser session defaults to sqlite and only falls back to configured default if its selection is disallowed.

No live containers, remote endpoints, deployment state or secret values were inspected.

Authentication and error boundaries

requireAdminToken fails closed when the expected token is absent and compares equal-length bytes with timingSafeEqual. Token environment aliases take precedence over runtimeConfig. Every protected operation checks the server gate; local signedIn state, noindex and route middleware are not authorization.

There is one shared secret, with no evidenced individual account, role hierarchy, per-user audit identity, server session record, timed session expiration or MFA step. Public web media endpoints still use token authentication even though the admin UI is deployed separately.

Blog validation maps to 400, missing records to 404, slug conflicts to 409; an absent injected facade is 500. Message delete returns 404 when missing. CDN delete does not check object existence; sync wraps errors as 500 and may have already uploaded files. Missing staged sync directories return skipped true rather than an exception. Sign-in displays a generic reachability message for non-401 failures.

Findings and architectural risks

Observed code mechanisms support the following risks; these are not reproduced production defects.

Finding Verified mechanism Inferred consequence
Store initialization before route auth Global blog request hook resolves a store for every request DB initialization failure can affect sign-in, CDN/media requests or healthchecks
Backend-switch response races Blog/messages watchers reload without cancellation or request-version guards Slower old-backend responses can overwrite the new view; unsaved edit fields can be replaced
Default selection mismatch Session starts at sqlite; selector uses configured default only when selection is disallowed Client requests may select SQLite despite Compose defaulting to DynamoDB
Partial CDN listing One ListObjectsV2, no continuation loop Large buckets can appear incomplete
Buffered and partial CDN sync Full-file reads, sequential puts, no rollback Large operations can consume memory/time and leave partial results
Sync metadata omission Sync calls putCdnObject without explicit contentType Intended MIME metadata may be missing; serving behavior needs runtime verification
Dynamo slug/update concurrency GSI precheck, ID-conditioned create, unconditional update Put Concurrent writes can duplicate slugs or overwrite/recreate records
Inconsistent deletion safeguards Native confirmation versus immediate deletion versus delayed Undo Recovery and accidental-deletion exposure differ by feature
Shared-token privilege Same gate for protected administration No individual attribution or role restrictions
RuntimeConfig naming drift Resolver options use adminDynamoTable/adminDynamoPostsTable; host declares dynamoTable/dynamoPostsTable Environment fallback can mask runtimeConfig-only overrides that do not reach the factories

The message route’s “No singleton” comment and old guide’s “per-request store” description differ from the current implementation: one store is cached per backend; the selected facade is per request. The related guide is corrected; source comments are recorded here without changing application files.

Any resulting UI change should cover phone-to-desktop reflow without page overflow, keyboard/focus/screen-reader operation and WCAG 2.2 AA contrast, plus at least 44px touch targets. This documentation work introduces no UI and claims no accessibility testing.

Verification and uncertainties

Resolved Nx @tgmc/admin targets were inspected: build produces .output/admin; tests use the local Vitest launcher with dependency builds. Native-module cache warnings occurred during inspection.

Test source reviewed: core/web/tests/web-layer-admin/admin-fetch.spec.ts and admin-handler.spec.ts, and core/admin/tests/admin-database.spec.ts and minio-client.spec.ts. Assertions cover credential injection, server gates, backend override selection and S3 list mapping. Existing tests are evidence of intent, not a claimed successful run.

No application tests, browser sessions, DB writes, Docker operations or AWS calls were performed. Diagram validation records parser and source-link checks. Every relationship was compared with supporting code; the deployment possibility is dashed. No private repository content was sent to a diagram service.

Evidence for findings