# MoneyMap - Codex Agent 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 complete technical documentation, see [ARCHITECTURE.md](./ARCHITECTURE.md)**

The shared architecture document provides:
- Complete technology stack and dependencies
- Core domain models and relationships
- Service layer implementations
- Database schema with all tables and relationships
- Key workflows (CSV import, categorization, receipt parsing, etc.)
- Design patterns and best practices
- Security considerations
- Performance optimizations
- Troubleshooting guide

## Agent Configuration

This file is used by Codex CLI for agent context. Claude Code users should reference [CLAUDE.md](./CLAUDE.md) instead.

## Key Features for Agents

### Transaction Management
- CSV import with duplicate detection
- Auto-categorization based on merchant patterns
- Manual category and merchant assignment
- Transfer detection between accounts

### Receipt Processing
- File upload with SHA256 deduplication
- OpenAI Vision API integration for parsing
- Line item extraction
- Parse logging and confidence tracking

### Data Organization
- Account and Card hierarchy
- Merchant normalization
- Category mapping rules with priority
- Relationship tracking (transactions ↔ receipts ↔ line items)

## Common Agent Tasks

### Code Analysis
When analyzing code, refer to [ARCHITECTURE.md](./ARCHITECTURE.md) for:
- Service interfaces and their responsibilities
- Domain model relationships
- Database constraints and cascade rules
- Performance considerations (indexes, AsNoTracking)

### Feature Implementation
1. Check [ARCHITECTURE.md](./ARCHITECTURE.md) for existing patterns
2. Follow Service Layer Pattern (business logic in services)
3. Use Result Pattern for error handling
4. Register new services in Program.cs
5. Create migrations for schema changes

### Bug Investigation
1. Review relevant service in [ARCHITECTURE.md](./ARCHITECTURE.md)
2. Check database constraints and relationships
3. Review cascade delete rules
4. Check unique indexes for duplicate constraints

### Refactoring
1. Maintain service layer separation
2. Keep interfaces for testability
3. Follow existing patterns (DI, Result Pattern, DTOs)
4. Update [ARCHITECTURE.md](./ARCHITECTURE.md) if making significant changes

## Important Constraints

- **Unique Transactions**: (Date, Amount, Name, Memo, AccountId, CardId)
- **Cascade Deletes**: Transaction → Receipts → ParseLogs/LineItems
- **Restrict Deletes**: Can't delete Account/Card with existing transactions
- **File Limits**: Receipts max 10MB, whitelist extensions only
- **API Requirements**: OpenAI API key required for receipt parsing

## Development Guidelines

1. **Always** check [ARCHITECTURE.md](./ARCHITECTURE.md) before making changes
2. **Use** existing service patterns and interfaces
3. **Follow** Single Responsibility Principle
4. **Test** with mockable interfaces
5. **Update [ARCHITECTURE.md](./ARCHITECTURE.md) when making architectural changes**

## Important: Keep Documentation Updated

**When making architectural changes, always update [ARCHITECTURE.md](./ARCHITECTURE.md):**
- Adding/removing domain models (Account, Transaction, Receipt, etc.)
- Adding/removing services or changing their responsibilities
- Modifying database schema, relationships, or constraints
- Adding new workflows or processes
- Changing design patterns or conventions
- Adding new pages or major features
- Modifying security or performance considerations

This shared documentation ensures both Claude Code and Codex CLI have accurate context for future work.

## Reference Links

- Technical Details: [ARCHITECTURE.md](./ARCHITECTURE.md)
- Claude Code Context: [CLAUDE.md](./CLAUDE.md)
- Service Layer: See ARCHITECTURE.md § Service Layer
- Database Schema: See ARCHITECTURE.md § Database Schema
- Workflows: See ARCHITECTURE.md § Key Workflows