MoneyMap/AGENTS.md

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

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 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 for:

• Service interfaces and their responsibilities
• Domain model relationships
• Database constraints and cascade rules
• Performance considerations (indexes, AsNoTracking)

Feature Implementation

1. Check 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
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 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 before making changes
2. Use existing service patterns and interfaces
3. Follow Single Responsibility Principle
4. Test with mockable interfaces
5. Update ARCHITECTURE.md when making architectural changes

Important: Keep Documentation Updated

When making architectural changes, always update 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
• Claude Code Context: CLAUDE.md
• Service Layer: See ARCHITECTURE.md § Service Layer
• Database Schema: See ARCHITECTURE.md § Database Schema
• Workflows: See ARCHITECTURE.md § Key Workflows