Skip to the content.

Runtime boundaries and system flows

These diagrams describe the current implementation. They complement the architecture hub, process sequences and package references. They are not a target-state design.

Import boundaries

The browser consumes portable helpers and the HTTP client. Node storage and credentials stay behind server routes. Nuxt layers provide app integration; the theme supplies packaged tokens and styles.

flowchart TB
  accTitle: Runtime import boundaries
  accDescr: Browser code uses portable helpers and HTTP; server routes own storage adapters.
  Browser[Browser components] --> Universal[Utilities universal]
  Browser --> Client[Media HTTP client]
  Browser --> DOM[Utilities browser]
  Client --> API[Nitro routes]
  API --> Node[Utilities Node]
  API --> Media[Media library]
  Media --> Stores[SQLite or PostgreSQL or AWS adapters]
  Layers[Nuxt base and UI layers] --> Browser
  Theme[Packaged theme] --> Layers

The default utilities export is a Node entry, not a browser convenience barrel. See utilities and Nuxt UI layer.

Documentation delivery

Markdown is parsed during the build. Requests query the generated Content database through Nitro; the browser does not open the source files or a client SQLite database. Only Mermaid fences within the docs page mapping invoke the diagram renderer.

flowchart TB
  accTitle: Documentation from source to reader
  accDescr: Repository Markdown becomes a Content database at build time and reaches the reader through Nitro.
  MD[Repository docs Markdown] --> Build[Nuxt Content build]
  Build --> DB[Content SQLite dump]
  DB --> API[Content API]
  API --> Page[Docs ContentRenderer]
  Page --> Fence{Mermaid fence?}
  Fence -->|No| Code[Normal prose or code]
  Fence -->|Yes| Source[SSR source and text alternative]
  Source --> Render[Lazy browser renderer]
  Render -->|Success| SVG[Sanitized SVG and source disclosure]
  Render -->|Failure| Fallback[Source and status message]

The same Markdown remains readable on GitHub. See page data loading and gallery/docs.

Preferences and theme application

Validated preferences feed pure token builders. Painting and persistence are separate from token calculation. Both-mode variations let the stylesheet select the active mode; the early head script restores the sanitized committed map before hydration.

flowchart TB
  accTitle: Preferences and theme application
  accDescr: Validated preferences produce both-mode tokens; DOM painting and saved early-paint state are separate effects.
  Picks[Validated preferences] --> Builders[Pure token builders]
  Builders --> Map[Both-mode colour map]
  Map --> Paint[Theme apply or remove]
  Paint --> DOM[Document styles]
  Map --> Saved[Committed token map in storage]
  Saved --> Early[Early head script]
  Early --> DOM
  Mode[Resolved mode] --> CSS[Stylesheet selects mode roles]
  DOM --> CSS

Default preferences allow stylesheet values to apply. See personalization for draft/commit and early-paint details.

Media processing boundaries

Ingest validates bytes before the catalog and blob adapters store an asset. Variant generation writes child outputs; the client reads status and ready URLs. Execution can be local or queued on AWS, so accepting an upload does not mean all variants are already ready.

flowchart TB
  accTitle: Media ingest and variant processing
  accDescr: Validated uploads create stored assets; processing produces child variants that clients can retrieve when ready.
  Upload[Authenticated upload] --> Check[Validate and sanitize]
  Check --> Asset[Catalog asset and original blob]
  Asset --> Process[Local processing or AWS worker]
  Process --> Child[Child variant and output blob]
  Child --> Read[Status and ready URL]
  Read --> Client[Media client and preview]

This diagram groups adapter operations; it does not claim a transaction spans the catalog and blob store. See media, AWS media, and admin.

Default data-backend selection

A nonblank DATA_BACKEND wins. Otherwise E2E_STORE_SYS_ENV takes precedence over SYS_ENV for store selection. Invalid explicit backends throw; missing or unknown environment values fall back to SQLite in this resolver. That fallback is distinct from the stricter Nitro output-directory normalizer.

flowchart TB
  accTitle: Data backend resolution
  accDescr: Explicit backend selection wins; otherwise the effective environment selects SQLite or DynamoDB.
  Input[Environment] --> Override{Nonblank DATA_BACKEND?}
  Override -->|Yes| Valid{Supported value?}
  Valid -->|Yes| Chosen[Use explicit backend]
  Valid -->|No| Error[Throw configuration error]
  Override -->|No| Effective[E2E_STORE_SYS_ENV or SYS_ENV]
  Effective --> Env{Development, remote, test or production?}
  Env -->|Yes| Dynamo[DynamoDB]
  Env -->|No| SQLite[SQLite]

PostgreSQL is an explicit choice. Admin database selection also has request-specific behaviour; see data stores and admin.

Promotion and deployment

Pull requests run CI. Development pushes run regression; promotion to main requires its regression gate. Main deploys to AWS test, while production has a separate release/manual trigger. Local Docker stacks are development tools, not an additional production promotion stage.

flowchart TB
  accTitle: Validation and deployment promotion
  accDescr: Development regression gates promotion to main; AWS test and production use distinct deployment triggers.
  PR[Pull request CI] --> Dev[Merge to development]
  Dev --> Regression[Full regression]
  Regression --> Gate[Main PR regression gate]
  Gate --> Main[Merge to main]
  Main --> Test[AWS test deployment]
  Test --> Dry[Production dry run]
  Release[Published release or confirmed manual dispatch] --> Prod[AWS production deployment]

Triggers, approvals and recovery commands remain authoritative in CI/CD, Docker, and infrastructure.