# maybe-finance/maybe architecture

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

- Interactive diagram: https://gitdiagram.com/maybe-finance/maybe
- Repository: https://github.com/maybe-finance/maybe

## Overview

1. **Overall shape**
   - This is a Ruby on Rails monolith for personal finance management.
   - The app is organized around a server-rendered web UI, a JSON API, background jobs, and a large domain/model layer that handles accounting, syncing, imports, analytics, and assistant features.

2. **Primary user boundary: family/workspace**
   - The main tenant boundary is the **Family** concept: users belong to a family and most financial data is scoped there.
   - Family-level state includes accounts, budgets, categories, rules, subscriptions, sync status, exports, and shared settings.

3. **Core financial domain**
   - The central data model revolves around **accounts**, **entries/transactions**, **balances**, **categories**, **tags**, **transfers**, **valuations**, **trades**, **holdings**, and **budgets**.
   - Accounts are specialized into several account types such as depository, credit card, investment, loan, property, vehicle, crypto, and other asset/liability models.
   - The `Entry`/`Transaction` layer acts as the shared ledger surface that ties together account activity, transfers, categorization, and reporting.

4. **Derived finance and reporting layer**
   - A significant part of the repo is read-only computation over the ledger: balance sheets, income statements, net worth series, account charts, cash-flow views, and portfolio snapshots.
   - These are implemented as dedicated model/services rather than controllers, which suggests the UI depends heavily on derived domain objects instead of querying raw tables directly.

5. **External account synchronization**
   - Plaid is the main banking/investment integration. The codebase contains dedicated models for Plaid items, accounts, webhooks, importers, processors, and syncers.
   - Sync is asynchronous and event-driven: Plaid webhooks and sync jobs update accounts, holdings, liabilities, transactions, and balances, then propagate derived state back into the app.

6. **Import pipeline**
   - There is a separate import subsystem for CSV/manual data ingestion.
   - The flow is staged: upload/configuration → column mapping → row cleaning/confirmation → job-backed import processing.
   - Imports support multiple domains, including transactions, accounts, trades, and Mint-style files, which indicates the app can bootstrap or reconcile data outside Plaid.

7. **Automation and rules**
   - The app has a rules engine for transaction processing, including auto-categorization, merchant detection, and field mutation actions.
   - Related background jobs apply these rules after new data arrives, which means categorization is not purely user-driven; it is part of the ingestion/sync pipeline.

8. **AI assistant subsystem**
   - Chats, messages, assistant messages, tool calls, and OpenAI provider objects form a distinct conversational subsystem.
   - The assistant can query domain data through explicit tools such as get accounts, balance sheet, income statement, and transactions.
   - This is a clear boundary: user chat input goes through controllers/jobs, then to the LLM provider, then back into finance-domain tool outputs.

9. **Presentation layer**
   - The UI is mostly server-rendered ERB with Hotwire-style interactivity.
   - `app/components` contains a design system (`DS`) plus feature-specific UI components (`UI/...`) used across pages.
   - Stimulus controllers handle client-side behavior such as dialogs, charts, menus, forms, filtering, onboarding, and chat streaming; Tailwind CSS powers styling.

10. **HTTP/API surface**
   - The app exposes both traditional HTML controllers and a versioned JSON API under `api/v1`.
   - API endpoints cover accounts, chats, messages, transactions, and usage, suggesting external clients or mobile apps are first-class.
   - OAuth is supported via Doorkeeper, alongside API keys and mobile-device records.

11. **Authentication, permissions, and operational flows**
   - The repo includes sessions, password reset, email confirmation, MFA, invitations, impersonation, and onboarding controllers.
   - These features imply a layered access model: normal users, invited users, and super-admin/impersonation paths.
   - Host/billing settings and subscription management also exist, showing that account lifecycle and plan state are part of the application boundary.

12. **Async processing and realtime**
   - Background jobs are used for sync, imports, assistant responses, exports, Stripe event handling, purge/reset flows, and security checks.
   - ActionCable is present, and Turbo streams/views are used in places where the UI needs live updates after async work completes.
   - This means the architecture is “request/response + job queue + incremental UI updates,” not a purely synchronous web app.

13. **External services**
   - Plaid, OpenAI, Stripe, Synth, and GitHub-backed provider abstractions are all part of the integration layer.
   - The `provider` namespace suggests a registry/interface pattern so external APIs can be swapped or mocked consistently in tests.
   - Sentry, Intercom, and rate limiting are present as operational concerns, but they are support boundaries rather than core domain drivers.

