MoneyMap/CLAUDE.md

MoneyMap - Claude Code Context

Quick Overview

MoneyMap is an ASP.NET Core 8.0 Razor Pages application for personal finance tracking. Users can import bank transaction CSVs, categorize expenses, attach receipt images/PDFs, and parse receipts using OpenAI's Vision API.

Architecture Documentation

For detailed technical documentation, see ARCHITECTURE.md

The architecture document contains:

• Complete technology stack
• Core domain models (Transaction, Receipt, Card, Account, Merchant, etc.)
• Service layer details (TransactionImporter, CardResolver, TransactionCategorizer, etc.)
• Database schema and relationships
• Key workflows and design patterns
• Security and performance considerations

Project Structure

MoneyMap/
├── Data/
│   └── MoneyMapContext.cs          # EF Core DbContext
├── Models/
│   ├── Account.cs                  # Bank accounts
│   ├── Card.cs                     # Payment cards
│   ├── Merchant.cs                 # Merchants/vendors
│   ├── Transaction.cs              # Core transaction entity
│   ├── Receipt.cs                  # Receipt files
│   ├── ReceiptLineItem.cs          # Parsed line items
│   └── ReceiptParseLog.cs          # Parse attempt logs
├── Services/
│   ├── TransactionCategorizer.cs   # Auto-categorization logic
│   ├── ReceiptManager.cs           # Receipt upload/storage
│   └── OpenAIReceiptParser.cs      # AI-powered receipt parsing
├── Pages/
│   ├── Index.cshtml[.cs]           # Dashboard
│   ├── Upload.cshtml[.cs]          # CSV import
│   ├── Transactions.cshtml[.cs]    # Transaction list
│   ├── EditTransaction.cshtml[.cs] # Edit transaction
│   ├── ViewReceipt.cshtml[.cs]     # Receipt details
│   ├── CategoryMappings.cshtml[.cs]# Category rules
│   ├── Merchants.cshtml[.cs]       # Merchant management
│   └── Recategorize.cshtml[.cs]    # Bulk recategorization
└── Program.cs                      # DI configuration

Common Development Tasks

Adding a New Page

1. Create .cshtml and .cshtml.cs files in Pages/
2. Inherit from PageModel
3. Add route via @page directive
4. Register dependencies in constructor via DI

Adding a New Service

1. Create interface in appropriate namespace
2. Create implementation class
3. Register in Program.cs:

   builder.Services.AddScoped<IMyService, MyService>();
   

Adding a Database Migration

dotnet ef migrations add MigrationName
dotnet ef database update

Modifying Domain Models

1. Update model class in Models/
2. Update MoneyMapContext.OnModelCreating() if needed (relationships, indexes)
3. Create and apply migration

Key Design Principles

1. Service Layer Pattern: Business logic lives in services, not pages
2. Result Pattern: Services return result objects (not exceptions)
3. Dependency Injection: All services injected via interfaces
4. Single Responsibility: Each service has one clear purpose
5. Clean Architecture: UI → Services → Data Access

Important Notes

• Duplicate Prevention: Transactions have a unique constraint on (Date, Amount, Name, Memo, AccountId, CardId)
• Cascade Deletes: Deleting a transaction cascades to receipts, parse logs, and line items
• Merchant Assignment: Category mappings can auto-assign merchants to transactions
• Transfer Detection: Transactions with TransferToAccountId are identified as transfers
• Receipt Parsing: OpenAI API key required for receipt parsing (env var OPENAI_API_KEY)

Development Workflow

1. Read ARCHITECTURE.md for technical details
2. Make changes to models, services, or pages
3. Test locally
4. Create database migration if schema changed
5. Update ARCHITECTURE.md if architecture changes (new models, services, workflows, etc.)
6. Commit with descriptive message

Important: Keep Documentation Updated

When making architectural changes, always update ARCHITECTURE.md:

• Adding/removing domain models
• Adding/removing services or changing their responsibilities
• Modifying database schema or relationships
• Adding new workflows or processes
• Changing design patterns or conventions
• Adding new pages or major features

This ensures both Claude Code and Codex CLI have accurate, up-to-date context.

Configuration

See appsettings.json:

• ConnectionStrings:MoneyMapDb - SQL Server connection
• OpenAI:ApiKey - OpenAI API key (optional, use env var instead)
• Receipts:StoragePath - Receipt storage location (relative to wwwroot)

Testing

• All services use interfaces for mockability
• Use in-memory database for integration tests
• Mock IReceiptParser to avoid OpenAI API calls in tests

Questions?

Refer to ARCHITECTURE.md for comprehensive technical documentation including:

• Detailed service descriptions
• Database schema
• Key workflows
• Security considerations
• Performance optimizations
• Troubleshooting guide