circle-exclamation
KatanOS will not receive any updates at the moment, which is why I decided to make it open source.

computer-speakerServices

KatanOS keeps non-visual logic in services/.

This page is the implementation-level map of each service and how modules use it.

Core Persistence

services/storage.ts

Raw storage adapter.

Responsibilities:

  • IndexedDB init and migration from localStorage

  • in-memory cache of key/value pairs

  • fallback behavior when IndexedDB is unavailable

Exports:

  • initStorage

  • storageGetRaw

  • storageSetRaw

  • storageRemoveRaw

  • getStorageStatus

services/db.ts

Typed domain data service.

Major API groups:

  • auth and profile settings

  • all module CRUD namespaces

  • backup payload creation

  • restore

  • autosave snapshot trigger

Notable behavior:

  • user filtering by userId

  • pbkdf2 hashing where available

  • API-key encryption via secrets.ts

Security and Secrets

services/vault.ts

Cryptographic implementation for encrypted vaults.

Core exports:

  • createVault(userId, password, initialData?)

  • unlockVault(vault, password)

  • recoverVault(vault, recoveryCode)

  • saveVault(data, masterKey, originalVault)

  • resetVaultPassword(vault, recoveryCode, newPassword)

  • getMasterKey(vault, password)

Crypto parameters:

  • AES-GCM 256

  • PBKDF2-SHA256

  • iterations: 300000

  • salt: 16 bytes

  • IV: 12 bytes

services/secrets.ts

Secret wrapper helpers for values like Gemini API keys.

Exports:

  • isEncryptedSecret

  • encryptSecretValue

  • decryptSecretValue

  • resolveSecretValue

Behavior:

  • uses prefix enc$

  • prefers Electron safeStorage bridge when available

  • falls back to plain text behavior when unavailable

Backup and Scheduling

services/backup.ts

Backup orchestration and scheduler.

Types:

  • BackupResult

  • BackupFileInfo

  • BackupManifest

Public API:

  • backupService.getDefaultSettings()

  • backupService.triggerBackupNow(userId, settings)

  • backupService.applyRetentionPolicy(settings)

  • backupService.getBackupHistory(folderPath)

  • backupService.startScheduler(user)

  • backupService.stopScheduler()

  • backupService.selectBackupFolder()

  • backupService.getIntervalLabel(interval, lang)

Scheduler:

  • exposed as backupScheduler

  • can run on startup and periodic interval

  • updates user.backupSettings.lastBackupAt/lastBackupStatus

Module and Widget Governance

services/modules.ts

Defines module registry and widget availability rules.

Key exports:

  • MODULE_REGISTRY

  • MODULE_NAV_ORDER

  • WIDGET_LABELS

  • modulesService

modulesService capabilities:

  • get modules for user

  • module enable checks

  • nav item generation

  • route accessibility helper

  • available widget list

  • dashboard layout defaults/sanitization/reorder/toggle

Categories and Label Resolution

services/calendarCategories.ts

  • default calendar categories

  • legacy icon to emoji migration helper

  • per-user merged category list

  • fallback resolution to default category id

services/financeCategories.ts

  • default finance category ids

  • localized labels

  • label fallback for custom categories

AI Integrations

services/gemini.ts

Public exports:

  • askGeminiPlaces

  • askGeminiFinance

  • analyzeJournalEntry

  • parseCalendarEvent

Usage map:

  • Maps Assistant -> places

  • Finance -> coaching insights

  • Journal -> mood/reflection

  • Agenda -> natural-language event parsing

Weather and Geolocation

services/weather.ts

Public exports:

  • getWeather

  • searchCities

  • getCityFromCoords

  • searchPlaces

  • getWeatherCodeDescription

Data providers:

  • Open-Meteo forecast/geocoding

  • OpenStreetMap Nominatim

Localization and Theming

services/translations.ts + services/useTranslation.ts

  • supported languages: it, en, fr, es, de

  • t(key, lang) translation resolver

  • getTranslationValue for non-string dictionary values

  • convenience hook useTranslation

services/themes.ts

  • predefined theme catalog (THEME_OPTIONS)

  • default theme id (default)

  • helper getThemeOption

services/localSettings.ts

Pre-auth UI preferences in localStorage:

  • last login language

  • last login theme

  • login background

Other Utility Services

services/PomodoroContext.tsx

State engine for pomodoro timer logic and persistence.

services/quotes.ts

Localized random quote retrieval.

services/avatar.ts

Deterministic SVG avatar generation from username.

services/emojiSprite.ts

Emoji sheet index and coordinate lookup for sprite rendering.

Last updated

Was this helpful?