14. **Persistence and deployment**
   - PostgreSQL is the main datastore, with Active Storage for uploads and extensive migrations showing a long-lived schema evolution.
   - Background processing is configured for Sidekiq, and the repo includes Docker/devcontainer support plus a self-hosting path in the docs.
   - The large test suite, VCR cassettes, and component previews indicate the architecture is heavily integration-tested across the domain and provider boundaries.

Main entry points: [`app/models/entry.rb`](https://github.com/maybe-finance/maybe/blob/main/app/models/entry.rb) (Ledger), [`app/jobs`](https://github.com/maybe-finance/maybe/tree/main/app/jobs) (Jobs), [`app/controllers`](https://github.com/maybe-finance/maybe/tree/main/app/controllers) (Controllers), [`app/models/account.rb`](https://github.com/maybe-finance/maybe/blob/main/app/models/account.rb) (Accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Presentation"]
  node_node_views["Views"]
  node_node_components["Components"]
  node_node_stimulus["Stimulus<br/>client controllers"]
end

subgraph group_group_domain["Finance Domain"]
  node_node_family["Family<br/>tenant boundary<br/>[family.rb]"]
  node_node_accounts["Accounts<br/>account aggregates<br/>[account.rb]"]
  node_node_ledger["Ledger<br/>entries & transactions<br/>[entry.rb]"]
  node_node_reporting["Reporting<br/>derived finance<br/>[balance_sheet.rb]"]
  node_node_budgets["Budgets<br/>budgeting<br/>[budget.rb]"]
end

subgraph group_group_ingest["Ingestion & Sync"]
  node_node_imports["Imports<br/>import pipeline<br/>[import.rb]"]
  node_node_plaid["Plaid Sync<br/>bank sync<br/>[plaid_item.rb]"]
  node_node_rules["Rules<br/>automation engine<br/>[rule.rb]"]
end

subgraph group_group_ai["Assistant"]
  node_node_assistant["Assistant<br/>llm chat<br/>[assistant.rb]"]
end

subgraph group_group_platform["Platform"]
  node_node_controllers["Controllers<br/>http entrypoints"]
  node_node_jobs["Jobs"]
  node_node_api["API v1<br/>json api"]
  node_node_auth["Auth & Access<br/>identity"]
  node_node_providers["Providers<br/>integrations<br/>[provider.rb]"]
  node_node_realtime(("Realtime<br/>cable/turbo<br/>[channel.rb]"))
  node_node_storage[("Persistence<br/>db/storage<br/>[schema.rb]")]
end

node_node_controllers -->|"renders"| node_node_views
node_node_controllers -->|"uses"| node_node_components
node_node_views -.->|"enhanced by"| node_node_stimulus
node_node_controllers -->|"guards"| node_node_auth
node_node_api -->|"reads/writes"| node_node_ledger
node_node_api -->|"serves"| node_node_assistant
node_node_family -->|"scopes"| node_node_accounts
node_node_family -->|"owns"| node_node_budgets
node_node_accounts -->|"anchors"| node_node_ledger
node_node_ledger -->|"feeds"| node_node_reporting
node_node_budgets -->|"summarizes"| node_node_ledger
node_node_imports -->|"ingests"| node_node_ledger
node_node_plaid -->|"syncs"| node_node_accounts
node_node_plaid -->|"syncs"| node_node_ledger
node_node_rules -->|"mutates"| node_node_ledger
node_node_jobs -->|"runs"| node_node_plaid
node_node_jobs -->|"runs"| node_node_imports
node_node_jobs -->|"runs"| node_node_assistant
node_node_jobs -->|"applies"| node_node_rules
node_node_assistant -->|"calls"| node_node_providers
node_node_providers -.->|"adapts"| node_node_assistant
node_node_providers -.->|"persists via"| node_node_storage
node_node_realtime -.->|"streams"| node_node_controllers
node_node_storage -.->|"backs"| node_node_accounts
node_node_storage -.->|"backs"| node_node_ledger

click node_node_controllers "https://github.com/maybe-finance/maybe/tree/main/app/controllers"
click node_node_views "https://github.com/maybe-finance/maybe/tree/main/app/views"
click node_node_components "https://github.com/maybe-finance/maybe/tree/main/app/components"
click node_node_stimulus "https://github.com/maybe-finance/maybe/tree/main/app/javascript/controllers"
click node_node_family "https://github.com/maybe-finance/maybe/blob/main/app/models/family.rb"
click node_node_accounts "https://github.com/maybe-finance/maybe/blob/main/app/models/account.rb"
click node_node_ledger "https://github.com/maybe-finance/maybe/blob/main/app/models/entry.rb"
click node_node_reporting "https://github.com/maybe-finance/maybe/blob/main/app/models/balance_sheet.rb"
click node_node_budgets "https://github.com/maybe-finance/maybe/blob/main/app/models/budget.rb"
click node_node_imports "https://github.com/maybe-finance/maybe/blob/main/app/models/import.rb"
click node_node_plaid "https://github.com/maybe-finance/maybe/blob/main/app/models/plaid_item.rb"
click node_node_rules "https://github.com/maybe-finance/maybe/blob/main/app/models/rule.rb"
click node_node_jobs "https://github.com/maybe-finance/maybe/tree/main/app/jobs"
click node_node_api "https://github.com/maybe-finance/maybe/tree/main/app/controllers/api/v1"
click node_node_auth "https://github.com/maybe-finance/maybe/blob/main/app/controllers/sessions_controller.rb"
click node_node_assistant "https://github.com/maybe-finance/maybe/blob/main/app/models/assistant.rb"
click node_node_providers "https://github.com/maybe-finance/maybe/blob/main/app/models/provider.rb"
click node_node_realtime "https://github.com/maybe-finance/maybe/blob/main/app/channels/application_cable/channel.rb"
click node_node_storage "https://github.com/maybe-finance/maybe/blob/main/db/schema.rb"

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_node_views,node_node_components,node_node_stimulus toneBlue
class node_node_family,node_node_accounts,node_node_ledger,node_node_reporting,node_node_budgets toneAmber
class node_node_imports,node_node_plaid,node_node_rules toneMint
class node_node_assistant toneRose
class node_node_controllers,node_node_jobs,node_node_api,node_node_auth,node_node_providers,node_node_realtime,node_node_storage toneIndigo
```

## Components

### Presentation

Server-rendered UI, reusable components, and client-side interactivity.

- [Views](https://github.com/maybe-finance/maybe/tree/main/app/views): erb views · Server-rendered pages, partials, and Turbo stream responses. · `app/views`
- [Components](https://github.com/maybe-finance/maybe/tree/main/app/components): view components · Design system and feature-specific reusable UI components. · `app/components`
- [Stimulus](https://github.com/maybe-finance/maybe/tree/main/app/javascript/controllers): client controllers · Browser behavior for dialogs, charts, forms, chat, imports, rules, and navigation. · `app/javascript/controllers`

### Finance Domain

Core tenant, ledger, reporting, and financial model layer.

- [Family](https://github.com/maybe-finance/maybe/blob/main/app/models/family.rb): tenant boundary · Primary workspace boundary for shared financial data, settings, subscriptions, and sync state. · `app/models/family.rb`
- [Accounts](https://github.com/maybe-finance/maybe/blob/main/app/models/account.rb): account aggregates · Depository, credit, investment, loan, property, vehicle, crypto, and other account types. · `app/models/account.rb`
- [Ledger](https://github.com/maybe-finance/maybe/blob/main/app/models/entry.rb): entries & transactions · Shared transaction surface with categories, tags, transfers, search, and reconciliation. · `app/models/entry.rb`
- [Reporting](https://github.com/maybe-finance/maybe/blob/main/app/models/balance_sheet.rb): derived finance · Balances, balance sheets, income statements, trends, portfolio snapshots, and time series. · `app/models/balance_sheet.rb`
- [Budgets](https://github.com/maybe-finance/maybe/blob/main/app/models/budget.rb): budgeting · Budget and budget-category allocation, progress, and comparison views. · `app/models/budget.rb`

### Ingestion & Sync

Imports, Plaid sync, rules, and related async processing.

- [Imports](https://github.com/maybe-finance/maybe/blob/main/app/models/import.rb): import pipeline · Upload, mapping, cleaning, confirmation, and job-backed import processing. · `app/models/import.rb`
- [Plaid Sync](https://github.com/maybe-finance/maybe/blob/main/app/models/plaid_item.rb): bank sync · Plaid items, accounts, webhooks, processors, and syncers for account data. · `app/models/plaid_item.rb`
- [Rules](https://github.com/maybe-finance/maybe/blob/main/app/models/rule.rb): automation engine · Conditions and actions for auto-categorization, merchant detection, and field mutation. · `app/models/rule.rb`

### Assistant

Chat, tool calling, and LLM provider integration.

- [Assistant](https://github.com/maybe-finance/maybe/blob/main/app/models/assistant.rb): llm chat · Chats, messages, tool calls, responders, and assistant-specific persistence. · `app/models/assistant.rb`

### Platform

HTTP/API, auth, jobs, realtime, and persistence.

- [Controllers](https://github.com/maybe-finance/maybe/tree/main/app/controllers): http entrypoints · HTML controllers, API endpoints, auth flows, settings, and domain actions. · `app/controllers`
- [Jobs](https://github.com/maybe-finance/maybe/tree/main/app/jobs): background jobs · Async workers for sync, imports, exports, assistant responses, rules, and maintenance. · `app/jobs`
- [API v1](https://github.com/maybe-finance/maybe/tree/main/app/controllers/api/v1): json api · Versioned JSON endpoints for accounts, chats, messages, transactions, and usage. · `app/controllers/api/v1`
- [Auth & Access](https://github.com/maybe-finance/maybe/blob/main/app/controllers/sessions_controller.rb): identity · Sessions, password reset, MFA, invitations, impersonation, OAuth, API keys, and onboarding. · `app/controllers/sessions_controller.rb`
- [Providers](https://github.com/maybe-finance/maybe/blob/main/app/models/provider.rb): integrations · Shared provider registry and adapters for OpenAI, Plaid, Stripe, GitHub, Synth, and security concepts. · `app/models/provider.rb`
- [Realtime](https://github.com/maybe-finance/maybe/blob/main/app/channels/application_cable/channel.rb): cable/turbo · ActionCable and Turbo stream updates for incremental UI refreshes. · `app/channels/application_cable/channel.rb`
- [Persistence](https://github.com/maybe-finance/maybe/blob/main/db/schema.rb): db/storage · PostgreSQL schema, migrations, Active Storage, and seeds. · `db/schema.rb`

## Connections

- Controllers → Views: renders · HTML controllers feed ERB pages and Turbo responses.
- Controllers → Components: uses · Pages are assembled from reusable UI components.
- Views → Stimulus: enhanced by · Rendered pages attach client behaviors from Stimulus controllers.
- Controllers → Auth & Access: guards · Authentication and access concerns are enforced at the HTTP boundary.
- API v1 → Ledger: reads/writes · The API exposes core ledger resources to external clients.
- API v1 → Assistant: serves · The API includes chat and message endpoints.
- Family → Accounts: scopes · Family is the tenant boundary for account data.
- Family → Budgets: owns · Budgets and shared finance settings are family-scoped.
- Accounts → Ledger: anchors · Accounts own the activity surface for entries and transactions.
- Ledger → Reporting: feeds · Derived reports compute from the shared ledger surface.
- Budgets → Ledger: summarizes · Budgets compare allocations against transaction activity.
- Imports → Ledger: ingests · Imports materialize accounts, transactions, trades, and related records.
- Plaid Sync → Accounts: syncs · Plaid processors update accounts and specialized account types.
- Plaid Sync → Ledger: syncs · Transactions, holdings, liabilities, and balances flow into the ledger.
- Rules → Ledger: mutates · Rules auto-categorize and normalize newly ingested transactions.
- Jobs → Plaid Sync: runs · Async jobs drive Plaid sync and webhook handling.
- Jobs → Imports: runs · Import processing and reversion are job-backed.
- Jobs → Assistant: runs · Assistant responses are generated asynchronously.
- Jobs → Rules: applies · Background workers execute post-ingest categorization and enrichment.
- Assistant → Providers: calls · Chat and tool execution route through provider abstractions.
- Providers → Assistant: adapts · OpenAI provider implements assistant chat and tool calling.
- Providers → Persistence: persists via · Integration state is backed by the database and storage layers.
- Realtime → Controllers: streams · Turbo streams and cable update the UI after async work completes.
- Persistence → Accounts: backs · Database persistence underpins the core account model.
- Persistence → Ledger: backs · Database persistence underpins entries, transactions, and transfers.
