How junaid-nazir-828/actual_budget works
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