Maybe — Administrator & Developer Guide

Maybe is a self-hosted personal finance platform built as a single Ruby on Rails 7.2 application backed by PostgreSQL and Redis, with Sidekiq for background work and a Hotwire (Turbo + Stimulus) front end. This guide is the operator's and developer's reference: how the system is built, every configuration variable, how to deploy and operate it, how it's secured, and how the code is organized.

For day-to-day usage (adding accounts, budgets, the AI assistant), see the companion Maybe — User Guide.

Note

Maybe reached its final public release (v0.6.0, defined in config/initializers/version.rb) and is no longer actively maintained upstream. It is fully functional and licensed under the AGPLv3. This guide documents the codebase at commit 77b5469.

1. Architecture Overview

Maybe is a "majestic monolith": one Rails application that serves both the web UI and a JSON API, with all heavy work pushed to a Sidekiq worker process. It runs in one of two modes, decided at boot from environment variables:

• Self-hosted (SELF_HOSTED=true) — you run it; subscriptions are disabled, rate limits are generous, encryption keys auto-generate, and self-hosting settings appear in the UI.
• Managed — the configuration the original hosted service used (billing on, tighter limits).

The mode is set in config/application.rb:

config.app_mode = (ENV["SELF_HOSTED"] == "true" || ENV["SELF_HOSTING_ENABLED"] == "true" ? "self_hosted" : "managed").inquiry

Runtime topology

                         ┌─────────────────────────────┐
        Browser ───────▶ │  web  (Puma, Rails 7.2)      │
        / API client     │  - HTML via Hotwire/Turbo    │
                         │  - JSON API /api/v1          │
                         │  - Rack::Attack rate limiting │
                         └───────┬─────────────┬─────────┘
                                 │             │
                    ┌────────────▼──┐     ┌────▼─────────┐
                    │ PostgreSQL 16 │     │  Redis        │
                    │ (UUID PKs,    │     │ - Sidekiq queue│
                    │  app data)    │     │ - ActionCable  │
                    └────────────▲──┘     │ - Rails cache  │
                                 │        └────▲──────────┘
                    ┌────────────┴───────────┐ │
                    │ worker (Sidekiq)        │─┘
                    │ - syncs, imports, AI    │
                    │ - sidekiq-cron schedule │
                    └────────────┬────────────┘
                                 │
              External providers ▼ (all optional, via Provider::Registry)
        Plaid (bank sync) · Synth (prices/FX) · OpenAI (assistant) ·
        Stripe (billing, managed only) · GitHub (release notes) ·
        S3 / Cloudflare R2 (file storage) · SMTP (email) · Sentry (errors)

Note

The web and worker containers run the same image with different commands (./bin/rails server vs. bundle exec sidekiq). They share the database and Redis. The worker is not optional: account syncs, CSV imports, AI responses, rule application, and all scheduled jobs execute there.

Component inventory

Technology stack

Core domain model

The data model centers on the Family (the tenant/household) which owns everything:

Family ──< User (member | admin | super_admin)
       ──< Account ──< Entry ──< {Transaction | Trade | Valuation}   (delegated type)
       │            ──< Holding ──> Security
       │            ──< Balance
       ──< Category (2-level, income | expense)
       ──< Tag, FamilyMerchant
       ──< Budget ──< BudgetCategory
       ──< Rule ──< Condition / Action
       ──< Import, FamilyExport, Invitation, PlaidItem
       ──< Subscription (managed mode)

Key design points, confirmed in app/models/:

• Account uses Rails delegated types (Accountable::TYPES): Depository, Investment, Property, Vehicle, CreditCard, Loan, Crypto, OtherAsset, OtherLiability. Each maps to a balance_type of :cash, :investment, or :non_cash. Account lifecycle is an AASM state machine: active, draft, disabled, pending_deletion.
• Entry is the polymorphic ledger line; its entryable is a Transaction, Trade, or Valuation. Amounts are signed (positive = outflow/expense, negative = inflow/income).
• Category supports two levels, an income/expense classification, a default bootstrap set, and a fixed color palette.
• Rule currently supports only the transaction resource type, with conditions (one level of compound nesting allowed) and at least one action.

