# aventurine-app/oliv-app architecture

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

- Interactive diagram: https://gitdiagram.com/aventurine-app/oliv-app
- Repository: https://github.com/aventurine-app/oliv-app

## Overview

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: [`electron/backend/db.js`](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/db.js) (Database core), [`static/js/pages/home.js`](https://github.com/aventurine-app/oliv-app/blob/main/static/js/pages/home.js) (Page scripts), [`electron/backend/router.js`](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/router.js) (Router), [`electron/backend/services/transactions.js`](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/transactions.js) (Transaction logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Electron backend"]
  node_main["Main process<br/>electron main<br/>[main.js]"]
  node_preload["Preload bridge<br/>ipc bridge<br/>[preload.js]"]
  node_router["Router<br/>[router.js]"]
  node_tx_handlers["Transactions<br/>handler<br/>[transactions.js]"]
  node_analytics_handlers["Analytics<br/>handlers<br/>[reportCard.js]"]
  node_settings_handlers["Settings API<br/>handler<br/>[appSettings.js]"]
  node_tx_services["Transaction logic<br/>[transactions.js]"]
  node_categorize_services["Categorization<br/>[categorize.js]"]
  node_analytics_services["Analytics engine<br/>[forecast.js]"]
end

subgraph group_renderer["Renderer UI"]
  node_home_page["Home<br/>page<br/>[home.html]"]
  node_tx_page["Transactions<br/>page<br/>[transactions.html]"]
  node_analytics_pages["Analysis pages<br/>[categories.html]"]
  node_shell["Shell UI<br/>shared ui<br/>[nav.js]"]
  node_api["API client<br/>frontend api<br/>[api.js]"]
  node_page_scripts["Page scripts<br/>renderer logic<br/>[home.js]"]
  node_widgets["Widgets<br/>ui components<br/>[chart.js]"]
end

subgraph group_data["Local data"]
  node_conn[("DB connection<br/>sqlite layer<br/>[conn.js]")]
  node_schema["Schema<br/>[schema.js]"]
  node_migrate["Migrations<br/>db lifecycle<br/>[migrate.js]"]
  node_seed["Seed data<br/>db lifecycle<br/>[seed.js]"]
  node_dbstate["DB state<br/>state guard<br/>[dbstate.js]"]
  node_db[("Database core<br/>[db.js]")]
end

node_main -->|"loads"| node_preload
node_preload -->|"ipc"| node_router
node_router -->|"dispatches"| node_tx_handlers
node_router -->|"dispatches"| node_analytics_handlers
node_router -->|"dispatches"| node_settings_handlers
node_tx_handlers -->|"uses"| node_tx_services
node_tx_handlers -->|"queries"| node_conn
node_analytics_handlers -->|"uses"| node_analytics_services
node_analytics_services -->|"reads"| node_tx_services
node_tx_services -->|"calls"| node_categorize_services
node_tx_services -->|"persists"| node_db
node_categorize_services -->|"reads/writes"| node_db
node_db -->|"opens"| node_conn
node_db -->|"uses"| node_schema
node_db -->|"runs"| node_migrate
node_db -->|"initializes"| node_seed
node_db -->|"guards"| node_dbstate
node_api -->|"calls"| node_preload
node_shell -->|"drives"| node_api
node_page_scripts -->|"uses"| node_api
node_widgets -->|"embedded by"| node_page_scripts
node_home_page -->|"bootstraps"| node_page_scripts
node_tx_page -->|"bootstraps"| node_page_scripts
node_analytics_pages -->|"bootstraps"| node_page_scripts
node_shell -->|"renders with"| node_widgets

click node_main "https://github.com/aventurine-app/oliv-app/blob/main/electron/main.js"
click node_preload "https://github.com/aventurine-app/oliv-app/blob/main/electron/preload.js"
click node_router "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/router.js"
click node_tx_handlers "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/transactions.js"
click node_analytics_handlers "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/reportCard.js"
click node_settings_handlers "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/appSettings.js"
click node_tx_services "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/transactions.js"
click node_categorize_services "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/categorize.js"
click node_analytics_services "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/forecast.js"
click node_conn "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/conn.js"
click node_schema "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/schema.js"
click node_migrate "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/migrate.js"
click node_seed "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/seed.js"
click node_dbstate "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/dbstate.js"
click node_db "https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/db.js"
click node_home_page "https://github.com/aventurine-app/oliv-app/blob/main/pages/home.html"
click node_tx_page "https://github.com/aventurine-app/oliv-app/blob/main/pages/transactions.html"
click node_analytics_pages "https://github.com/aventurine-app/oliv-app/blob/main/pages/categories.html"
click node_shell "https://github.com/aventurine-app/oliv-app/blob/main/static/js/shell/nav.js"
click node_api "https://github.com/aventurine-app/oliv-app/blob/main/static/js/core/api.js"
click node_page_scripts "https://github.com/aventurine-app/oliv-app/blob/main/static/js/pages/home.js"
click node_widgets "https://github.com/aventurine-app/oliv-app/blob/main/static/js/widgets/chart.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_main,node_preload,node_router,node_tx_handlers,node_analytics_handlers,node_settings_handlers,node_tx_services,node_categorize_services,node_analytics_services toneBlue
class node_home_page,node_tx_page,node_analytics_pages,node_shell,node_api,node_page_scripts,node_widgets toneAmber
class node_conn,node_schema,node_migrate,node_seed,node_dbstate,node_db toneMint
```

## Components

### Electron backend

Main process, preload bridge, routing, handlers, services, and local DB lifecycle.

- [Main process](https://github.com/aventurine-app/oliv-app/blob/main/electron/main.js): electron main · Creates windows and owns app lifecycle. · `electron/main.js`
- [Preload bridge](https://github.com/aventurine-app/oliv-app/blob/main/electron/preload.js): ipc bridge · Trust boundary between renderer and backend. · `electron/preload.js`
- [Router](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/router.js): request router · Dispatches backend API requests to handlers. · `electron/backend/router.js`
- [Transactions](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/transactions.js): handler · Transaction and database-facing request handling. · `electron/backend/handlers/transactions.js`
- [Analytics](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/reportCard.js): handlers · Report card, trends, forecast, income/expenses, year table, and portfolio endpoints. · `electron/backend/handlers/reportCard.js`
- [Settings API](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/handlers/appSettings.js): handler · App settings, categories, credit cards, and database operations. · `electron/backend/handlers/appSettings.js`
- [Transaction logic](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/transactions.js): service · Transaction management and persistence rules. · `electron/backend/services/transactions.js`
- [Categorization](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/categorize.js): service · Matching, merchant-category logic, and category synchronization. · `electron/backend/services/categorize.js`
- [Analytics engine](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/services/forecast.js): service · 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](https://github.com/aventurine-app/oliv-app/blob/main/pages/home.html): page · Dashboard and overview view. · `pages/home.html`
- [Transactions](https://github.com/aventurine-app/oliv-app/blob/main/pages/transactions.html): page · Transaction list and editing view. · `pages/transactions.html`
- [Analysis pages](https://github.com/aventurine-app/oliv-app/blob/main/pages/categories.html): pages · Categories, statements, cash flow, trends, credit cards, portfolio, and report card views. · `pages/categories.html`
- [Shell UI](https://github.com/aventurine-app/oliv-app/blob/main/static/js/shell/nav.js): shared ui · Navigation, title bar, theme, zoom, autolock, settings, and database actions. · `static/js/shell/nav.js`
- [API client](https://github.com/aventurine-app/oliv-app/blob/main/static/js/core/api.js): frontend api · Shared renderer API layer that calls through preload into backend handlers. · `static/js/core/api.js`
- [Page scripts](https://github.com/aventurine-app/oliv-app/blob/main/static/js/pages/home.js): renderer logic · Page-specific behavior for home, transactions, cash flow, trends, portfolio, report card, statements, and credit cards. · `static/js/pages/home.js`
- [Widgets](https://github.com/aventurine-app/oliv-app/blob/main/static/js/widgets/chart.js): ui components · 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](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/conn.js): sqlite layer · Opens and manages the local encrypted database connection. · `electron/backend/conn.js`
- [Schema](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/schema.js): db schema · Database schema and structural definitions. · `electron/backend/schema.js`
- [Migrations](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/migrate.js): db lifecycle · Applies database migrations. · `electron/backend/migrate.js`
- [Seed data](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/seed.js): db lifecycle · Initial database seeding. · `electron/backend/seed.js`
- [DB state](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/dbstate.js): state guard · Tracks database state and write safety. · `electron/backend/dbstate.js`
- [Database core](https://github.com/aventurine-app/oliv-app/blob/main/electron/backend/db.js): database core · Core database operations and lifecycle orchestration. · `electron/backend/db.js`

## Connections

- 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.
