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.