# siyabongadlamini/actual architecture

> Architecture diagram of the GitHub repository siyabongadlamini/actual, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siyabongadlamini/actual
- Repository: https://github.com/siyabongadlamini/actual

## Overview

Actual is a local-first personal-finance and envelope-budgeting application. A user works in the desktop client or another supported app to manage budget data; loot-core provides the cross-platform application behavior and SQLite storage, while cloud storage and the sync server support moving changes between devices. The tree and README establish these broad product boundaries, and excerpts show selected implementation links. Many feature modules and server integrations are indexed but unsampled, so only documented or directly evidenced relationships are drawn.

Main entry points: [`packages/sync-server/src/app.ts`](https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/src/app.ts) (Sync server), [`packages/loot-core/src/platform/server/sqlite/engine.wasm.ts`](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.wasm.ts) (WASM SQLite engine), [`packages/desktop-client/src/components/ManageRules.tsx`](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx) (Budget UI), [`packages/loot-core/src/server/accounts/app.ts`](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/accounts/app.ts) (Account management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_desktop["Desktop shell<br/>[index.ts]"]
  node_budget_ui["Budget UI<br/>[ManageRules.tsx]"]
  node_rules["Rules management<br/>[ManageRules.tsx]"]
  node_query_ui["Query manager<br/>[QueryManager.tsx]"]
  node_storage_toggle["Storage settings"]
  node_account_tree["Account navigation"]
end

subgraph group_core["Budget core"]
  node_accounts["Account management<br/>[app.ts]"]
  node_budgeting["Budget management<br/>[app.ts]"]
  node_schedules["Schedules<br/>[app.ts]"]
  node_dashboard["Dashboard<br/>[app.ts]"]
  node_query_model["Query model<br/>[query.ts]"]
  node_cloud_storage["Cloud file storage<br/>[cloud-storage.ts]"]
end

subgraph group_persistence["Local persistence"]
  node_sqlite_legacy[("Legacy SQLite engine")]
  node_sqlite_wasm[("WASM SQLite engine<br/>[engine.wasm.ts]")]
end

subgraph group_sync["Cloud sync"]
  node_sync_server["Sync server<br/>[app.ts]"]
  node_sync_entry["Server entry<br/>[app.ts]"]
  node_banking["Bank connections"]
end

subgraph group_interfaces["Developer interfaces"]
  node_api["Public API<br/>[methods.ts]"]
  node_api_query["API query builder<br/>[query.ts]"]
  node_cli["Command-line client<br/>[index.ts]"]
end

node_user(("Budget user"))

node_user -->|"manages budget"| node_budget_ui
node_desktop -.->|"hosts UI"| node_budget_ui
node_budget_ui -->|"opens rules"| node_rules
node_rules -->|"requests rules"| node_accounts
node_storage_toggle -.->|"selects backend"| node_sqlite_wasm
node_storage_toggle -.->|"selects backend"| node_sqlite_legacy
node_query_ui -.->|"configures queries"| node_query_model
node_account_tree -.->|"reorders accounts"| node_accounts
node_accounts -.->|"persists data"| node_sqlite_wasm
node_budgeting -.->|"persists data"| node_sqlite_wasm
node_schedules -.->|"persists data"| node_sqlite_wasm
node_dashboard -.->|"uses queries"| node_query_model
node_cloud_storage -->|"uploads files"| node_sync_server
node_cloud_storage -->|"lists files"| node_sync_server
node_sync_entry -->|"starts server"| node_sync_server
node_sync_server -->|"routes requests"| node_banking
node_api -->|"builds queries"| node_api_query
node_cli -.->|"uses API"| node_api

click node_desktop "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-electron/index.ts"
click node_budget_ui "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx"
click node_rules "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx"
click node_query_ui "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/formula/QueryManager.tsx"
click node_storage_toggle "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/settings/StorageBackendToggle.tsx"
click node_account_tree "https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx"
click node_accounts "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/accounts/app.ts"
click node_budgeting "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/budget/app.ts"
click node_schedules "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/schedules/app.ts"
click node_dashboard "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/dashboard/app.ts"
click node_query_model "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/shared/query.ts"
click node_cloud_storage "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/cloud-storage.ts"
click node_sqlite_legacy "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.sqljs.legacy.ts"
click node_sqlite_wasm "https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.wasm.ts"
click node_sync_server "https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/src/app.ts"
click node_sync_entry "https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/app.ts"
click node_banking "https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/src/app-gocardless/services/gocardless-service.ts"
click node_api "https://github.com/siyabongadlamini/actual/blob/master/packages/api/methods.ts"
click node_api_query "https://github.com/siyabongadlamini/actual/blob/master/packages/api/app/query.ts"
click node_cli "https://github.com/siyabongadlamini/actual/blob/master/packages/cli/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_budget_ui,node_rules,node_query_ui,node_storage_toggle,node_account_tree,node_user toneBlue
class node_accounts,node_budgeting,node_schedules,node_dashboard,node_query_model,node_cloud_storage toneAmber
class node_sqlite_legacy,node_sqlite_wasm toneMint
class node_sync_server,node_sync_entry,node_banking toneRose
class node_api,node_api_query,node_cli toneIndigo
```

## Components

### User clients

- [Desktop shell](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-electron/index.ts): `packages/desktop-electron/index.ts`
- [Budget UI](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx): `packages/desktop-client/src/components/ManageRules.tsx`
- [Rules management](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx): `packages/desktop-client/src/components/ManageRules.tsx`
- [Query manager](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/formula/QueryManager.tsx): `packages/desktop-client/src/components/formula/QueryManager.tsx`
- [Storage settings](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/settings/StorageBackendToggle.tsx): `packages/desktop-client/src/components/settings/StorageBackendToggle.tsx`
- [Account navigation](https://github.com/siyabongadlamini/actual/blob/master/packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx): `packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx`

### Budget core

- [Account management](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/accounts/app.ts): `packages/loot-core/src/server/accounts/app.ts`
- [Budget management](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/budget/app.ts): `packages/loot-core/src/server/budget/app.ts`
- [Schedules](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/schedules/app.ts): `packages/loot-core/src/server/schedules/app.ts`
- [Dashboard](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/dashboard/app.ts): `packages/loot-core/src/server/dashboard/app.ts`
- [Query model](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/shared/query.ts): `packages/loot-core/src/shared/query.ts`
- [Cloud file storage](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/server/cloud-storage.ts): `packages/loot-core/src/server/cloud-storage.ts`

### Local persistence

- [Legacy SQLite engine](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.sqljs.legacy.ts): `packages/loot-core/src/platform/server/sqlite/engine.sqljs.legacy.ts`
- [WASM SQLite engine](https://github.com/siyabongadlamini/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.wasm.ts): `packages/loot-core/src/platform/server/sqlite/engine.wasm.ts`

### Cloud sync

- [Sync server](https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/src/app.ts): `packages/sync-server/src/app.ts`
- [Server entry](https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/app.ts): `packages/sync-server/app.ts`
- [Bank connections](https://github.com/siyabongadlamini/actual/blob/master/packages/sync-server/src/app-gocardless/services/gocardless-service.ts): `packages/sync-server/src/app-gocardless/services/gocardless-service.ts`

### Developer interfaces

- [Public API](https://github.com/siyabongadlamini/actual/blob/master/packages/api/methods.ts): `packages/api/methods.ts`
- [API query builder](https://github.com/siyabongadlamini/actual/blob/master/packages/api/app/query.ts): `packages/api/app/query.ts`
- [Command-line client](https://github.com/siyabongadlamini/actual/blob/master/packages/cli/src/index.ts): `packages/cli/src/index.ts`

### Other components

- **Budget user**

## Connections

- Budget user → Budget UI: manages budget
- Desktop shell → Budget UI: hosts UI
- Budget UI → Rules management: opens rules (evidence: `packages/desktop-client/src/components/ManageRules.tsx`)
- Rules management → Account management: requests rules (evidence: `packages/desktop-client/src/components/ManageRules.tsx`)
- Storage settings → WASM SQLite engine: selects backend (evidence: `packages/desktop-client/src/components/settings/StorageBackendToggle.tsx`)
- Storage settings → Legacy SQLite engine: selects backend (evidence: `packages/desktop-client/src/components/settings/StorageBackendToggle.tsx`)
- Query manager → Query model: configures queries
- Account navigation → Account management: reorders accounts
- Account management → WASM SQLite engine: persists data
- Budget management → WASM SQLite engine: persists data
- Schedules → WASM SQLite engine: persists data
- Dashboard → Query model: uses queries
- Cloud file storage → Sync server: uploads files (evidence: `packages/loot-core/src/server/cloud-storage.ts`)
- Cloud file storage → Sync server: lists files (evidence: `packages/loot-core/src/server/cloud-storage.ts`)
- Server entry → Sync server: starts server (evidence: `packages/sync-server/app.ts`)
- Sync server → Bank connections: routes requests (evidence: `packages/sync-server/src/app.ts`)
- Public API → API query builder: builds queries (evidence: `packages/api/methods.ts`)
- Command-line client → Public API: uses API
