🧭 Runtime Architecture

Prompt Wizard is a single Bun service with a Vite-built React client. The browser talks only to same-origin routes. The server owns persistence, uploads, identity, generation calls, and live invalidation events.

Runtime components

• browser SPA:
  • React 18 app built by Vite
  • imports room from src/lib/room.js for collection access
  • imports generateText, generateImage, uploadFile, getCurrentUser, and reportError from src/lib/ai.js
  • renders generated prompt steps, settings, library, blueprint views, admin prompts, debug views, and wizard management
• Bun server:
  • serves dist/ with SPA fallback
  • serves uploaded files from data/uploads/ under /uploads/
  • exposes JSON API routes under /api/
  • stamps identity from the Authelia-provided user header
  • shells out to installed omp for generation
• SQLite store:
  • database path: data/pwiz.db
  • journal mode: WAL
  • JSON-valued columns are stored as text and parsed at API boundaries
• event stream:
  • one shared EventSource('/api/events') in the client module
  • successful mutations broadcast the affected collection name
  • likes toggles broadcast both likes and blueprints

Request lifecycle

• page load:
  • nginx authenticates app requests with Authelia
  • Bun serves the SPA shell
  • React mounts immediately; no WebSim initialization race remains
• collection read:
  • component creates room.collection(name).filter(criteria) or room.collection(name)
  • useQuery(query) fetches /api/collections/:name
  • result is newest-first array data
• mutation:
  • client calls create, patch, delete, or toggleLike
  • server validates collection and payload
  • server writes SQLite row or transaction
  • server emits collection invalidation event
  • subscribed browser queries refetch
• generation:
  • client posts to /api/ai/text or /api/ai/image
  • server writes the prompt context into an omp system-prompt file
  • server runs omp with stdin ignored and project context disabled
  • server stores an llm_logs row with the true outcome

Development proxy

The Vite development server proxies /api and /uploads to the Bun backend origin. Use a symbolic backend origin in examples and keep machine-specific loopback values out of published prose.

server: {
  proxy: {
    "/api": "${BACKEND_ORIGIN}",
    "/uploads": "${BACKEND_ORIGIN}"
  }
}

Runtime dependencies

• Bun: runs server and scripts
• Vite: builds client assets
• React and React DOM: UI runtime
• marked and Mermaid: rendered docs and diagrams
• Fabric.js: wizard avatar editor
• Font Awesome package: local icons, not CDN
• installed omp: sole text and image generation backend

See omp-integration for the generation bridge and api for route contracts.