From 2c74e5e403f35224f60e1bb8fa785ae58772bf1e Mon Sep 17 00:00:00 2001
From: AJ Isaacs <ajisaacs27@gmail.com>
Date: Thu, 18 Dec 2025 20:08:19 -0500
Subject: [PATCH] Docs: Document Financial Audit API in ARCHITECTURE.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for:
- FinancialAuditService responsibilities and methods
- Audit flag types and severities
- /api/audit endpoint with query parameters and response
- Version bump to 1.4 with recent changes section

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 98 insertions(+), 2 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 633940a..9394483 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -743,6 +743,42 @@ Represents a spending budget for a category or total spending.
 
 **Location:** Services/ReceiptAutoMapper.cs
 
+### FinancialAuditService (Services/FinancialAuditService.cs)
+**Interface:** `IFinancialAuditService`
+
+**Responsibility:** Generate comprehensive financial audit data for AI analysis via the `/api/audit` endpoint.
+
+**Key Methods:**
+- `GenerateAuditAsync(DateTime startDate, DateTime endDate, bool includeTransactions = false)`
+  - Aggregates all financial data for the specified period
+  - Returns `FinancialAuditResponse` with summary, budgets, categories, merchants, trends, accounts, and flags
+
+**Response Structure:**
+- `Summary` - High-level stats (income, expenses, net, average daily spend, uncategorized count)
+- `Budgets` - All active budget statuses with period info and over-budget flags
+- `SpendingByCategory` - Category breakdown with budget correlation
+- `TopMerchants` - Top 20 merchants by spending
+- `MonthlyTrends` - Month-by-month income/expense/net with top categories per month
+- `Accounts` - Per-account transaction summaries
+- `Flags` - AI-friendly alerts (over-budget, spending increases, uncategorized, etc.)
+- `Transactions` - Optional detailed transaction list
+
+**Audit Flags Generated:**
+- `OverBudget` - Budgets exceeded (Alert)
+- `HighBudgetUtilization` - Budgets at 80%+ (Warning)
+- `Uncategorized` - Transactions without categories (Warning)
+- `NegativeCashFlow` - Spending exceeds income (Alert)
+- `HighCategoryConcentration` - Category >30% of total spending (Info)
+- `SpendingIncrease` - Month-over-month increase >20% (Warning)
+- `NoBudget` - Top spending categories without budgets (Info)
+
+**Design Pattern:**
+- Orchestrates existing services (IBudgetService) and new queries
+- Single comprehensive endpoint for AI consumption
+- Excludes transfers from spending calculations
+
+**Location:** Services/FinancialAuditService.cs
+
 ### TransactionAICategorizer (Services/TransactionAICategorizer.cs)
 **Interface:** `ITransactionAICategorizer`
 
@@ -1053,6 +1089,51 @@ EF Core DbContext managing all database entities.
 
 **Location:** Pages/ReviewAISuggestionsWithProposals.cshtml.cs
 
+## API Endpoints
+
+### Financial Audit API
+**Route:** `GET /api/audit`
+
+**Purpose:** Provide comprehensive financial data for AI analysis and auditing.
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `startDate` | DateTime? | Today - 90 days | Start of audit period |
+| `endDate` | DateTime? | Today | End of audit period |
+| `includeTransactions` | bool | false | Include detailed transaction list |
+
+**Example Requests:**
+```
+GET /api/audit
+GET /api/audit?startDate=2025-01-01&endDate=2025-12-31
+GET /api/audit?startDate=2025-11-01&includeTransactions=true
+```
+
+**Response:** JSON `FinancialAuditResponse` object containing:
+- `generatedAt` - Timestamp of audit generation
+- `periodStart`, `periodEnd` - Audit date range
+- `summary` - High-level financial statistics
+- `budgets` - Active budget statuses
+- `spendingByCategory` - Category breakdown with budget correlation
+- `topMerchants` - Top 20 merchants by spending
+- `monthlyTrends` - Month-by-month trends
+- `accounts` - Per-account summaries
+- `flags` - AI-friendly alerts and observations
+- `transactions` - Detailed transaction list (optional)
+
+**Authentication:** None (localhost/personal use only)
+
+**Use Cases:**
+- AI-powered financial analysis and recommendations
+- Spending pattern identification
+- Budget compliance monitoring
+- External tool integration
+
+**Implementation:** Minimal API endpoint in Program.cs, backed by `IFinancialAuditService`
+
+**Location:** Program.cs:99-112
+
 ## Configuration
 
 ### appsettings.json
@@ -1602,10 +1683,25 @@ MoneyMap demonstrates a well-architected ASP.NET Core application with clear sep
 
 ---
 
-**Last Updated:** 2025-12-11
-**Version:** 1.3
+**Last Updated:** 2025-12-15
+**Version:** 1.4
 **Framework:** ASP.NET Core 8.0 / EF Core 9.0
 
+## Recent Changes (v1.4)
+
+### Financial Audit API
+- **New Endpoint**: `GET /api/audit` - Comprehensive financial data for AI analysis
+- **FinancialAuditService**: New service orchestrating financial data aggregation
+- **Audit Response**: Summary stats, budgets, categories, merchants, trends, accounts
+- **AI Flags**: Pre-computed observations (over-budget, spending increases, uncategorized)
+- **Configurable Period**: Query parameters for date range and transaction inclusion
+
+### Technical Details
+- Implemented using Minimal API pattern (no controllers needed)
+- DTOs in `Models/Api/FinancialAuditModels.cs`
+- Excludes transfers from spending calculations
+- Correlates category spending with budget limits
+
 ## Recent Changes (v1.3)
 
 ### Budget Tracking Feature