# pasta-devs/marinara-engine architecture

> Architecture diagram of the GitHub repository pasta-devs/marinara-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pasta-devs/marinara-engine
- Repository: https://github.com/pasta-devs/marinara-engine

## Overview

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: [`packages/server/src/services/prompt/assembler.ts`](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/prompt/assembler.ts) (Services), [`packages/server/src/app.ts`](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/app.ts) (Server API), [`packages/server/src/routes/index.ts`](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/routes/index.ts) (Routes), [`packages/client/src/hooks/use-generate.ts`](https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/hooks/use-generate.ts) (Feature Hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_packages["Packages"]
  node_client_app["Client UI<br/>React/Vite app<br/>[App.tsx]"]
  node_client_stores[("UI Stores<br/>state slices<br/>[chat.store.ts]")]
  node_client_hooks{{"Feature Hooks<br/>orchestration hooks<br/>[use-generate.ts]"}}
  node_client_api["API Client<br/>HTTP/SSE client<br/>[api-client.ts]"]
  node_server_app["Server API<br/>Node backend<br/>[app.ts]"]
  node_server_routes{{"Routes<br/>HTTP endpoints<br/>[index.ts]"}}
  node_server_services{{"Services<br/>workflow layer<br/>[assembler.ts]"}}
  node_server_prompt{{"Prompt Pipeline<br/>prompt assembly<br/>[assembler.ts]"}}
  node_server_agents{{"Agent Engine<br/>agent pipeline<br/>[agent-pipeline.ts]"}}
  node_server_game{{"Game Engine<br/>simulation services<br/>[session.service.ts]"}}
  node_server_store[("Local Store<br/>file-backed DB")]
  node_shared_contracts["Shared Contracts<br/>schemas/types<br/>[index.ts]"]
  node_shared_prompt_utils["Macro Utils<br/>shared logic<br/>[macro-engine.ts]"]
  node_server_llm{{"LLM Adapters<br/>provider registry"}}
  node_server_media{{"Media Services<br/>asset/image/audio"}}
  node_server_security{{"Security Layer<br/>middleware"}}
  node_server_sidecar{{"Sidecar Runtime<br/>local inference"}}
end

subgraph group_grp_platform["Platform"]
  node_platform_android["Android Shell<br/>WebView wrapper<br/>[MainActivity.java]"]
  node_platform_windows["Windows Launcher<br/>desktop wrapper<br/>[Program.cs]"]
  node_platform_docker["Docker Pack<br/>container build<br/>[docker-compose.yml]"]
end

subgraph group_grp_integrations["Integrations"]
  node_integration_ha["Home Assistant<br/>custom component<br/>[__init__.py]"]
end

node_client_app -->|"renders state"| node_client_stores
node_client_app -->|"uses hooks"| node_client_hooks
node_client_hooks -->|"calls API"| node_client_api
node_client_api -->|"requests"| node_server_routes
node_server_app -->|"protects"| node_server_security
node_server_app -->|"mounts"| node_server_routes
node_server_routes -->|"delegates"| node_server_services
node_server_services -->|"assembles prompts"| node_server_prompt
node_server_services -->|"runs agents"| node_server_agents
node_server_services -->|"simulates game"| node_server_game
node_server_services -->|"invokes models"| node_server_llm
node_server_services -->|"manages media"| node_server_media
node_server_services -->|"uses runtime"| node_server_sidecar
node_server_services -->|"persists data"| node_server_store
node_server_prompt -->|"reuses"| node_shared_prompt_utils
node_server_routes -->|"validates contracts"| node_shared_contracts
node_client_hooks -->|"shares types"| node_shared_contracts
node_server_store -->|"stores models"| node_shared_contracts
node_platform_android -->|"wraps"| node_server_app
node_platform_windows -->|"launches"| node_server_app
node_platform_docker -->|"packages"| node_server_app
node_integration_ha -->|"calls web API"| node_server_routes

click node_client_app "https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/App.tsx"
click node_client_stores "https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/stores/chat.store.ts"
click node_client_hooks "https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/hooks/use-generate.ts"
click node_client_api "https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/lib/api-client.ts"
click node_server_app "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/app.ts"
click node_server_routes "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/routes/index.ts"
click node_server_services "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/prompt/assembler.ts"
click node_server_prompt "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/prompt/assembler.ts"
click node_server_agents "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/agents/agent-pipeline.ts"
click node_server_game "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/game/session.service.ts"
click node_server_store "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/db/file-backed-store.ts"
click node_shared_contracts "https://github.com/pasta-devs/marinara-engine/blob/main/packages/shared/src/index.ts"
click node_shared_prompt_utils "https://github.com/pasta-devs/marinara-engine/blob/main/packages/shared/src/utils/macro-engine.ts"
click node_server_llm "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/llm/provider-registry.ts"
click node_server_media "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/game/asset-manifest.service.ts"
click node_server_security "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/middleware/security-headers.ts"
click node_server_sidecar "https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/sidecar/sidecar-runtime.service.ts"
click node_platform_android "https://github.com/pasta-devs/marinara-engine/blob/main/android/app/src/main/java/com/marinara/engine/MainActivity.java"
click node_platform_windows "https://github.com/pasta-devs/marinara-engine/blob/main/win/launcher/Program.cs"
click node_platform_docker "https://github.com/pasta-devs/marinara-engine/blob/main/docker-compose.yml"
click node_integration_ha "https://github.com/pasta-devs/marinara-engine/blob/main/custom_components/marinara_engine/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_app,node_client_stores,node_client_hooks,node_client_api,node_server_app,node_server_routes,node_server_services,node_server_prompt,node_server_agents,node_server_game,node_server_store,node_shared_contracts,node_shared_prompt_utils,node_server_llm,node_server_media,node_server_security,node_server_sidecar toneBlue
class node_platform_android,node_platform_windows,node_platform_docker toneAmber
class node_integration_ha toneMint
```

## Components

### Packages

Core monorepo packages for app runtime and shared contracts.

- [Client UI](https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/App.tsx): React/Vite app · Browser application for chat, game mode, assets, and settings. · `packages/client/src/App.tsx`
- [UI Stores](https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/stores/chat.store.ts): state slices · Global client state for chat, game, dialog, translation, sidecar, and UI. · `packages/client/src/stores/chat.store.ts`
- [Feature Hooks](https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/hooks/use-generate.ts): orchestration hooks · Client hooks that coordinate API calls, state updates, and feature behavior. · `packages/client/src/hooks/use-generate.ts`
- [API Client](https://github.com/pasta-devs/marinara-engine/blob/main/packages/client/src/lib/api-client.ts): HTTP/SSE client · Shared client-side transport for server requests, streaming, and CSRF-aware calls. · `packages/client/src/lib/api-client.ts`
- [Server API](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/app.ts): Node backend · Main coordinator for routes, services, persistence, and integrations. · `packages/server/src/app.ts`
- [Routes](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/routes/index.ts): HTTP endpoints · Feature-grouped request handlers for chat, game, generation, media, admin, and integrations. · `packages/server/src/routes/index.ts`
- [Services](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/prompt/assembler.ts): workflow layer · Business logic for prompt assembly, agents, conversation, game, imports, media, and providers. · `packages/server/src/services/prompt/assembler.ts`
- [Prompt Pipeline](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/prompt/assembler.ts): prompt assembly · Macro expansion, prompt overrides, merger logic, and lore/context injection. · `packages/server/src/services/prompt/assembler.ts`
- [Agent Engine](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/agents/agent-pipeline.ts): agent pipeline · Agent execution, knowledge routing, normalization, and autonomous behaviors. · `packages/server/src/services/agents/agent-pipeline.ts`
- [Game Engine](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/game/session.service.ts): simulation services · Combat, encounters, dice, map, time, weather, session, and checkpoint logic. · `packages/server/src/services/game/session.service.ts`
- [Local Store](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/db/file-backed-store.ts): file-backed DB · File-backed persistence, schema, migrations, seeds, and storage adapters. · `packages/server/src/db/file-backed-store.ts`
- [Shared Contracts](https://github.com/pasta-devs/marinara-engine/blob/main/packages/shared/src/index.ts): schemas/types · Common schemas, types, constants, and utilities used by client and server. · `packages/shared/src/index.ts`
- [Macro Utils](https://github.com/pasta-devs/marinara-engine/blob/main/packages/shared/src/utils/macro-engine.ts): shared logic · Prompt, macro, regex, and generation helpers reused across runtimes. · `packages/shared/src/utils/macro-engine.ts`
- [LLM Adapters](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/llm/provider-registry.ts): provider registry · Unified adapters for OpenAI, Anthropic, Google, OpenRouter, local sidecar, and compatible endpoints. · `packages/server/src/services/llm/provider-registry.ts`
- [Media Services](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/game/asset-manifest.service.ts): asset/image/audio · Asset manifests, sprites, backgrounds, image generation, and media handling. · `packages/server/src/services/game/asset-manifest.service.ts`
- [Security Layer](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/middleware/security-headers.ts): middleware · Basic auth, CSRF, IP allowlisting, rate limiting, privileged gating, and security headers. · `packages/server/src/middleware/security-headers.ts`
- [Sidecar Runtime](https://github.com/pasta-devs/marinara-engine/blob/main/packages/server/src/services/sidecar/sidecar-runtime.service.ts): local inference · 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](https://github.com/pasta-devs/marinara-engine/blob/main/android/app/src/main/java/com/marinara/engine/MainActivity.java): WebView wrapper · Android app shell that wraps the local server in a WebView. · `android/app/src/main/java/com/marinara/engine/MainActivity.java`
- [Windows Launcher](https://github.com/pasta-devs/marinara-engine/blob/main/win/launcher/Program.cs): desktop wrapper · Windows launcher and installer pipeline for local execution and distribution. · `win/launcher/Program.cs`
- [Docker Pack](https://github.com/pasta-devs/marinara-engine/blob/main/docker-compose.yml): container build · Container and compose packaging for self-hosted deployment. · `docker-compose.yml`

### Integrations

External integration packages around the engine.

- [Home Assistant](https://github.com/pasta-devs/marinara-engine/blob/main/custom_components/marinara_engine/__init__.py): custom component · External integration exposing engine entities, services, and webhooks to Home Assistant. · `custom_components/marinara_engine/__init__.py`

## Connections

- 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.
