How aventurine-app/oliv-app works
1. Overall shape
- Oliv is a single-user, offline Electron desktop app.
- The repo is split into a desktop shell (electron/), renderer pages (pages/), and static assets/JS/CSS (static/).
- There is no remote application backend; the only durable state is the user’s local SQLite/SQLCipher database file.
2. Process model
- The Electron main process (electron/main.js) owns window creation, app lifecycle, and backend initialization.
- The preload layer (electron/preload.js) is the trust boundary between renderer and backend.
- The renderer is plain HTML/CSS/JS with no bundler or framework build step; each page loads its own page script plus shared shell scripts.
3. Renderer / UI composition
- Top-level views live in pages/ such as Home, Transactions, Categories, Statements, Cash Flow, Trends, Credit Cards, Portfolio, and Report Card.
- Shared layout pieces are in pages/partials/ and global shell behavior in static/js/shell/ for navigation, title bar, theme, zoom, autolock, settings, and DB actions.
- Reusable UI components/widgets live in static/js/widgets/ for charts, tables, sankey cash flow, transaction import/export, and cell selection.
4. Frontend data access path
- Page code in static/js/pages/ does not talk to the database directly.
- It calls a shared API layer in static/js/core/api.js, which routes requests through the preload bridge into the backend.
- Frontend helpers such as currency.js, store.js, encryption.js, and escape.js provide formatting, persisted UI state, local storage-like behavior, and passphrase-related support.
5. Backend API boundary
- The backend is organized around request handlers in electron/backend/handlers/ and routing in router.js / routes.js.
- Handlers are feature-oriented: transactions, categories, forecast, report card, trends, portfolio, income/expenses, credit cards, app settings, year tables, and database operations.
- This layer is the main integration boundary for the renderer: it translates UI requests into domain operations and serializable responses.
6. Domain logic layer
- Business rules live in electron/backend/services/.
- Important service areas include transaction management, categorization/matching, merchant-category logic, forecasting, report-card computation, credit-card logic, transaction export, and prediction generation.
- This separation suggests handlers are thin orchestration layers while services encode the actual financial logic.
7. Persistence and database lifecycle
- Data is stored in a local SQLite database, with optional SQLCipher encryption at creation time.
- Core DB infrastructure is split across conn.js, db.js, schema.js, migrate.js, seed.js, and dbstate.js.
- validate.js and writeGuard.js tests imply the app enforces safe writes and database state checks before mutating user data.
8. Primary data flows
- The central flow is: import or enter transactions → classify/categorize them → persist to DB → surface summaries in cash flow, trends, and report card views.
- Categorization is assisted by rule matching and learning from user choices, with a separate category synchronization path (categorySync.js).
- Statement import/export is a first-class flow via widgets and services, supporting CSV/OFX/QFX/QIF ingestion and transaction export.
9. Analytics and projections
- Analytical features are computed locally from stored transactions and account data.
- Forecasting, trend analysis, year tables, income/expense summaries, report cards, and portfolio views all depend on backend computation rather than server-side aggregation.
- The frontend renders these results via chart/table widgets and page-specific scripts.
10. Settings and app security
- User preferences such as theme, currency, and zoom are persisted separately from financial records.
- The app supports autolock and encrypted databases; passphrases are not written to disk.
- This makes the architecture explicitly privacy-first: renderer state is lightweight, sensitive data stays in the local DB, and unlock logic is mediated through the shell/backend boundary.
11. Tests and release tooling
- Backend behavior is heavily covered by Node-based tests in electron/backend/__tests__/.
- There are separate scripts for smoke testing under the real Electron runtime and end-to-end verification from the renderer.
- Packaging is handled with Electron Builder (electron-builder.yml) and GitHub Actions workflows for test and release, with helper scripts for native SQLite ABI setup.
12. What to draw in an architecture diagram
- Draw three main tiers: Electron main/preload, renderer UI, and local database.
- Inside the backend tier, show routing/handlers in front of services, and services in front of DB/migration/schema modules.
- Connect page scripts to the shared API bridge, then to feature handlers/services, then to SQLite/SQLCipher.
- Show analytics as local computations over the same database, not as separate external services.
Main entry points: db.js Database core · home.js Page scripts · router.js Router · transactions.js Transaction logic
Components 22
Electron backend
Main process, preload bridge, routing, handlers, services, and local DB lifecycle.
- Main process · Creates windows and owns app lifecycle.
electron/main.js - Preload bridge · Trust boundary between renderer and backend.
electron/preload.js - Router · Dispatches backend API requests to handlers.
electron/backend/router.js - Transactions · Transaction and database-facing request handling.
electron/backend/handlers/transactions.js - Analytics · Report card, trends, forecast, income/expenses, year table, and portfolio endpoints.
electron/backend/handlers/reportCard.js - Settings API · App settings, categories, credit cards, and database operations.
electron/backend/handlers/appSettings.js - Transaction logic · Transaction management and persistence rules.
electron/backend/services/transactions.js - Categorization · Matching, merchant-category logic, and category synchronization.
electron/backend/services/categorize.js - Analytics engine · Forecasting, report-card computation, predictions, credit-card logic, and export.
electron/backend/services/forecast.js
Renderer UI
HTML pages, shared shell scripts, page scripts, and reusable widgets.
- Home · Dashboard and overview view.
pages/home.html - Transactions · Transaction list and editing view.
pages/transactions.html - Analysis pages · Categories, statements, cash flow, trends, credit cards, portfolio, and report card views.
pages/categories.html - Shell UI · Navigation, title bar, theme, zoom, autolock, settings, and database actions.
static/js/shell/nav.js - API client · Shared renderer API layer that calls through preload into backend handlers.
static/js/core/api.js - Page scripts · Page-specific behavior for home, transactions, cash flow, trends, portfolio, report card, statements, and credit cards.
static/js/pages/home.js - Widgets · Charts, tables, sankey cash flow, import/export, forecast, and cell selection widgets.
static/js/widgets/chart.js
Local data
SQLite/SQLCipher database and schema/migration lifecycle.
- DB connection · Opens and manages the local encrypted database connection.
electron/backend/conn.js - Schema · Database schema and structural definitions.
electron/backend/schema.js - Migrations · Applies database migrations.
electron/backend/migrate.js - Seed data · Initial database seeding.
electron/backend/seed.js - DB state · Tracks database state and write safety.
electron/backend/dbstate.js - Database core · Core database operations and lifecycle orchestration.
electron/backend/db.js
Connections 25
- Main process → Preload bridge: loads · Main process exposes preload for renderer access.
- Preload bridge → Router: ipc · Renderer calls are bridged into backend routing.
- Router → Transactions: dispatches · Routes transaction requests to the matching handler.
- Router → Analytics: dispatches · Routes analysis requests to feature handlers.
- Router → Settings API: dispatches · Routes app settings and database actions.
- Transactions → Transaction logic: uses · Transaction handlers delegate business rules to services.
- Transactions → DB connection: queries · Handlers read and write through the DB connection layer.
- Analytics → Analytics engine: uses · Analytics endpoints delegate computation to services.
- Analytics engine → Transaction logic: reads · Analytics reuse transaction data and domain logic.
- Transaction logic → Categorization: calls · Transaction processing uses categorization and matching logic.
- Transaction logic → Database core: persists · Transaction service writes through database core.
- Categorization → Database core: reads/writes · Category rules and sync operate on stored data.
- Database core → DB connection: opens · Database core manages the active connection.
- Database core → Schema: uses · Database core relies on schema definitions.
- Database core → Migrations: runs · Database core applies migrations.
- Database core → Seed data: initializes · Database core seeds new databases.
- Database core → DB state: guards · Database state and safe-write checks gate mutations.
- API client → Preload bridge: calls · Shared renderer API forwards requests through preload.
- Shell UI → API client: drives · Global shell actions invoke backend APIs.
- Page scripts → API client: uses · Page code fetches data and submits actions through the API client.
- Widgets → Page scripts: embedded by · Reusable components are composed into page views.
- Home → Page scripts: bootstraps · Home page loads its page script.
- Transactions → Page scripts: bootstraps · Transactions page loads its page script.
- Analysis pages → Page scripts: bootstraps · Analysis pages load their corresponding page scripts.
- Shell UI → Widgets: renders with · Shared UI uses widgets for tables, charts, and dialogs.