Skip to the content.

Admin process — current implementation

Source review: 2026-10-21, HEAD f38ee3c6ced7fcab6b34955a65cfb955ec097567, root package 1.6.9. This supersedes the October 14 diagrams for current behavior. Arrows describe source-visible calls; deployment is configuration, not a live-environment check.

2026-11-05 CDN update: The admin sync now persists per-environment progress under data/admin-cdn-sync, exposes an authenticated progress read, and resumes pending files after a failed request or process restart when the staged source is unchanged. This targeted update reflects the current task branch; it is not a full rereview of the other diagrams. Sources: sync runner, sync routes, admin Compose.

Components

flowchart LR
  Browser["Admin browser"] --> UI["web-layer-admin pages and core/admin media/CDN pages"]
  UI --> FETCH["useAdminFetch and media-client"]
  FETCH --> API["core/admin Nitro routes"]
  API --> AUTH["requireAdminToken"]
  API --> SELECT["resolveAdminDatabase"]
  SELECT --> BLOG["BlogPostStore"]
  SELECT --> MSG["MessageStore"]
  BLOG --> SQL["SQLite or PostgreSQL"]
  BLOG --> DDB["DynamoDB"]
  MSG --> SQL
  MSG --> DDB
  API --> CDN["MinIO client and output sync"]
  API --> MEDIA["admin media-service"]
  MEDIA --> LOCAL["local MediaLibrary / SQLite / filesystem"]
  MEDIA -->|MEDIA_API_URL| WEB["web media API"]

The selected database applies to blog posts, messages and CDN source-output mapping; media has its own local or forwarded configuration. Sources: admin routes, database selector, auth gate, media service, CDN client.

Main types and responsibilities

classDiagram
  class BlogPost {
    +id
    +slug
    +status
    +title
  }
  class BlogPostStore {
    <<interface>>
  }
  class MessageStore {
    <<interface>>
  }
  class AdminMediaAsset {
    +id
    +path
    +publicUrl
    +previewUrl
  }
  class MediaLibrary {
    +ingest()
    +renameAsset()
    +deleteAsset()
  }
  BlogPostStore --> BlogPost : persists

These are selected implemented types, not an inheritance hierarchy. AdminMediaAsset is a type intersection created by the admin service, while BlogPostStore and MessageStore are store contracts. Sources: blog types, blog store, message store, media service, MediaLibrary.

Authentication and database selection

sequenceDiagram
  actor Admin
  participant UI as Admin page
  participant Fetch as useAdminFetch
  participant Route as Admin API route
  participant Gate as requireAdminToken
  participant Select as resolveAdminDatabase
  participant Store as Blog/Message store
  Admin->>UI: Enter bearer token and select database
  UI->>Fetch: Request with token and database header
  Fetch->>Route: HTTP request
  Route->>Gate: Validate bearer against configured token
  alt missing or invalid token
    Gate-->>Fetch: 401
    Fetch-->>UI: Expired-session redirect
  else valid token
    Route->>Select: Resolve query db, header, or default
    Select->>Store: Select backend-specific store
    Store-->>Route: Result
    Route-->>UI: Response
  end

The route middleware is a client navigation guard; server routes enforce the bearer token. Query db wins over X-Admin-Database. Sources: route middleware, fetch wrapper, auth gate, database selector.

Blog edit and deletion

sequenceDiagram
  actor Admin
  participant Editor as Blog editor
  participant Form as useForm / dirty guard
  participant List as Blog list / useCrudResource
  participant API as Admin post API
  participant Store as BlogPostStore
  Admin->>Editor: Edit and save
  Editor->>Form: Validate shared schema
  Form->>API: POST new or PUT existing
  API->>Store: Persist selected backend
  Store-->>Editor: Saved post
  Admin->>Editor: Confirm delete
  Editor->>List: In-memory handoff and navigation
  List->>API: GET list (abortable)
  API-->>List: Posts
  alt handoff is fresh and post is listed
    List-->>Admin: Undo window
    opt Undo not selected
      List->>API: DELETE post after delay
      API->>Store: Delete selected backend
    end
  else load fails or post absent
    List-->>Admin: Not deleted
  end

The list filters status in the route query and loads all posts in one response. The editor uses useUnsavedChangesGuard for navigation, but its database watcher calls loadPost() and resets form values without a separate dirty-edit check; a slow response can also replace a later selection. These are source-level risks, not observed production failures. Sources: blog adapter and handoff, blog list, blog editor, CRUD composable, dirty guard, post API.

