Background Services
A well-built desktop app does a lot of work you don’t see. Auto-save, file monitoring, background indexing, periodic health checks, entity extraction on newly-edited text, cache warming, metrics collection — all of this happens in the background while you’re writing, and none of it should be visible to you unless something goes wrong. The test of a good background service is that you never notice it running. The test of a bad one is that you feel the UI freeze when it kicks in. Ishvana’s background services are built on the principle that the writing experience should never hitch because the backend is doing something. This page walks through what’s actually running behind the scenes, what each service is for, and when you’d ever need to think about one of them.
The services, one by one
Section titled “The services, one by one”Auto-save
Section titled “Auto-save”The most important background service, and the one you’d miss most if it stopped. Auto-save watches for unsaved changes in the editor and writes them to disk on a configurable interval — default is every 2 seconds, configurable from 0.5 to 10 seconds in Settings.
The save is incremental, not full-document. When you type a new word, only the change gets written. This means auto-save can happen frequently without any perceptible performance cost. On a modern SSD, a typical save takes under a millisecond.
Auto-save also handles focus-loss saves — when you Tab away from the editor to another panel, the current edits save immediately regardless of the interval. This catches the “I switched tabs and the app crashed” scenario by making sure the most recent state is always on disk before you navigate away.
Disable auto-save if you have a specific reason to (some authors prefer manual save for psychological reasons), but most users should leave it on. The cost is near-zero and the safety is significant.
File monitoring
Section titled “File monitoring”Ishvana watches the data/documents/ directory for file changes using the operating system’s native file watcher. If a file changes externally — you edited it in Word, a sync tool overwrote it, a backup system restored it — Ishvana detects the change and reloads the file from disk.
File monitoring is why you can edit a manuscript in both Ishvana and another tool and have the changes sync (eventually) without manual intervention. It’s also why a sync tool like Dropbox can push a version from another machine and have Ishvana pick up the change.
The file watcher runs continuously but is cheap — it’s OS-level, not a polling loop. It wakes up only when the OS says a file has actually changed.
Entity extraction
Section titled “Entity extraction”When you save a document (or paragraphs within it change), a background service runs the TF-IDF entity extractor on the changed text. It pulls out candidate entities — proper nouns that look like characters, places, items, factions — and matches them against your Legendry. Entities that already exist as lore entries get tagged as “known.” Entities that don’t get surfaced as “unlinked references” in the Insights panel.
Entity extraction is non-blocking. You don’t see it running and it doesn’t slow your editing. The results become available in the Insights panel when you open it, or they get picked up by the next Lorekeeper check if you run one.
Lore ML pipeline (on-demand)
Section titled “Lore ML pipeline (on-demand)”The full ML pipeline for the Legendry is not a continuous background service — it’s an on-demand batch job you trigger from Lore ML. But when it runs, it runs in the background and doesn’t block the UI.
The pipeline does clustering, similarity analysis, contradiction detection, anomaly detection, coverage analysis, maturity scoring, tag analysis, entity graph analysis, and health snapshot computation. For a large Legendry it can take a few minutes. During that time you can keep writing, browsing lore, and using other features — the pipeline runs in a thread pool separate from the main app.
When the pipeline finishes, the results get stored in SQLite and become available in the Lore ML panel. You don’t have to wait for it or watch it run.
Heartbeats
Section titled “Heartbeats”Various subsystems run periodic heartbeats — small recurring tasks that check on state, update timestamps, and collect metrics. Most heartbeats fire every 30 seconds or so. A few run more frequently:
- Desktop tab heartbeat. The Desktop overview refreshes timestamps and stale indicators on a 30-second heartbeat so “Edited 5 minutes ago” becomes “Edited 6 minutes ago” while you’re looking.
- Agent activity heartbeat. The Agent Overview panel polls for activity updates on a configurable interval.
- Cost tracking heartbeat. Cost tracking aggregates fresh data periodically so the Observability panel stays current without a manual refresh.
- Error log heartbeat. The Mime error subsystem periodically flushes buffered errors to disk.
Heartbeats are individually cheap. In aggregate they do add some constant background load, but it’s negligible on any hardware that can run Ishvana at all. If heartbeats become a problem, the fix is usually a specific heartbeat that’s misbehaving — check Error Tracking for errors from that service.
Backup snapshots
Section titled “Backup snapshots”Automatic backup snapshots run on a schedule you configure in Settings (hourly, daily, weekly, or off). When the scheduled time arrives, a background service creates a compressed copy of your main SQLite databases and any recently-changed files, stores it in data/backups/, and retains the last N snapshots (configurable).
Backup snapshots run at low priority and can be interrupted if you do something interactive. They’re designed to stay out of the way of your actual writing.
Session tracking
Section titled “Session tracking”Ishvana tracks your writing session state in the background — start time, active duration, word count added this session, goals progress, streaks. The session tracker updates on every save and on focus changes, so the analytics panel can show real-time progress.
Session tracking can be disabled in Settings if you don’t want any analytics collection. The cost of keeping it on is essentially zero — it’s a few database writes per minute during active editing.
Research web monitoring
Section titled “Research web monitoring”If you’ve set up web monitors in the Research module (URLs to watch for changes), a background service periodically polls those URLs and notifies you when content changes. The polling interval is per-monitor (default is every few hours) and the service runs idle between polls.
Web monitors are the most noticeable of the background services because they actually hit the network. If you’re on a flaky connection, a web monitor trying to poll can produce log entries in Error Tracking. The service is designed to fail silently on network errors — you won’t get a popup saying “web monitor failed,” just an entry in the error log if you care to look.
Email polling (if email is configured)
Section titled “Email polling (if email is configured)”The Email module has a background service that polls IMAP for new messages on a configurable interval. If you haven’t set up email accounts, this service does nothing. If you have, it’s what brings new messages into the local mail cache.
Email polling is the other service that actively hits the network. It inherits the same “fail silently on network errors” pattern as web monitors.
How to tell what’s running
Section titled “How to tell what’s running”You generally don’t need to know which background service is doing what at any given moment. The UI hides all of this. But if you want visibility:
- Error Tracking shows errors and warnings from any background service that’s having trouble. If a heartbeat is failing repeatedly, it shows up in the error log with its source.
- Agent Overview shows per-agent activity including background jobs kicked off by agents.
- Operational Stats in Etherforce Observability shows LLM-related background activity including any requests kicked off by background services that call a model.
For the routine case — everything is working, nothing to check — the background services are completely invisible. That’s the design goal.
What background services can’t do
Section titled “What background services can’t do”A few deliberate limits:
- Nothing blocks the UI. Any background service that tried to block the main event loop would violate the architecture. The frontend runs in Electron’s renderer, the backend runs as a separate process, and communication is over local HTTP — there’s a structural boundary that prevents backend work from freezing the UI.
- No service writes outside the data directory. Background services don’t touch files outside
data/. They can’t accidentally modify your Documents folder or your Desktop. The sandbox is enforced at the backend level. - No service runs without an active session. When you close Ishvana, all background services stop. There’s no persistent daemon that keeps running. The next time you open the app, the services restart from a clean state.
- No service escalates privileges. Everything runs as the same user that launched Ishvana. No background service can ask for admin rights or elevated permissions.
When to disable background services
Section titled “When to disable background services”Most background services should stay on. The few you might reasonably disable:
- Web monitors. If you’re not actively using Research’s monitoring feature and you don’t want network activity in the background, pause or delete your monitors.
- Email polling. If your email is configured but you don’t actually use Ishvana’s email features, removing the accounts stops the polling.
- Analytics. If you have privacy concerns about session tracking, you can disable it in Settings. The cost is that you lose the writing stats panel in Editorial Analysis.
- Backup snapshots. If you have an external backup solution and don’t want Ishvana’s built-in snapshots taking disk space, you can turn them off in Settings. Do not turn off backups entirely unless your external solution is rock solid.
Everything else should stay running. The cost is minimal and the functionality they provide is part of what makes Ishvana feel like a serious writing environment.