# actualbudget/actual architecture

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

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

## Overview

Actual is a local-first personal finance and envelope-budgeting application. Users manage accounts, transactions, budgets and rules in a desktop or other client; the shared loot-core provides application behavior, while the sync server enables changes to move between devices. The repository also includes bank-connection integrations and cloud-file handling. The README documents the package split and local-first sync, and excerpts show selected client, core and server calls. Several important modules are indexed but unsampled, so their internal connections are omitted rather than inferred.

Main entry points: [`packages/sync-server/src/app.ts`](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app.ts) (Sync server), [`packages/loot-core/src/server/accounts/app.ts`](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/accounts/app.ts) (Account operations), [`packages/loot-core/src/server/cloud-storage.ts`](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/cloud-storage.ts) (Cloud file handling), [`packages/desktop-electron/index.ts`](https://github.com/actualbudget/actual/blob/master/packages/desktop-electron/index.ts) (Desktop shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_desktop["Desktop shell<br/>[index.ts]"]
  node_backend_loader["Backend loader<br/>[server.ts]"]
  node_rules_ui["Rules manager<br/>[ManageRules.tsx]"]
  node_account_tree["Account tree drag-drop"]
  node_transactions_table["Transactions table<br/>[table.tsx]"]
  node_virtual_list["Virtual list<br/>[FixedSizeList.tsx]"]
  node_query_manager["Query manager<br/>[QueryManager.tsx]"]
end

subgraph group_finance["Finance Core"]
  node_core_accounts["Account operations<br/>[app.ts]"]
  node_account_sync["Account sync<br/>[sync.ts]"]
  node_budget["Budget operations<br/>[app.ts]"]
  node_schedules["Schedule operations<br/>[app.ts]"]
  node_schedule_finder["Schedule finder<br/>[find-schedules.ts]"]
  node_reports["Reports<br/>[app.ts]"]
  node_dashboard["Dashboard<br/>[app.ts]"]
  node_auth["Authentication<br/>[app.ts]"]
end

subgraph group_storage["Local Data"]
  node_budget_files["Budget files<br/>[app.ts]"]
  node_cloud_files["Cloud file handling<br/>[cloud-storage.ts]"]
  node_sqlite_legacy["Legacy SQLite engine"]
  node_sqlite_wasm["WASM SQLite engine<br/>[engine.wasm.ts]"]
end

subgraph group_sync["Sync Services"]
  node_sync_server["Sync server<br/>[app.ts]"]
  node_sync_routes["Sync routes<br/>[app-sync.ts]"]
  node_sync_files["Sync file service<br/>[files-service.ts]"]
end

subgraph group_integrations["Bank Integrations"]
  node_bank_gocardless["GoCardless integration<br/>[app-gocardless.ts]"]
  node_gocardless_service["GoCardless service"]
  node_enable_banking["Enable Banking"]
  node_akahu["Akahu integration<br/>[app-akahu.ts]"]
  node_pluggy["Pluggy integration<br/>[app-pluggyai.js]"]
  node_simplefin["SimpleFIN integration<br/>[app-simplefin.js]"]
end

node_user(("Budget user"))
node_bank_provider(("Banking provider"))

node_user -.->|"uses"| node_desktop
node_desktop -->|"starts backend"| node_backend_loader
node_backend_loader -.->|"loads core bundle"| node_core_accounts
node_rules_ui -.->|"requests rule data"| node_core_accounts
node_account_tree -.->|"updates account layout"| node_core_accounts
node_transactions_table -->|"renders rows"| node_virtual_list
node_core_accounts -->|"syncs account"| node_account_sync
node_schedules -->|"finds schedules"| node_schedule_finder
node_cloud_files -->|"uploads files"| node_sync_server
node_cloud_files -->|"lists files"| node_sync_server
node_cloud_files -->|"downloads files"| node_sync_server
node_sync_server -->|"registers routes"| node_sync_routes
node_sync_server -->|"registers integration"| node_bank_gocardless
node_sync_server -->|"registers integration"| node_enable_banking
node_sync_server -->|"registers integration"| node_akahu
node_sync_server -->|"registers integration"| node_pluggy
node_sync_server -->|"registers integration"| node_simplefin
node_gocardless_service -.->|"contacts provider"| node_bank_provider
node_core_accounts -.->|"connects accounts"| node_bank_provider

click node_desktop "https://github.com/actualbudget/actual/blob/master/packages/desktop-electron/index.ts"
click node_backend_loader "https://github.com/actualbudget/actual/blob/master/packages/desktop-electron/server.ts"
click node_rules_ui "https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx"
click node_account_tree "https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx"
click node_transactions_table "https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/table.tsx"
click node_virtual_list "https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/FixedSizeList.tsx"
click node_query_manager "https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/formula/QueryManager.tsx"
click node_core_accounts "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/accounts/app.ts"
click node_account_sync "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/accounts/sync.ts"
click node_budget "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/budget/app.ts"
click node_schedules "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/schedules/app.ts"
click node_schedule_finder "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/schedules/find-schedules.ts"
click node_reports "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/reports/app.ts"
click node_dashboard "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/dashboard/app.ts"
click node_auth "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/auth/app.ts"
click node_budget_files "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/budgetfiles/app.ts"
click node_cloud_files "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/cloud-storage.ts"
click node_sqlite_legacy "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.sqljs.legacy.ts"
click node_sqlite_wasm "https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.wasm.ts"
click node_sync_server "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app.ts"
click node_sync_routes "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-sync.ts"
click node_sync_files "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-sync/services/files-service.ts"
click node_bank_gocardless "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/app-gocardless.ts"
click node_gocardless_service "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/services/gocardless-service.ts"
click node_enable_banking "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-enablebanking/app-enablebanking.ts"
click node_akahu "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-akahu/app-akahu.ts"
click node_pluggy "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-pluggyai/app-pluggyai.js"
click node_simplefin "https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-simplefin/app-simplefin.js"

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_backend_loader,node_rules_ui,node_account_tree,node_transactions_table,node_virtual_list,node_query_manager,node_user toneBlue
class node_core_accounts,node_account_sync,node_budget,node_schedules,node_schedule_finder,node_reports,node_dashboard,node_auth toneAmber
class node_budget_files,node_cloud_files,node_sqlite_legacy,node_sqlite_wasm toneMint
class node_sync_server,node_sync_routes,node_sync_files toneRose
class node_bank_gocardless,node_gocardless_service,node_enable_banking,node_akahu,node_pluggy,node_simplefin,node_bank_provider toneIndigo
```

## Components

### Clients

- [Desktop shell](https://github.com/actualbudget/actual/blob/master/packages/desktop-electron/index.ts): `packages/desktop-electron/index.ts`
- [Backend loader](https://github.com/actualbudget/actual/blob/master/packages/desktop-electron/server.ts): `packages/desktop-electron/server.ts`
- [Rules manager](https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/ManageRules.tsx): `packages/desktop-client/src/components/ManageRules.tsx`
- [Account tree drag-drop](https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx): `packages/desktop-client/src/components/sidebar/redesign/useAccountTreeDragAndDrop.tsx`
- [Transactions table](https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/table.tsx): `packages/desktop-client/src/components/table.tsx`
- [Virtual list](https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/FixedSizeList.tsx): `packages/desktop-client/src/components/FixedSizeList.tsx`
- [Query manager](https://github.com/actualbudget/actual/blob/master/packages/desktop-client/src/components/formula/QueryManager.tsx): `packages/desktop-client/src/components/formula/QueryManager.tsx`

### Finance Core

- [Account operations](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/accounts/app.ts): `packages/loot-core/src/server/accounts/app.ts`
- [Account sync](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/accounts/sync.ts): `packages/loot-core/src/server/accounts/sync.ts`
- [Budget operations](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/budget/app.ts): `packages/loot-core/src/server/budget/app.ts`
- [Schedule operations](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/schedules/app.ts): `packages/loot-core/src/server/schedules/app.ts`
- [Schedule finder](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/schedules/find-schedules.ts): `packages/loot-core/src/server/schedules/find-schedules.ts`
- [Reports](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/reports/app.ts): `packages/loot-core/src/server/reports/app.ts`
- [Dashboard](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/dashboard/app.ts): `packages/loot-core/src/server/dashboard/app.ts`
- [Authentication](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/auth/app.ts): `packages/loot-core/src/server/auth/app.ts`

### Local Data

- [Budget files](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/budgetfiles/app.ts): `packages/loot-core/src/server/budgetfiles/app.ts`
- [Cloud file handling](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/cloud-storage.ts): `packages/loot-core/src/server/cloud-storage.ts`
- [Legacy SQLite engine](https://github.com/actualbudget/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/actualbudget/actual/blob/master/packages/loot-core/src/platform/server/sqlite/engine.wasm.ts): `packages/loot-core/src/platform/server/sqlite/engine.wasm.ts`

### Sync Services

- [Sync server](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app.ts): `packages/sync-server/src/app.ts`
- [Sync routes](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-sync.ts): `packages/sync-server/src/app-sync.ts`
- [Sync file service](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-sync/services/files-service.ts): `packages/sync-server/src/app-sync/services/files-service.ts`

### Bank Integrations

- [GoCardless integration](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/app-gocardless.ts): `packages/sync-server/src/app-gocardless/app-gocardless.ts`
- [GoCardless service](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/services/gocardless-service.ts): `packages/sync-server/src/app-gocardless/services/gocardless-service.ts`
- [Enable Banking](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-enablebanking/app-enablebanking.ts): `packages/sync-server/src/app-enablebanking/app-enablebanking.ts`
- [Akahu integration](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-akahu/app-akahu.ts): `packages/sync-server/src/app-akahu/app-akahu.ts`
- [Pluggy integration](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-pluggyai/app-pluggyai.js): `packages/sync-server/src/app-pluggyai/app-pluggyai.js`
- [SimpleFIN integration](https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-simplefin/app-simplefin.js): `packages/sync-server/src/app-simplefin/app-simplefin.js`

### Other components

- **Budget user**
- **Banking provider**

## Connections

- Budget user → Desktop shell: uses
- Desktop shell → Backend loader: starts backend (evidence: `packages/desktop-electron/index.ts`)
- Backend loader → Account operations: loads core bundle (evidence: `packages/desktop-electron/server.ts`)
- Rules manager → Account operations: requests rule data (evidence: `packages/desktop-client/src/components/ManageRules.tsx`)
- Account tree drag-drop → Account operations: updates account layout
- Transactions table → Virtual list: renders rows (evidence: `packages/desktop-client/src/components/table.tsx`)
- Account operations → Account sync: syncs account (evidence: `packages/loot-core/src/server/accounts/app.ts`)
- Schedule operations → Schedule finder: finds schedules (evidence: `packages/loot-core/src/server/schedules/app.ts`)
- Cloud file handling → Sync server: uploads files (evidence: `packages/loot-core/src/server/cloud-storage.ts`)
- Cloud file handling → Sync server: lists files (evidence: `packages/loot-core/src/server/cloud-storage.ts`)
- Cloud file handling → Sync server: downloads files (evidence: `packages/loot-core/src/server/cloud-storage.ts`)
- Sync server → Sync routes: registers routes (evidence: `packages/sync-server/src/app.ts`)
- Sync server → GoCardless integration: registers integration (evidence: `packages/sync-server/src/app.ts`)
- Sync server → Enable Banking: registers integration (evidence: `packages/sync-server/src/app.ts`)
- Sync server → Akahu integration: registers integration (evidence: `packages/sync-server/src/app.ts`)
- Sync server → Pluggy integration: registers integration (evidence: `packages/sync-server/src/app.ts`)
- Sync server → SimpleFIN integration: registers integration (evidence: `packages/sync-server/src/app.ts`)
- GoCardless service → Banking provider: contacts provider
- Account operations → Banking provider: connects accounts
