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](./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`:
   ```csharp
   builder.Services.AddScoped<IMyService, MyService>();
   ```

### Adding a Database Migration
```bash
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](./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](./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](./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](./ARCHITECTURE.md) for comprehensive technical documentation including:
- Detailed service descriptions
- Database schema
- Key workflows
- Security considerations
- Performance optimizations
- Troubleshooting guide