Modules

KatanOS is module-driven. Module metadata and enable/disable rules are defined in services/modules.ts.

Registry Contract

interface ModuleDefinition {
  id: ModuleId;
  labelKey: string;
  descriptionKey: string;
  icon: LucideIcon;
  routes: string[];
  widgets: WidgetId[];
  dependencies: ModuleId[];
  defaultEnabled: boolean;
  canDisable: boolean;
}

Important rules:

• dashboard is always visible (injected nav item, not part of ModuleId union)

• calendar is core (canDisable: false)

• other modules are controlled through user.modulesConfig

• widget availability is derived from enabled modules plus core widgets

Navigation order (MODULE_NAV_ORDER):

1. calendar (agenda)

2. contacts

3. todo

4. journal

5. habits

6. finance

7. bookshelf

8. vault

9. games

Dashboard

File: pages/Dashboard.tsx

Primary purpose:

• home overview combining weather, schedule, favorites, finance summary, quote, and pomodoro

Data sources:

• db.events.list

• db.transactions.list

• db.contacts.list

• weather services (getWeather, searchCities, getCityFromCoords)

Widgets and behavior:

• clock + greeting block

• weather panel with forecast popup and city search

• on-this-day ticker (Wikipedia API)

• rotating daily quote (services/quotes.ts)

• next event card

• today events list (opens agenda event)

• favorites list with click-to-copy phone/email and contact deep-link

• finance mini-summary with recent transactions and deep-link to finance

• embedded pomodoro widget

Widget gating:

• todayEvents shown only if calendar widgets are available

• favorites shown only if contacts module is enabled

• finance block shown only if finance module is enabled

Persistence and keys:

• weather location: katanos_weather_loc_<userId>

External APIs used directly in page:

• https://ipapi.co/json/

• https://<lang>.wikipedia.org/api/rest_v1/feed/onthisday/events/MM/DD

Agenda (Calendar)

File: pages/Agenda.tsx Route: agenda (module id calendar)

Views:

• month

• week (hour grid)

• day (hour grid)

• list (grouped by month)

Core behavior:

• create/edit/delete events

• drag-and-drop rescheduling in month/week/day views

• recurrence generation on create:

  • daily: 7 instances

  • weekly: 4 instances

  • monthly: 6 instances

• category-aware coloring and labels via calendarCategories

• location search suggestions via searchPlaces

• optional AI event parsing via parseCalendarEvent

• weather icon overlays per day from saved location

Data model:

• uses CalendarEvent records in chronos_events

Persistence and keys:

• reads katanos_weather_loc_<userId> for weather overlays

Todo

File: pages/Todo.tsx Route: todo

Submodes:

• board: draggable sticky-note tasks

• checklist: named checklists with ordered items

Board behavior:

• add note in selected color

• toggle completion

• inline edit

• drag/drop absolute position updates

• auto-arrange layout

• clear completed

Checklist behavior:

• create/delete checklist

• add/remove/toggle checklist items

• item order stored in each checklist item

Data model:

• board uses TodoItem (chronos_todos)

• checklist uses Checklist (chronos_checklists)

Finance

File: pages/Finance.tsx Route: finance

Tabs:

• overview

• transactions

• planning

Domains handled:

• transactions

• budgets

• goals

• debts

• recurring entries

Key behavior:

• transaction CRUD (with tags)

• recurring autoposting on load

  • for each recurring rule, generates pending transactions up to today

  • advances nextDate using weekly/monthly/yearly progression

• goal contribution workflow (quick and custom)

• debt payment workflow

  • updates debt balance

  • writes matching expense transaction

• CSV export for filtered transactions

• analytics charts via useFinanceCharts

• AI financial coaching via askGeminiFinance

Data model:

• Transaction (chronos_transactions)

• FinanceBudget (chronos_finance_budgets)

• FinanceGoal (chronos_finance_goals)

• FinanceDebt (chronos_finance_debts)

• FinanceRecurring (chronos_finance_recurring)

Contacts

File: pages/Contacts.tsx Route: contacts

Core behavior:

• contact CRUD

• favorite toggle

• avatar upload (data URL)

• tags and tag filtering

• live search by name/email/tag

• click-to-copy for phone/email

• open external links (socials/web/email)

Data model:

• Contact (chronos_contacts)

Habits

File: pages/Habits.tsx Route: habits

Core behavior:

• habit CRUD with color

• day-level completion (logs) and skip (skips)

• skip and log are mutually exclusive for same day

• streak calculation respects skips

• weekly chart and consistency calculations

• achievement system with unlock notifications

Achievement thresholds (from code logic):

• habit count milestones (1, 3, 5)

• streak milestones (3, 7, 14, 30, 60)

• consistency milestones (100% for >=5 and >=14 days)

• account age milestones (>=30, >=60 days)

Data model:

• Habit (chronos_habits)

Journal

File: pages/Journal.tsx Route: journal

Core behavior:

• rich text editor (contenteditable + command API)

• emoji sprite insertion with fallback text rendering

• mood assignment (default + user-defined moods)

• filtering by search and mood tags

• autosave/update of normalized HTML content

• optional AI analysis (analyzeJournalEntry) to infer mood + reflection

Data model:

• JournalEntry (chronos_journal)

• User.journalMoods for custom moods

Notable implementation detail:

• entry content is stored as HTML; legacy plain text is normalized on load.

Bookshelf

File: pages/Bookshelf.tsx Route: bookshelf

Statuses:

• tobuy

• toread

• read

Core behavior:

• add books from Google Books search

• add books manually (including uploaded cover image)

• duplicate prevention by title+author

• rating, notes, start/finish dates

• drag-and-drop reorder within tobuy and toread (sortOrder)

• reading statistics and yearly goal tracking

• CSV export

Persistence and keys:

• reading goal key: katanos.readingGoal.<userId>

External API:

• https://www.googleapis.com/books/v1/volumes

Vault

File: pages/Vault.tsx Route: vault

Core behavior:

• first-run setup (create encrypted vault)

• unlock with master password

• recovery flow with recovery code + password reset

• item types: login, note, card

• in-session lock (clears decrypted state + master key from component state)

Cryptography operations (service-backed):

• create: createVault

• unlock: unlockVault

• recover: recoverVault

• save: saveVault

• reset password: resetVaultPassword

• derive session key: getMasterKey

Data model:

• encrypted payload stored in chronos_vault

Games

File: pages/Games.tsx Route: games

Launcher behavior:

• shows game catalog cards

• mounts selected game component

• Escape exits active game back to catalog

Implemented games (components/GameModules.tsx):

• Snake

• Shooter

• Breaker

• Reflex

• TicTacToe

• Memory

• Miner

Persistence:

• game-specific localStorage keys under katanos_game_*_<userId>

Login and Access Control

File: pages/Login.tsx

Behavior:

• login and registration UI

• required username/password

• registration requires secret question + answer

• password reset flow:

  • load question by username

  • validate answer

  • set new password

• login language selector persists katanos_last_login_lang

• supports custom login background via katanos_login_bg

Module Extension Checklist

To add a new module safely:

1. Add module metadata to services/modules.ts.

2. Add page component under pages/.

3. Wire page switch in App.tsx.

4. Add nav labels/translations.

5. Add or gate widgets in modulesService if needed.

6. Update docs and tests.