Services

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.