How pasta-devs/marinara-engine works
1. Overall shape
- This is a local-first monorepo for the Marinara Engine product, centered on a TypeScript server + TypeScript React client with a shared schema/types package.
- Around that core are platform wrappers and deployment assets: Docker, Windows launcher/installer, Android WebView shell, and a Home Assistant custom component.
2. Primary runtime boundary
- The main execution path is packages/server running as the backend API and orchestration layer.
- packages/client is the browser UI built with React + Vite, talking to the server over HTTP/SSE and consuming server-managed state.
- packages/shared defines the contracts both sides rely on: schemas, types, constants, and utility logic.
3. Client architecture
- The client is organized by feature areas: chat, game mode, agents, characters, lorebooks, presets, connections, assets, and settings.
- UI state is split between global stores and feature hooks. Stores handle app-wide state slices like chat, game state, dialog, translation, sidecar, and UI.
- Most UI actions are thin orchestration layers that call hooks, which in turn call the API client and update stores.
4. Server architecture
- The server is the central coordinator for persistence, prompt assembly, generation workflows, agent execution, import/export, media handling, and integrations.
- It is split into:
- routes: HTTP endpoints grouped by feature,
- services: business logic and workflow engines,
- db/storage: persistence and migrations,
- middleware: security and request policy,
- config/utils: runtime and environment concerns.
5. Data persistence boundary
- State is stored locally using a file-backed database layer with schema definitions under packages/server/src/db/schema.
- Storage services map API-facing entities such as chats, characters, connections, lorebooks, themes, regex scripts, prompts, and game state into that local store.
- The repo also includes seed data and migration helpers, indicating the app can bootstrap a working local environment without external setup.
6. Prompt and generation pipeline
- A major backend subsystem is the prompt pipeline: assembling prompts, expanding macros, applying prompt overrides, merging presets, and injecting lorebook/context data.
- Generation-related routes and services also handle dry runs, replay, SSE streaming, agent normalization, and retry logic.
- The shared package provides prompt/macro utilities that keep generation behavior consistent between UI and server.
7. AI agent subsystem
- Agents are a first-class subsystem on both UI and server sides.
- The server has an agent executor/pipeline, knowledge retrieval/router, and conversation-aware services; the client exposes agent editors, debug panels, thought bubbles, and context injection controls.
- Agents augment chat/game sessions with tasks like world state tracking, quest updates, scene analysis, prose analysis, expression detection, and other autonomous behaviors.
8. Conversation and game modes
- The product has multiple interaction surfaces: Conversation, Roleplay, and Game.
- Conversation services manage chat history, summaries, autonomous messaging, transcript sanitization, and command handling.
- Game services manage higher-level simulation features such as combat, dice, encounters, maps, weather, time, party/NPC state, journals, checkpoints, and session summaries.
9. Media and immersive subsystems
- The client contains extensive UI for sprites, backgrounds, weather overlays, galleries, audio, and image prompts.
- The server provides corresponding services for asset manifests, sprite generation, background handling, image generation, and file/media routes.
- This makes visuals part of the core architecture, not just decorative UI.
10. External integrations
- The server abstracts multiple provider families:
- LLM providers like OpenAI, Anthropic, Google/Gemini, OpenRouter, Mistral, Cohere, NovelAI, and custom OpenAI-compatible endpoints,
- sidecar/local inference services,
- image generation backends,
- Spotify playback/auth,
- haptics,
- bot browser/import sources.
- These are isolated behind provider and service layers so the UI mostly interacts with unified app concepts rather than vendor-specific APIs.
11. Security and trust boundaries
- The repo is intentionally local-first, but the server still enforces a significant security boundary.
- Middleware covers Basic Auth, CSRF protection, IP allowlisting, rate limiting, security headers, privileged/admin gating, and error handling.
- The README notes that powerful actions like backups, bulk import, updates, sidecar lifecycle changes, haptics, and custom tool mutation require an admin secret.
12. Platform wrappers and deployment
- Docker/Docker Compose are the primary packaging path for self-hosting.
- Windows has a dedicated launcher and NSIS installer pipeline.
- Android is a WebView shell around the same local server, not a standalone server app.
- There are also release/build workflows for APKs, containers, and Windows installers.
13. Home Assistant integration
- custom_components/marinara_engine is a separate integration package for Home Assistant.
- It exposes entities/services around the engine via HTTP/webhooks/coordinator patterns, meaning it treats Marinara Engine as an external local service rather than embedding it.
14. Useful diagram anchors
- The cleanest architecture diagram would center on:
- Client UI
- Server API/orchestrator
- Local persistence
- Provider/integration adapters
- Sidecar/runtime helpers
- Platform wrappers
- The main flow is: user action in client → server route → service pipeline → local store and/or external provider → server streams or returns results → client updates stores/UI.
Main entry points: assembler.ts Services · app.ts Server API · index.ts Routes · use-generate.ts Feature Hooks
Components 21
Packages
Core monorepo packages for app runtime and shared contracts.
- Client UI · Browser application for chat, game mode, assets, and settings.
packages/client/src/App.tsx - UI Stores · Global client state for chat, game, dialog, translation, sidecar, and UI.
packages/client/src/stores/chat.store.ts - Feature Hooks · Client hooks that coordinate API calls, state updates, and feature behavior.
packages/client/src/hooks/use-generate.ts - API Client · Shared client-side transport for server requests, streaming, and CSRF-aware calls.
packages/client/src/lib/api-client.ts - Server API · Main coordinator for routes, services, persistence, and integrations.
packages/server/src/app.ts - Routes · Feature-grouped request handlers for chat, game, generation, media, admin, and integrations.
packages/server/src/routes/index.ts - Services · Business logic for prompt assembly, agents, conversation, game, imports, media, and providers.
packages/server/src/services/prompt/assembler.ts - Prompt Pipeline · Macro expansion, prompt overrides, merger logic, and lore/context injection.
packages/server/src/services/prompt/assembler.ts - Agent Engine · Agent execution, knowledge routing, normalization, and autonomous behaviors.
packages/server/src/services/agents/agent-pipeline.ts - Game Engine · Combat, encounters, dice, map, time, weather, session, and checkpoint logic.
packages/server/src/services/game/session.service.ts - Local Store · File-backed persistence, schema, migrations, seeds, and storage adapters.
packages/server/src/db/file-backed-store.ts - Shared Contracts · Common schemas, types, constants, and utilities used by client and server.
packages/shared/src/index.ts - Macro Utils · Prompt, macro, regex, and generation helpers reused across runtimes.
packages/shared/src/utils/macro-engine.ts - LLM Adapters · Unified adapters for OpenAI, Anthropic, Google, OpenRouter, local sidecar, and compatible endpoints.
packages/server/src/services/llm/provider-registry.ts - Media Services · Asset manifests, sprites, backgrounds, image generation, and media handling.
packages/server/src/services/game/asset-manifest.service.ts - Security Layer · Basic auth, CSRF, IP allowlisting, rate limiting, privileged gating, and security headers.
packages/server/src/middleware/security-headers.ts - Sidecar Runtime · Local model runtime selection, process control, download, and inference services.
packages/server/src/services/sidecar/sidecar-runtime.service.ts
Platform
Packaging, launcher, and mobile/webview wrappers.
- Android Shell · Android app shell that wraps the local server in a WebView.
android/app/src/main/java/com/marinara/engine/MainActivity.java - Windows Launcher · Windows launcher and installer pipeline for local execution and distribution.
win/launcher/Program.cs - Docker Pack · Container and compose packaging for self-hosted deployment.
docker-compose.yml
Integrations
External integration packages around the engine.
- Home Assistant · External integration exposing engine entities, services, and webhooks to Home Assistant.
custom_components/marinara_engine/__init__.py
Connections 22
- Client UI → UI Stores: renders state · UI reads from and writes to global stores.
- Client UI → Feature Hooks: uses hooks · Feature components delegate orchestration to hooks.
- Feature Hooks → API Client: calls API · Hooks invoke server endpoints and streaming calls.
- API Client → Routes: requests · Client traffic is routed through HTTP and SSE endpoints.
- Server API → Security Layer: protects · Server applies policy and request boundary middleware.
- Server API → Routes: mounts · Application entrypoint registers feature routes.
- Routes → Services: delegates · Routes hand off work to business logic layers.
- Services → Prompt Pipeline: assembles prompts · Generation and conversation flows use the prompt pipeline.
- Services → Agent Engine: runs agents · Agent-related workflows execute through the agent engine.
- Services → Game Engine: simulates game · Game mode features use simulation and state services.
- Services → LLM Adapters: invokes models · Generation and analysis services call provider adapters.
- Services → Media Services: manages media · Asset and image workflows route through media services.
- Services → Sidecar Runtime: uses runtime · Local inference and sidecar lifecycle are coordinated here.
- Services → Local Store: persists data · Business logic reads and writes local persistent state.
- Prompt Pipeline → Macro Utils: reuses · Prompt assembly depends on shared macro and regex helpers.
- Routes → Shared Contracts: validates contracts · API boundaries use shared schemas and types.
- Feature Hooks → Shared Contracts: shares types · Feature hooks use the same contracts as the server.
- Local Store → Shared Contracts: stores models · Schemas and types define persisted entities.
- Android Shell → Server API: wraps · Android shell connects to the same local server.
- Windows Launcher → Server API: launches · Windows wrapper starts or packages the local runtime.
- Docker Pack → Server API: packages · Container build delivers the server and app together.
- Home Assistant → Routes: calls web API · Home Assistant integration treats the engine as an external service.