135 lines
5.2 KiB
Markdown
135 lines
5.2 KiB
Markdown
# 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
|