maybe/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Development Server

• bin/dev - Start development server (Rails, Sidekiq, Tailwind CSS watcher)
• bin/rails server - Start Rails server only
• bin/rails console - Open Rails console

Testing

• bin/rails test - Run all tests
• bin/rails test:db - Run tests with database reset
• bin/rails test:system - Run system tests only
• bin/rails test test/models/account_test.rb - Run specific test file
• bin/rails test test/models/account_test.rb:42 - Run specific test at line

Linting & Formatting

• bin/rubocop - Run Ruby linter
• npm run lint - Check JavaScript/TypeScript code
• npm run lint:fix - Fix JavaScript/TypeScript issues
• npm run format - Format JavaScript/TypeScript code
• bin/brakeman - Run security analysis

Database

• bin/rails db:prepare - Create and migrate database
• bin/rails db:migrate - Run pending migrations
• bin/rails db:rollback - Rollback last migration
• bin/rails db:seed - Load seed data

Setup

• bin/setup - Initial project setup (installs dependencies, prepares database)

General Development Rules

Authentication Context

• Use Current.user for the current user. Do NOT use current_user.
• Use Current.family for the current family. Do NOT use current_family.

Development Guidelines

• Prior to generating any code, carefully read the project conventions and guidelines
• Ignore i18n methods and files. Hardcode strings in English for now to optimize speed of development
• Do not run rails server in your responses
• Do not run touch tmp/restart.txt
• Do not run rails credentials
• Do not automatically run migrations

High-Level Architecture

Application Modes

The Maybe app runs in two distinct modes:

• Managed: The Maybe team operates and manages servers for users (Rails.application.config.app_mode = "managed")
• Self Hosted: Users host the Maybe app on their own infrastructure, typically through Docker Compose (Rails.application.config.app_mode = "self_hosted")

Core Domain Model

The application is built around financial data management with these key relationships:

• User → has many Accounts → has many Transactions
• Account types: checking, savings, credit cards, investments, crypto, loans, properties
• Transaction → belongs to Category, can have Tags and Rules
• Investment accounts → have Holdings → track Securities via Trades

API Architecture

The application provides both internal and external APIs:

• Internal API: Controllers serve JSON via Turbo for SPA-like interactions
• External API: /api/v1/ namespace with Doorkeeper OAuth and API key authentication
• API responses use Jbuilder templates for JSON rendering
• Rate limiting via Rack Attack with configurable limits per API key

Sync & Import System

Two primary data ingestion methods:

1. Plaid Integration: Real-time bank account syncing
   • PlaidItem manages connections
   • Sync tracks sync operations
   • Background jobs handle data updates
2. CSV Import: Manual data import with mapping
   • Import manages import sessions
   • Supports transaction and balance imports
   • Custom field mapping with transformation rules

Background Processing

Sidekiq handles asynchronous tasks:

• Account syncing (SyncAccountsJob)
• Import processing (ImportDataJob)
• AI chat responses (CreateChatResponseJob)
• Scheduled maintenance via sidekiq-cron

Frontend Architecture

• Hotwire Stack: Turbo + Stimulus for reactive UI without heavy JavaScript
• ViewComponents: Reusable UI components in app/components/
• Stimulus Controllers: Handle interactivity, organized alongside components
• Charts: D3.js for financial visualizations (time series, donut, sankey)
• Styling: Tailwind CSS v4.x with custom design system
  • Design system defined in app/assets/tailwind/maybe-design-system.css
  • Always use functional tokens (e.g., text-primary not text-white)
  • Prefer semantic HTML elements over JS components
  • Use icon helper for icons, never lucide_icon directly

Multi-Currency Support

• All monetary values stored in base currency (user's primary currency)
• Exchange rates fetched from Synth API
• Money objects handle currency conversion and formatting
• Historical exchange rates for accurate reporting

Security & Authentication

• Session-based auth for web users
• API authentication via:
  • OAuth2 (Doorkeeper) for third-party apps
  • API keys with JWT tokens for direct API access
• Scoped permissions system for API access
• Strong parameters and CSRF protection throughout

Key Service Objects & Patterns

• Query Objects: Complex database queries isolated in app/queries/
• Service Objects: Business logic in app/services/
• Form Objects: Complex forms with validation
• Concerns: Shared functionality across models/controllers
• Jobs: Background processing logic

Testing Philosophy

• Comprehensive test coverage using Rails' built-in Minitest
• Fixtures for test data (avoid FactoryBot)
• Keep fixtures minimal (2-3 per model for base cases)
• VCR for external API testing
• System tests for critical user flows (use sparingly)
• Test helpers in test/support/ for common scenarios
• Only test critical code paths that significantly increase confidence
• Write tests as you go, when required

Performance Considerations

• Database queries optimized with proper indexes
• N+1 queries prevented via includes/joins
• Background jobs for heavy operations
• Caching strategies for expensive calculations
• Turbo Frames for partial page updates

Development Workflow

• Feature branches merged to main
• Docker support for consistent environments
• Environment variables via .env files
• Lookbook for component development (/lookbook)
• Letter Opener for email preview in development

Project Conventions

Convention 1: Minimize Dependencies

• Push Rails to its limits before adding new dependencies
• When adding dependencies, favor old and reliable over new and flashy
• Strong technical or business reason required for new dependencies

Convention 2: POROs and Concerns over Service Objects

• "Skinny controller, fat models" convention
• Everything in app/models/ folder, avoid separate folders like app/services/
• Use Rails concerns for better organization (can be one-off concerns)
• Models should answer questions about themselves (e.g., account.balance_series)

Convention 3: Leverage Hotwire and Server-Side Solutions

• Native HTML preferred over JS components (e.g., <dialog>, <details>)
• Use Turbo frames to break up pages
• Leverage query params for state over local storage
• Format values server-side, pass to Stimulus for display only
• Client-side code only where it truly shines (e.g., bulk selections)

Convention 4: Optimize for Simplicity and Clarity

• Prioritize good OOP domain design over performance
• Only focus on performance in critical/global areas
• Be mindful of N+1 queries and large data payloads

Convention 5: ActiveRecord for Complex Validations, DB for Simple Ones

• Enforce null checks, unique indexes in the DB
• ActiveRecord validations for convenience in forms
• Complex validations and business logic in ActiveRecord