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:
121
CLAUDE.md
Normal file
121
CLAUDE.md
Normal 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
|
||||
Reference in New Issue
Block a user