How maybe-finance/maybe works
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: entry.rb Ledger · jobs Jobs · controllers Controllers · account.rb Accounts
Components 19
Presentation
Server-rendered UI, reusable components, and client-side interactivity.
- Views · Server-rendered pages, partials, and Turbo stream responses.
app/views - Components · Design system and feature-specific reusable UI components.
app/components - Stimulus · 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 · Primary workspace boundary for shared financial data, settings, subscriptions, and sync state.
app/models/family.rb - Accounts · Depository, credit, investment, loan, property, vehicle, crypto, and other account types.
app/models/account.rb - Ledger · Shared transaction surface with categories, tags, transfers, search, and reconciliation.
app/models/entry.rb - Reporting · Balances, balance sheets, income statements, trends, portfolio snapshots, and time series.
app/models/balance_sheet.rb - Budgets · Budget and budget-category allocation, progress, and comparison views.
app/models/budget.rb
Ingestion & Sync
Imports, Plaid sync, rules, and related async processing.
- Imports · Upload, mapping, cleaning, confirmation, and job-backed import processing.
app/models/import.rb - Plaid Sync · Plaid items, accounts, webhooks, processors, and syncers for account data.
app/models/plaid_item.rb - Rules · Conditions and actions for auto-categorization, merchant detection, and field mutation.
app/models/rule.rb
Assistant
Chat, tool calling, and LLM provider integration.
- Assistant · Chats, messages, tool calls, responders, and assistant-specific persistence.
app/models/assistant.rb
Platform
HTTP/API, auth, jobs, realtime, and persistence.
- Controllers · HTML controllers, API endpoints, auth flows, settings, and domain actions.
app/controllers - Jobs · Async workers for sync, imports, exports, assistant responses, rules, and maintenance.
app/jobs - API v1 · Versioned JSON endpoints for accounts, chats, messages, transactions, and usage.
app/controllers/api/v1 - Auth & Access · Sessions, password reset, MFA, invitations, impersonation, OAuth, API keys, and onboarding.
app/controllers/sessions_controller.rb - Providers · Shared provider registry and adapters for OpenAI, Plaid, Stripe, GitHub, Synth, and security concepts.
app/models/provider.rb - Realtime · ActionCable and Turbo stream updates for incremental UI refreshes.
app/channels/application_cable/channel.rb - Persistence · PostgreSQL schema, migrations, Active Storage, and seeds.
db/schema.rb
Connections 25
- 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.