Skip to content

CLAUDE.md

Latest commit

 

History

History
102 lines (76 loc) · 4.17 KB

CLAUDE.md

File metadata and controls

102 lines (76 loc) · 4.17 KB
Raw

CLAUDE.md

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

Build and Test Commands

Building

# Build the executable
go build -o dave.exe

# Download dependencies
go mod download

Testing

# Run all tests
go test ./tests/...

# Run a specific test file
go test ./tests/calculator_test.go

# Run a specific test function
go test -run TestCalculateMonthlyInterest ./tests/

Running

# Run the built executable
./dave.exe

# Or run directly with go
go run main.go

Project Architecture

Dave is a CLI debt tracking tool built with Go using the Cobra command framework and SQLite for persistence.

Core Package Structure

  • main.go: Entry point that delegates to cmd.Execute()
  • cmd/: Cobra command definitions (add, pay, remove, adjust-*, mode, snowball, reset, show)
    • root.go: Base command setup, database initialization lifecycle, and command registration
    • Each command file defines a single Cobra command
  • internal/models/: Data models and database operations
    • debt.go: Debt CRUD operations with support for position-based (#) or name-based lookup
    • payment.go: Payment history tracking
    • settings.go: User settings (sort mode, snowball amount)
  • internal/database/: SQLite database wrapper and schema management
    • db.go: Database connection wrapper
    • schema.go: Table creation and schema initialization
  • internal/calculator/: Financial calculation engine
    • interest.go: Monthly interest calculations
    • projections.go: Simulates monthly payments with compound interest to project payoff timelines
  • internal/display/: Terminal UI rendering with Lipgloss
    • table.go: Debt table formatting with ASCII art header
    • formatter.go: Currency, date, and percentage formatting utilities
    • styles.go: Lipgloss style definitions
  • internal/config/: Configuration and path management
    • paths.go: Database path resolution (~/.dave/debts.db)

Key Architecture Patterns

Database Lifecycle: The database connection is initialized in cmd/root.go's init() via Cobra's OnInitialize hook and closed in PersistentPostRun. All commands access the shared DB via GetDB().

Dual Identifier System: Most commands accept either a position number (1, 2, 3...) or creditor name. The GetDebtByIndexOrName() function handles this by attempting integer parsing first, then falling back to name lookup.

Sort Modes: Three modes control debt ordering:

  • snowball: Smallest balance first (psychological wins)
  • avalanche: Highest APR first (mathematically optimal)
  • manual: Custom ordering via custom_order column

Mode changes are handled in models/settings.go and affect how GetAllDebts() sorts results.

Projection Algorithm (calculator/projections.go): The ProjectPayoffTimeline() function simulates month-by-month payments:

  1. Apply monthly interest to all active debts
  2. Apply minimum payments to all active debts
  3. Apply snowball amount to highest-priority unpaid debt
  4. When a debt is paid off, add its minimum payment to the snowball (auto-snowball)
  5. Repeat for up to 600 months (50 years) or until all debts are paid

This simulation accounts for compound interest and the cascading snowball effect.

Hidden Paid Debts: Debts with current_balance = 0 are automatically filtered out by GetAllDebts() (via WHERE current_balance > 0), but remain in the database for historical tracking.

Payment History: The payments table tracks all payments with interest/principal breakdown. When recording a payment, the debt balance is updated and a payment record is inserted.

Data Storage

SQLite database at ~/.dave/debts.db with three tables:

  • debts: id, creditor, original_balance, current_balance, apr, minimum_payment, custom_order (nullable), created_at, updated_at
  • payments: id, debt_id (FK), amount, interest_paid, principal_paid, payment_date, created_at
  • settings: key-value pairs (sort_mode, snowball_amount)

Dependencies

  • Cobra: CLI framework for command structure
  • Lipgloss: Terminal UI styling and table rendering
  • modernc.org/sqlite: Pure-Go SQLite driver (no CGo)