From 1509bcd1307c1df89e5ef9ed764df3577dd21baf Mon Sep 17 00:00:00 2001
From: AJ <ajisaacs27@gmail.com>
Date: Sat, 25 Oct 2025 22:53:57 -0400
Subject: [PATCH] Docs: update ARCHITECTURE.md with new services
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document TransactionService and ReceiptMatchingService in the architecture documentation, including their responsibilities, key methods, matching algorithms, and design patterns.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ARCHITECTURE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 1f0f216..48d598a 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -30,6 +30,8 @@ MoneyMap follows a clean, service-oriented architecture:
 │  - TransactionImporter                      │
 │  - CardResolver                             │
 │  - TransactionCategorizer                   │
+│  - TransactionService (NEW)                 │
+│  - ReceiptMatchingService (NEW)             │
 │  - DashboardService                         │
 │  - ReceiptManager                           │
 │  - OpenAIReceiptParser                      │
@@ -252,6 +254,82 @@ Pattern-based rules for auto-categorization with merchant linking.
 
 **Location:** Services/TransactionCategorizer.cs:31-231
 
+### TransactionService (Services/TransactionService.cs)
+**Interface:** `ITransactionService`
+
+**Responsibility:** Core transaction operations including duplicate detection, retrieval, and deletion.
+
+**Key Methods:**
+- `IsDuplicateAsync(Transaction transaction)`
+  - Checks if a transaction already exists in the database
+  - Matches on: Date, Amount, Name, Memo, AccountId, and CardId
+  - Used during CSV import to prevent duplicate entries
+  - Returns boolean indicating if duplicate exists
+
+- `GetTransactionByIdAsync(long id, bool includeRelated = false)`
+  - Retrieves a transaction by ID
+  - Optional parameter to include related entities (Card, Account, Merchant, Receipts, etc.)
+  - Returns Transaction entity or null if not found
+
+- `DeleteTransactionAsync(long id)`
+  - Deletes a transaction and all related data
+  - Cascades to Receipts, ParseLogs, and LineItems
+  - Returns boolean indicating success
+
+**Design Pattern:**
+- Consolidates duplicate detection logic previously scattered across multiple PageModels
+- Single source of truth for transaction CRUD operations
+- Improves testability by separating business logic from UI layer
+
+**Location:** Services/TransactionService.cs
+
+### ReceiptMatchingService (Services/ReceiptMatchingService.cs)
+**Interface:** `IReceiptMatchingService`
+
+**Responsibility:** Match receipts to transactions using intelligent scoring based on date, merchant, and amount.
+
+**Key Methods:**
+- `FindMatchingTransactionsAsync(ReceiptMatchCriteria criteria)`
+  - Finds candidate transactions that match receipt criteria
+  - Uses multi-stage filtering and scoring algorithm
+  - Returns sorted list of `TransactionMatch` objects with relevance scores
+
+- `GetTransactionIdsWithReceiptsAsync()`
+  - Returns set of transaction IDs that already have receipts
+  - Used to exclude already-mapped transactions from matching
+
+**Matching Algorithm:**
+1. **Date Filtering:**
+   - Regular receipts: ±3 days from receipt date
+   - Bills with due dates: From receipt date to due date + 5 days (for auto-pay delays)
+   - No date: Skip date filter
+
+2. **Merchant Matching (Word-Based Scoring):**
+   - Exact match: Score = 1000
+   - Word overlap: Count matching words between receipt merchant and transaction name/merchant
+   - Splits on spaces, hyphens, underscores, periods
+   - Uses case-insensitive comparison
+   - Prioritizes merchant name over transaction description
+
+3. **Amount Tolerance:**
+   - ±10% tolerance from receipt total
+   - Marks exact matches and close matches separately
+   - Filters out transactions outside tolerance range
+
+4. **Fallback:**
+   - If no matches found and no receipt date: Returns 50 most recent unmapped transactions
+
+**DTOs:**
+- `ReceiptMatchCriteria` - Input criteria (receipt date, due date, total, merchant, exclusions)
+- `TransactionMatch` - Output with transaction details and match quality flags (IsExactAmount, IsCloseAmount)
+
+**Design Pattern:**
+- Extracts complex 140+ line matching algorithm from Receipts PageModel
+- Enables unit testing of matching logic
+- Centralizes receipt-to-transaction correlation rules
+
+**Location:** Services/ReceiptMatchingService.cs
+
 ### DashboardService (Pages/Index.cshtml.cs)
 **Interface:** `IDashboardService`