Restructure documentation for DRY principle

Split documentation into three files to eliminate duplication:
- ARCHITECTURE.md: Shared technical documentation (domain models,
  services, database schema, workflows, patterns)
- CLAUDE.md: Claude Code-specific context referencing ARCHITECTURE.md
- AGENTS.md: Codex agent context referencing ARCHITECTURE.md

This allows both Claude Code and Codex CLI to share the same source
of truth for architecture details while maintaining tool-specific
configuration in separate files.

Benefits:
- Single source of truth for technical details
- Easier maintenance (update once, not twice)
- Consistent documentation across tools
- Clear separation of concerns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
AJ
2025-10-12 10:24:08 -04:00
parent b2fa1d47a8
commit cecdd63767
3 changed files with 1145 additions and 855 deletions

121
CLAUDE.md Normal file
View File

@@ -0,0 +1,121 @@
# 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. Commit with descriptive message
## 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