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
- The client plugin restores the versioned token/database pair from sessionStorage, migrating legacy keys. Storage errors fall back to in-memory state.
- Protected pages check token presence through middleware. Sign-in validates the candidate server-side before saving and follows a safe /admin redirect.
- Blog/messages/CDN calls use adminFetch, attaching Bearer and X-Admin-Database only to same-origin requests. Media uses media-client separately.
- 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.
- 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.
- 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.
- 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.
- 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.
Recommended improvements — not existing implementation
- Resolve stores lazily in authenticated feature handlers and align runtimeConfig field names.
- Guard backend changes against stale responses and unsaved edits; initialize new sessions from the intended configured default.
- Paginate listings, stream bounded uploads, preserve content types and provide recoverable sync progress.
- Add atomic Dynamo slug claims and revision-conditional updates where concurrent administration matters.
- Align delete confirmation/recovery; consider individual identities and actor audit records if operators expand.
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
- core/admin/server/plugins/admin-blog.ts:19 — nitroApp.hooks.hook(‘request’
- core/admin/server/utils/admin-database.ts:60 — export const resolveAdminDatabase
- core/admin/app/components/AdminDatabaseSelector.vue:44 — onMounted
- packages/web-layer-admin/app/utils/admin-session.ts:14 — export const defaultAdminSession
- packages/web-layer-admin/app/pages/admin/blog/[id].vue:102 — const loadPost
- core/admin/app/pages/admin/messages/index.vue:62 — const loadMessages
- core/admin/server/utils/minio-client.ts:50 — export const listCdnObjects
- core/admin/server/utils/minio-client.ts:121 — export const syncPublicAssetsToMinio
- core/web/server/db/blog-dynamodb.ts:103 — const createPost
- core/admin/nuxt.config.ts:19 — const dynamoTable
- core/web/nuxt.config.ts:42 — const adminToken