Architecture

Architecture

High-level structure of Cultiva 1.7.0 · Linden.

---

Process model (Electron)

flowchart TB
  subgraph Main["Main process"]
    IPC[IPC handlers]
    FS[File I/O / plugin install]
    UPD[electron-updater]
  end
  subgraph Renderer["Renderer (Vite bundle)"]
    APP[app controllers]
    PM[plugin-manager]
    IDB[(IndexedDB)]
    MW[Main window DOM]
  end
  subgraph Sandbox["Plugin sandbox iframe"]
    PLG[plugin index.js]
  end
  Main <-->|IPC| Renderer
  PM -->|postMessage RPC| Sandbox
  PM -->|inject CSS / mount UI| MW
  APP --> IDB
  PLG -->|storage/ui/data RPC| PM

Loading

Process	Key files
Main	electron/main.js, IPC for plugin file read, HTTP proxy
Renderer	src/main.js, src/app/*, src/core/*
Preload	electron/preload.js — exposes safe window.electron bridge

---

Data layer

• IndexedDB — habits, settings, completion history
• localStorage — small settings bridge where needed
• userData/ — plugin installs, auto-backups (ZIP), custom photos

Modules: src/modules/habits.js, storage helpers, migration on version bump.

---

Plugin runtime

1. Fetch registry.json from configured URL.
2. Verify sha256 for each file in plugin entry.
3. Download to userData/cultiva-plugins/<id>/.
4. Create PluginSandboxHost iframe (sandbox="allow-scripts").
5. Execute plugin as new Function('context', 'hooks', source).
6. Wire RPC allowlist in plugin-rpc.js based on manifest.permissions.
7. Bridge UI calls to main window (header, garden, sheets).

Key files:

• src/core/plugin-manager.js
• src/core/plugin-sandbox-host.js
• src/core/plugin-rpc.js
• src/app/plugins-ui.js

---

UI structure

View	Entry
Garden (home)	src/index.html + src/app/garden*.js
Calendar	src/calendar.html
Settings	Modal overlay in main window

Styling: CSS variables in src/styles/main.css — themes swap variable sets.

---

Build pipeline

npm ci → vite build → electron-builder (NSIS + portable)

CI: GitHub Actions for tests, Dependabot, npm audit.

---

Security boundaries

Asset	Access
Habit data	Renderer only — plugins via hooks, not direct DB
Network	Gated by manifest.permissions.network
Filesystem	Main process path guards for plugin install dir
Sandbox	No nodeIntegration, no direct DOM

See Privacy and Security.