Media administration

sequenceDiagram
  actor Admin
  participant Page as Admin media page / drawer
  participant Client as media-client
  participant Route as Admin media API
  participant Service as media-service
  participant Library as MediaLibrary or web media API
  Admin->>Page: Upload asset
  Page->>Client: Ingest request
  Client->>Route: POST ingest
  Route->>Service: ingestMediaUpload
  alt local media
    Service->>Library: Ingest with sanitization and processing
  else MEDIA_API_URL configured
    Service->>Service: Sanitize upload bytes
    Service->>Library: SVG request or presign, PUT, complete
  end
  Library-->>Page: Asset and URLs
  Admin->>Page: Edit metadata or rename
  Page->>Client: PATCH metadata or POST rename
  Client->>Route: Authorized request
  Route->>Service: Update or rename
  Service->>Library: Local call or forwarded request
  Admin->>Page: Confirm delete and optionally Undo
  Page->>Client: DELETE after undo window
  Client->>Route: DELETE asset
  Route->>Library: Cascade delete

The media page now has metadata and rename forms plus a processing drawer. Its delete uses the shared undo composable, whereas the API performs hard deletion when the timer commits. The media store is independent of the blog/message database selector. Sources: media page, editing composable, drawer, media routes, media service. See Media Library current architecture for processing and storage details.

Messages and CDN

flowchart LR
  MUI["Messages page"] --> MGET["GET /api/admin/messages"]
  MUI --> MDEL["DELETE /api/admin/messages/:id"]
  MGET --> MS["selected MessageStore"]
  MDEL --> MS
  CUI["CDN page"] --> CLIST["list objects"]
  CUI --> CPUT["upload object"]
  CUI --> CDEL["delete object"]
  CUI --> CSYNC["sync staged output"]
  CUI --> CPOLL["read sync progress"]
  CLIST --> MINIO["MinIO bucket"]
  CPUT --> MINIO
  CDEL --> MINIO
  CSYNC --> OUTPUT[".output/<environment>/public"]
  CSYNC --> STATE["persistent sync manifest"]
  CPOLL --> STATE
  OUTPUT --> MINIO

Messages use the selected database; CDN operations use one configured bucket. CDN sync reads staged build output, writes objects sequentially, and checkpoints a per-environment JSON manifest after each successful PUT. The selected database only chooses the staged source directory. The manifest lives in the admin data volume (NUXT_CDN_SYNC_STATE_DIR can select another persistent path); a repeat POST resumes pending files only when the source snapshot and normalized MinIO endpoint and bucket still match. Older manifests without an endpoint identity start a fresh sync. A repeat after completion returns the same operation without another PUT; the UI reads progress for the captured database before sending an explicit restart when the operator chooses to resync. There is no cross-process lease or conditional destination write, so this is not multi-replica reconciliation. Sources: messages page, message routes, CDN page, CDN routes, sync runner, CDN client, database selector.

Deployment

flowchart TB
  Host["Local admin Nitro node server"] --> SQLite["SQLite blog/message database"]
  Host --> Files["local media filesystem"]
  Docker["Docker admin Nitro service"] --> PG["PostgreSQL option"]
  Docker --> DD["DynamoDB Local option"]
  Docker --> MinIO["MinIO CDN"]
  Docker --> Forward["optional MEDIA_API_URL"]
  Forward --> Web["Web media API"]
  Web --> AWS["SAM web Lambda + media AWS resources"]

This diagram describes configured paths. There is no separate admin-app SAM deployment in the inspected configuration; AWS media belongs to the web stack when forwarding is enabled. Sources: admin Nuxt config, admin Compose, admin Dockerfile, SAM template, media service.

Current issues and recommendations

Verified source behavior: editor database changes can reset unsaved values; CDN sync now has a local durable manifest but no cross-process lock or destination overwrite guard; post list is one unpaged response; Dynamo post updates remain unconditional after the slug precheck; media selection is independent of the admin database control. Recommended work: guard/reconcile editor database switches, add CDN pagination if object counts grow, add conditional destination writes before multi-replica sync, introduce conditional Dynamo revisions and slug claims where concurrent editing matters, and label the media storage target in the UI. These are recommendations, not diagrammed services. Sources: editor, blog adapter, sync runner, Dynamo blog store, media service.