Engine

Most writing tools hide their internals. You open the app, you click buttons, things happen, and the machinery is a black box. For a web app with your data on someone else’s server, the black box is fine — you couldn’t poke at the internals anyway. For a desktop app where the data is yours and lives on your machine, the black box is unhelpful. You deserve to know what’s happening under the hood — where your manuscript actually lives, how the search finds things, what’s cached and what isn’t, which background services are running. Not because you need to touch any of it, but because understanding the machinery is the difference between trusting a tool and guessing at it. The Engine section is Ishvana’s answer to that. Every meaningful subsystem gets a page, written for the author who wants to understand rather than for the developer who wants to modify.

This section is educational, not configurational. For the live panels where you actually see engine behaviour (handler dispatch logs, cache stats, performance numbers), go to the Analysis workspace. For the settings where you actually change engine behaviour, go to Settings. This section is for the times you want to know why the machinery is built the way it is.

What’s in this section

Etherforce overview The dispatch layer for every Divinity Engine handler call in Ishvana.

Tool Registry How handlers and agent tools get registered and exposed for observability.

Data Storage Where your data actually lives — SQLite, ChromaDB, DOCX files, and the local-first architecture that keeps it yours.

Semantic Search Vector embeddings, ChromaDB, and how the app finds things by meaning instead of by keyword match.

Cache & Performance The in-memory cache, hardware tier detection, and everything that keeps the app fast.

Background Services Auto-save, file monitoring, monitored-feed polling, entity extraction — the work the app does when you're not watching.

The mental model

Ishvana is a desktop app, but structurally it’s a small stack:

Electron frontend. The Vue 3 renderer you see when you open the app. All the UI, all the editor, all the panels, all the keyboard shortcuts. This is what feels like “Ishvana” from a user perspective.
FastAPI backend. A local Python process that Electron spawns in the background. It handles everything that isn’t UI — data storage, the Divinity Engine, entity extraction, machine learning analysis, semantic search. The backend runs on a fixed local port (37737) and the frontend talks to it over HTTP.
Data layer. SQLite databases for structured data, ChromaDB for vector embeddings, DOCX files on disk for document content, and a few JSON/YAML files for configuration. All of it lives in a data directory on your machine.
The Divinity Engine. The local intelligence layer that powers every agent, scan, and analysis. Bundled handlers for consistency checking, prose analysis, lore graph work, generative replacements, and classification. No external service is contacted at runtime.
Etherforce. The dispatch layer between agents and the Divinity Engine handlers. Routes typed handler invocations, returns typed handler results, caches by content hash, surfaces streaming progress for long-running scans.
Background services. Auto-save, file watching, entity extraction, cache management, the monitored-feeds poller, the project-classifier trainer.

Everything else in this section is a deeper look at one of these layers.

Why it’s worth understanding

Two reasons.

First, trust. Ishvana’s design commitment is local-first data. Your manuscript, your lore, your project — all of it lives on your machine, in formats you can read with other tools. The Data Storage page tells you exactly what formats and exactly where. That’s the difference between “trust us, your data is safe” and “here is the specific directory, here are the specific file extensions, here is the schema if you want to verify.” The latter is what an author working on a long-term project deserves.

Second, diagnosis. When something isn’t working right, the black-box view gives you nothing. The transparent view gives you the layer where the problem lives. Is a scan slow? Check the Etherforce dispatch log to see which handler is taking time. Is the cache not hitting? Check Cache & Performance. Is a background service stalled? Check Background Services. The ability to localize a problem to a specific layer is worth hours of frustration on a bad day.

What this section isn’t

Not API documentation. If you want to build external tools that talk to Ishvana’s backend, that’s a different kind of doc not included here. The Engine section is for understanding what the app does on your behalf.
Not configuration guides. Configuration lives in Settings. The Engine section explains concepts; Settings explains how to change them.
Not developer onboarding. If you’re going to contribute code to Ishvana, you’d want technical documentation with module paths and class diagrams. The Engine section is written for authors who want to understand.

What used to live here

Older versions of this documentation included a Providers & Models page covering Anthropic, OpenRouter, and Ollama, plus a Context & Compression page about handling long LLM conversations. Both pages described a system that no longer exists. The Divinity Engine replaced the entire external-provider routing layer with bundled local handlers in 2026-04, so there are no providers to choose between, no per-model tier assignments to make, and no token-window pressure to compress around. The conceptual content from those pages is preserved in Etherforce overview — the dispatch layer is still real, it just dispatches handler invocations now instead of model calls.

What’s next

Etherforce overview Start here if your question is about the dispatch pipeline.

Data Storage Start here if your question is about where your data lives.

Semantic Search Start here if your question is about how the app finds things.