# junaid-nazir-828/actual_budget architecture

> Architecture diagram of the GitHub repository junaid-nazir-828/actual_budget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/junaid-nazir-828/actual_budget
- Repository: https://github.com/junaid-nazir-828/actual_budget

## Overview

##### Project type and purpose
- This is a local-first, personal-finance full-stack application (“Actual”) organized as a Yarn/TypeScript monorepo.
- Core logic lives in the “loot-core” package. A React-based web UI (“desktop-client”) is wrapped by an Electron shell (“desktop-electron”) for desktop installs. A standalone Node.js “sync-server” handles multi-device synchronization via CRDT messages.

##### High-level file-structure analysis
- Top-level: workspace config (.gitignore, Dockerfile, GitHub workflows) and helper scripts in bin/.
- packages/
– api: lightweight HTTP API (TypeScript) for remote calls.
– crdt: library for generating/merging synchronization messages.
– desktop-client: React + Vite front end, packaged for web or Electron.
– desktop-electron: Electron main/preload scripts, bundling the desktop-client and launching a local Node server.
– loot-core: core application logic (platform-agnostic), persistence (SQLite/IndexedDB), business rules, migrations.
– sync-server: Node.js backend (Express-style) that stores sync messages, manages user accounts (OpenID/password), bank-sync adapters (GoCardless, SimpleFin, PluggyAI), and exposes migration scripts.

##### README insights
- Project split into three “main” packages: loot-core (core engine), desktop-client (UI), desktop-electron (desktop app).
- Local-first design: runs locally with optional remote sync.
- External docs cover installation, envelope budgeting concept, community/contributing links.

a. Main components
– User Interface: React application in desktop-client (also served via web)
– Desktop Shell: Electron runtime (desktop-electron) hosting the React UI and spawning a local Node process
– Core Engine: loot-core library (shared JS code)
– Local Persistence: SQLite file (Electron) or IndexedDB (web)
– CRDT Sync Library: crdt package invoked by loot-core to build sync payloads
– Remote Sync Server: sync-server service (Node.js + PostgreSQL/SQLite)
– External Integrations: GoCardless, SimpleFin, PluggyAI adapters in sync-server
– Optional HTTP API: packages/api for headless or hosted deployments

b. Relationships & interactions
1. User clicks in React UI → calls into loot-core client APIs (via direct import in web, via IPC/HTTP in Electron).
2. loot-core performs business logic, reads/writes local DB, and updates in-memory state.
3. On sync event: loot-core/crdt generates a sync message → HTTP POST to remote sync-server.
4. sync-server persists message, merges it server-side, and returns any new messages.
5. loot-core applies incoming messages, updating local store.
6. External services (GoCardless, etc.) are orchestrated by sync-server to fetch bank transactions and surface them back through sync.

c. Architectural patterns & design principles
– Monorepo with clearly separated packages for UI, core, server, CRDT.
– Local-first architecture with eventual consistency via CRDT-based synchronization.
– Platform abstraction: loot-core uses adapter interfaces to support Electron (SQLite) or browser (IndexedDB).
– Modular sync-server: plugin-style bank adapters and OpenID/password auth.

d. Key technologies/frameworks
– TypeScript, Node.js, React, Electron, Vite
– Yarn workspaces, Docker, DevContainer
– SQLite (server & Electron) and IndexedDB (web)
– CRDT sync (packages/crdt)
– Express-style Node server for sync-server
– GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::external
    subgraph "UI Layer"
        ReactUI["React UI"]:::frontend
        ElectronMain["Electron Main"]:::frontend
        Preload["Preload Script"]:::frontend
    end

    %% Core and Persistence
    subgraph "Core Engine & Persistence"
        BL["Business Logic"]:::core
        PA["Persistence Adapter"]:::core
        SQLiteDB["SQLite (local)"]:::database
        IndexedDB["IndexedDB (web)"]:::database
    end

    %% Sync Modules
    subgraph "Sync Components"
        CRDT["CRDT Sync Module"]:::sync
        subgraph "Local Node Server"
            LocalServer["Bundled Node Server"]:::sync
            LocalMsgStore["Local Message Store"]:::database
        end
    end

    %% Remote Sync Server
    subgraph "Sync Server (Node.js)" 
        Auth["Auth Module"]:::sync
        subgraph "Bank-Sync Adapters"
            GoCardless["GoCardless Adapter"]:::external
            SimpleFin["SimpleFin Adapter"]:::external
            PluggyAI["PluggyAI Adapter"]:::external
        end
        MsgStore["Message Store"]:::database
        Migrations["Migrations & Scripts"]:::sync
    end

    %% Optional API
    API["HTTP API"]:::api

    %% External Services
    subgraph "External Bank Services"
        ExtBanks["Bank Services"]:::external
    end

    %% Relationships
    User -->|"clicks"| ReactUI
    ReactUI -->|"import loot-core APIs"| BL
    ElectronMain -->|launch + IPC| ReactUI
    ElectronMain -->|spawn| LocalServer
    Preload -->|expose IPC| BL

    BL -->|"reads/writes"| PA
    PA -->|"SQL queries"| SQLiteDB
    PA -->|"IndexedDB API"| IndexedDB

    BL -->|"generate diff"| CRDT
    CRDT -->|"HTTP POST CRDT payload"| SyncServer
    LocalServer -->|"persist messages"| LocalMsgStore

    subgraph down
        CRDT -->|"POST /sync"| MsgStore
        MsgStore -->|"return diffs"| CRDT
    end

    SyncServer --> Auth
    SyncServer --> MsgStore
    SyncServer --> Migrations
    SyncServer --> GoCardless
    SyncServer --> SimpleFin
    SyncServer --> PluggyAI

    GoCardless -->|fetch transactions| ExtBanks
    SimpleFin -->|fetch transactions| ExtBanks
    PluggyAI -->|fetch transactions| ExtBanks

    API -->|"HTTP calls"| SyncServer

    %% Click Events
    click ReactUI "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/desktop-client/src/index.tsx"
    click ReactUI "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/desktop-client/src/"
    click ElectronMain "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/desktop-electron/index.ts"
    click Preload "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/desktop-electron/preload.ts"
    click LocalServer "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/desktop-electron/server.ts"
    click BL "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/loot-core/"
    click SQLiteDB "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/loot-core/src/platform/server/sqlite/"
    click IndexedDB "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/loot-core/src/platform/server/indexeddb/"
    click CRDT "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/crdt/src/crdt/"
    click CRDT "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/crdt/src/proto/"
    click SyncServer "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/sync-server/src/app.js"
    click Migrations "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/sync-server/migrations/"
    click Migrations "https://github.com/junaid-nazir-828/actual_budget/blob/master/packages/sync-server/src/run-migrations.js"
    click GoCardless "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/sync-server/src/app-gocardless/banks/"
    click SimpleFin "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/sync-server/src/app-simplefin/"
    click PluggyAI "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/sync-server/src/app-pluggyai/"
    click API "https://github.com/junaid-nazir-828/actual_budget/tree/master/packages/api/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#005FCC,color:#003366
    classDef core fill:#E6FFDD,stroke:#4CAF50,color:#33691E
    classDef sync fill:#FFF3CD,stroke:#FFB300,color:#795548
    classDef database fill:#F0F0F0,stroke:#888888,color:#555555
    classDef external fill:#EEEEEE,stroke:#AAAAAA,color:#555555
    classDef api fill:#FFDCE0,stroke:#FF4081,color:#C2185B
```