Note

The codebase follows a deliberate "skinny controllers, fat models" convention (see the repo's CLAUDE.md): business logic lives in app/models/ as ActiveRecord models, concerns, and POROs, not in a service layer. When extending the app, put domain logic on the model that owns the question.

2. System Requirements

Image build notes (from the Dockerfile):

• Multi-stage build on ruby:3.4.4-slim; runtime packages curl, libvips, postgresql-client, libyaml.
• Runs as non-root user/group rails (uid/gid 1000).
• Assets are precompiled at build time; bootsnap is precompiled for fast boot.
• Entrypoint (bin/docker-entrypoint) prepares the database before starting.
• BUILD_COMMIT_SHA is baked in so the running app can report its commit.

3. Configuration Reference

All configuration is via environment variables (read into compose.yml/.env). The complete supported set is documented in .env.example.

Required (self-hosting)

Important

SECRET_KEY_BASE is security-critical. The sample compose.example.yml ships a default value so the app runs out of the box — replace it for any instance reachable beyond localhost. It also seeds Active Record encryption keys (below), so changing it later invalidates previously encrypted data.

Database

Cache / jobs

Active Record encryption (optional)

If unset on a self-hosted instance, these are auto-derived from SECRET_KEY_BASE (see config/initializers/active_record_encryption.rb), so encryption works with zero setup and stays stable across restarts.

Tip

To manage keys yourself, generate them with rails db:encryption:init and set all three variables. Provide all three or none — if any is blank, all three are regenerated from SECRET_KEY_BASE.

Email (SMTP)

TLS / proxy

External providers (all optional)

File storage (Active Storage)

Defaults to local disk. To use object storage, set ACTIVE_STORAGE_SERVICE and the matching credentials (config/storage.yml):

Important

If you use Disk storage (the default), the web and worker containers must share the storage volume (the Compose file mounts app-storage:/rails/storage on web). Exports generated by the worker need to be readable by the web process for download. libvips is required for image processing and is included in the image.

Sidekiq Web dashboard credentials

Caution

The /sidekiq dashboard is protected by HTTP Basic auth that defaults to maybe / maybe. Anyone who reaches it can inspect and control your job queues. Set SIDEKIQ_WEB_USERNAME and SIDEKIQ_WEB_PASSWORD to strong values, or block /sidekiq at your reverse proxy.

4. Deployment & Scaling

Reference Docker Compose

The shipped compose.example.yml defines four services sharing a bridge network:

services:
  web:      # ghcr.io/maybe-finance/maybe:latest, ports 3000:3000, volume app-storage
  worker:   # same image, command: bundle exec sidekiq
  db:       # postgres:16, volume postgres-data, healthcheck pg_isready
  redis:    # redis:latest, volume redis-data, healthcheck redis-cli ping
volumes: [ app-storage, postgres-data, redis-data ]

web and worker depend on db and redis being healthy before they start. Both restart unless-stopped.

Production deployment checklist

• [ ] Set a unique SECRET_KEY_BASE (openssl rand -hex 64).
• [ ] Set a strong POSTGRES_PASSWORD.
• [ ] Terminate TLS at a reverse proxy (Caddy, Traefik, nginx) and set RAILS_ASSUME_SSL / RAILS_FORCE_SSL appropriately.
• [ ] Set strong SIDEKIQ_WEB_USERNAME / SIDEKIQ_WEB_PASSWORD (or block /sidekiq).
• [ ] Configure SMTP if you need password resets / email confirmation / reports.
• [ ] Decide on file storage (Disk vs S3/R2) and provision a backup for the DB volume.
• [ ] Add SYNTH_API_KEY if investments or multi-currency are in use.
• [ ] Add OPENAI_ACCESS_TOKEN (with spend limits) if AI is wanted.
• [ ] Pin the image tag you've tested rather than tracking a moving latest.

Pinning and updating

image: ghcr.io/maybe-finance/maybe:stable   # latest tagged release
# image: ghcr.io/maybe-finance/maybe:latest # latest commit

docker compose pull
docker compose build
docker compose up --no-deps -d web worker

Warning

The entrypoint runs database preparation on start. Take a database backup before applying an update that may include migrations, especially since upstream is no longer publishing new releases and you may be building from source.

Scaling

• Vertical: raise RAILS_MAX_THREADS to give Puma and Sidekiq more concurrency on a larger box.

• Horizontal worker: run additional worker replicas; Sidekiq coordinates through Redis. Queues and weights are fixed in config/sidekiq.yml:

  concurrency: <%= ENV.fetch("RAILS_MAX_THREADS") { 3 } %>
  queues:
    - [scheduled, 10]
    - [high_priority, 4]
    - [medium_priority, 2]
    - [low_priority, 1]
    - [default, 1]
  

• For a single household, one web and one worker are typically plenty.

5. Operations

Health and status

Background jobs

All asynchronous work runs as Sidekiq jobs (app/jobs/). The most important:

ApplicationJob retries on ActiveRecord::Deadlocked and discards on deserialization errors; the default queue is low_priority.

Scheduled (cron) jobs

Defined in config/schedule.yml and run by sidekiq-cron:

Note

sidekiq-cron is configured with a 10-minute "catch-up" grace window (reschedule_grace_period = 600) so a cron tick that lands during a worker redeploy still fires. ImportMarketDataJob and SecurityHealthCheckJob no-op in development.

Backups and restore

Tip

Two complementary backups: (1) application-level via Settings → Profile → Export (a portable ZIP per family), and (2) infrastructure-level via the PostgreSQL postgres-data volume plus your Active Storage location.

A volume-level reset (destructive — wipes all data), per the hosting docs:

docker compose down
docker volume rm maybe_postgres-data
docker compose up
docker exec -it maybe-postgres-1 psql -U maybe -d maybe_production -c "SELECT 1;"

Cache management

Admins can clear computed/cached financial data from Settings → Self-Hosting → Clear cache, which enqueues DataCacheClearJob (drops exchange rates, security prices, balances, and holdings, then triggers a fresh sync).

6. Performance

• YJIT is enabled after initialization (enable_yjit.rb) for a free Ruby-level speedup.
• Caching: family- and entry-level cache keys are built from latest_sync_completed_at and max updated_at timestamps (Family#build_cache_key, entries_cache_version) so aggregations invalidate automatically when data changes. Sparkline and chart endpoints use HTTP conditional GET (stale? with ETag + last_modified) to return 304 Not Modified and skip expensive series computation.
• Market-data batching: ImportMarketDataJob pre-fetches the prices and FX rates all families need once per day, so individual account syncs don't redo overlapping work (e.g. a common ticker like AAPL).
• Profiling tools (development): Rack::MiniProfiler (with skip paths configured), Vernier/Stackprof, derailed_benchmarks, benchmark-ips.
• Query hygiene: the conventions call for avoiding N+1s with includes/joins; API and web list endpoints eager-load associations and paginate with Pagy (overflow: :last_page).

Note

Pagination defaults: the web Transactions list defaults to 20 per page; the API defaults to 25 and caps at 100 per page.

7. Security

Maybe layers several mechanisms; review each before exposing an instance publicly.

Authentication

• Web: session-based auth with has_secure_password (bcrypt). Sessions are stored as Session records keyed by a signed session_token cookie.
• API: two methods (see Api::V1::BaseController):
  • OAuth2 via Doorkeeper — Authorization: Bearer <token>.
  • API keys — X-Api-Key: <key> header, tied to a user.
• MFA: TOTP via ROTP (User#setup_mfa!/verify_otp?), issuer "Maybe Finance", with 8 single-use backup codes and a small verification drift window.

Password policy

Enforced on registration (RegistrationsController): minimum 8 characters, with at least one uppercase, one lowercase, one digit, and one special character.

API authorization, scopes, and rate limits

• Scopes are hierarchical: read is satisfied by read or read_write; write requires read_write. Doorkeeper default_scopes :read, optional_scopes :read_write. Access tokens last 1 year; refresh tokens and PKCE are enabled; token and application secrets are hashed at rest (hash_token_secrets, hash_application_secrets).
• Rate limiting is enforced two ways:
  • Application-level for API-key auth (ApiRateLimiter), emitting X-RateLimit-Limit/Remaining/Reset headers and 429 on exceed.
  • Rack::Attack (config/initializers/rack_attack.rb), enabled in production/staging:

Throttled requests get 429 with Retry-After: 60.

Warning

Rack::Attack throttling is only active in production/staging (Rails.env.production? || staging?). If you run the app in a different environment or front it directly without a proxy, add your own network-level rate limiting and IP filtering.

Data protection

• Active Record encryption protects sensitive columns (e.g. stored provider API keys); keys derive deterministically from SECRET_KEY_BASE when not set explicitly.
• Log filtering (filter_parameter_logging.rb) redacts parameters matching passw, email, secret, token, _key, crypt, salt, certificate, otp, ssn.
• UUID primary keys everywhere (generator.rb) — no guessable sequential IDs.
• CSRF protection is on for web controllers; it's deliberately skipped for the JSON API and Doorkeeper's OAuth endpoints (which use their own OAuth security), with documented rationale in doorkeeper_csrf_protection.rb.

Access control and impersonation

• Roles: member, admin, super_admin (admin? = admin or super_admin). Admin-only actions include inviting/removing members, generating invite codes, starting exports, and clearing cache.
• Impersonation (ImpersonationSession) is restricted to super_admin and requires the impersonated user's approval — a support feature, gated tightly.
• Family-scoped access: API controllers verify resources belong to the authenticated user's family (ensure_current_family_access); the OAuth resource_owner_authenticator reuses the app's session logic.

Caution

Several admin/operator surfaces are powerful: the /sidekiq dashboard (weak default Basic-auth creds), super-admin impersonation, and FamilyResetJob / DataCacheClearJob (destructive). Lock down credentials, restrict who is super_admin, and put the app behind TLS + a trusted proxy.

Hardening checklist

• [ ] Unique SECRET_KEY_BASE and POSTGRES_PASSWORD.
• [ ] Strong SIDEKIQ_WEB_USERNAME/PASSWORD, or block /sidekiq at the proxy.
• [ ] TLS terminated; RAILS_FORCE_SSL/RAILS_ASSUME_SSL set correctly.
• [ ] Enable MFA on admin accounts.
• [ ] Turn on Require invite for signup so a public URL can't be used to self-register.
• [ ] Keep OPENAI_ACCESS_TOKEN and provider keys out of source control and set OpenAI spend limits.
• [ ] Verify Rack::Attack is active in your environment (production) or add equivalent protection.

8. Developer Internals

Repository structure

Front-end architecture

• Hotwire-first: Turbo Frames/Streams drive SPA-like updates; controllers frequently respond_to with both html and turbo_stream. Native HTML elements (<dialog>, <details>) are preferred over JS widgets.
• Stimulus controllers (eager-loaded from app/javascript/controllers/index.js via the importmap) handle interactivity; component-scoped controllers live with their ViewComponent.
• Styling: Tailwind CSS v4 with a custom design system in app/assets/tailwind/maybe-design-system.css; functional tokens (text-primary, bg-container) are used rather than raw colors. Charts use D3 (time series, donut, Sankey). Lookbook previews components at /design-system.

API surface

JSON API under /api/v1 (responses rendered via Jbuilder):

The transactions endpoint filters by account(s), category/-ies, merchant(s), date range, amount range, tags, and type (income/expense), plus free-text search. Chat endpoints additionally require the user to have AI enabled and use read/ write scopes; see docs/api/chats.md in the repo for request/response shapes.

Note

Some /api/v1/test* routes exist only in the test environment for controller tests; they are not part of the production API.

Providers (integration layer)

app/models/provider/ wraps every external service behind a Provider::Registry, with concept mixins (LlmConcept, SecurityConcept, ExchangeRateConcept) so the app depends on capabilities, not vendors:

The AI assistant (Assistant) streams responses and supports tool calls that read the user's financial data; tools are wired through a FunctionToolCaller.

Data ingestion

Two paths, both worker-backed:

1. Plaid sync — PlaidItem manages a connection; Sync tracks an operation; webhooks (/webhooks/plaid, /webhooks/plaid_eu) and SyncJob keep data fresh.
2. CSV import — Import (with TransactionImport, TradeImport, MintImport subtypes) drives a multi-step flow: upload → configure/map (templates supported) → clean → confirm → publish, all via ImportJob; reversible via RevertImportJob. Imports enforce a maximum row count.

Money & multi-currency

lib/money and the Monetizable concern model amounts as value objects. config/currencies.yml defines 160+ currencies (fiat, crypto, precious metals) with symbols, precision, and formatting. A family needs a data provider (Synth) only when it holds trades or uses more than one currency (Family#requires_data_provider?).

Subscriptions / billing

Subscription mirrors Stripe statuses (trialing, active, past_due, canceled, etc.) with a 14-day trial. Self-hosted instances disable billing entirely (SubscriptionsController guards the feature when self_hosted?), so the subscription model is effectively managed-mode only.

Testing strategy

Per the repo's conventions (CLAUDE.md):

• Minitest + fixtures only — never RSpec or factories. Fixtures are kept minimal (2–3 per model); edge cases are built inline.
• VCR records external API interactions (Plaid, Stripe, OpenAI, Synth cassettes live under test/vcr_cassettes/).
• System tests (Capybara + Selenium) cover critical flows, used sparingly.
• Test boundaries: assert commands were called with correct params; assert query outputs; don't test other classes' implementation details.

Pre-PR CI workflow (also from CLAUDE.md): bin/rails test (and test:system when relevant), bin/rubocop -f github -a, bundle exec erb_lint, and bin/brakeman for static security analysis. JS/TS is linted/formatted with Biome (npm run lint / format).

Local development (contributors)

cd maybe
cp .env.local.example .env.local
bin/setup
bin/dev
# Optional demo data:
rake demo_data:default

bin/dev runs Rails, Sidekiq, and the Tailwind watcher together (Procfile.dev). A seeded login is [email removed] / password. Useful commands: bin/rails console, bin/rails db:prepare, bin/rails test test/models/account_test.rb:42.

Note

Required dev tooling matches the image: Ruby per .ruby-version (3.4.4) and PostgreSQL >9.3. libvips must be installed locally for Active Storage image processing.

Potential improvements

These are observations for anyone forking or maintaining the project; they are not defects in normal operation:

• Rules are transaction-only. Rule#registry raises UnsupportedResourceTypeError for anything but transaction. Extending to other resource types (e.g. trades) would require new registry classes.
• Rack::Attack only in production/staging. Non-production deployments get no built-in throttling; document or add protection for other environments.
• Default Sidekiq Web credentials (maybe/maybe) are a foot-gun on public instances — consider failing closed when the defaults are unchanged.
• Long-lived access tokens. OAuth access tokens default to a 1-year lifetime; tighten if your threat model warrants.
• Unmaintained upstream. With v0.6.0 as the final release, security patches to dependencies (Rails and gems) are a fork's responsibility — track CVEs in the pinned gem set.

Contributing

The repository is AGPLv3 and open to forks. To stay compliant: keep the original license, state clearly that a fork is "not affiliated with or endorsed by Maybe Finance," and do not reuse the "Maybe" name or logo (both are trademarks of Maybe Finance, Inc.). Follow the existing conventions — minimize dependencies, fat models / skinny controllers, Hotwire-first, Minitest + fixtures — and run the full pre-PR CI workflow before submitting changes.

9. Integration Points

Note

Every external integration is optional and gated on its environment variables — the app boots and runs (manual accounts, CSV import, budgeting, reporting) with none of them configured. Add providers as you need their capabilities.