docs: update CLAUDE.md with new architecture and security features

- Add test commands (npm test, npm run test:watch)
- Update architecture diagram with new directory structure
- Document security features (XSS prevention, cache validation, type safety)
- Add AI Fallback System section
- Document Major Architecture Refactoring in Recent Changes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -15,6 +15,8 @@ Cloudflare Worker-based AI server recommendation service. Uses OpenAI GPT-4o-min
 npm run dev              # Start local development server (wrangler dev)
 npm run deploy           # Deploy to Cloudflare Workers
 npm run typecheck        # TypeScript type checking
+npm test                 # Run tests (Vitest)
+npm run test:watch       # Run tests in watch mode
 
 # Database operations (D1)
 npx wrangler d1 execute cloud-instances-db --file=schema.sql        # Apply schema
@@ -33,13 +35,28 @@ src/
 ├── index.ts              # Main router, CORS, request handling
 ├── config.ts             # Configuration constants
 ├── types.ts              # TypeScript type definitions
-├── utils.ts              # Utilities (bandwidth, response, AI, benchmarks, candidates, techSpecs)
+├── region-utils.ts       # Region matching utilities
-├── region-utils.ts       # Region matching utilities (flexible region conditions)
+├── utils.ts              # Re-exports from utils/ (backward compatibility)
-└── handlers/
+├── utils/                # Modular utilities (split from monolithic utils.ts)
-    ├── health.ts         # GET /api/health
+│   ├── index.ts          # Central export point
-    ├── servers.ts        # GET /api/servers - List servers with filtering
+│   ├── http.ts           # HTTP responses, CORS, escapeHtml
-    ├── recommend.ts      # POST /api/recommend - AI-powered recommendations
+│   ├── validation.ts     # Input validation, type guards
-    └── report.ts         # GET /api/recommend/report - HTML report generation
+│   ├── bandwidth.ts      # Bandwidth estimation & cost calculation
+│   ├── cache.ts          # Caching, rate limiting
+│   ├── ai.ts             # AI prompt sanitization
+│   └── exchange-rate.ts  # Currency conversion
+├── repositories/
+│   └── AnvilServerRepository.ts  # DB queries for Anvil servers
+├── services/
+│   └── ai-service.ts     # AI recommendations & fallback logic
+├── handlers/
+│   ├── health.ts         # GET /api/health
+│   ├── servers.ts        # GET /api/servers
+│   ├── recommend.ts      # POST /api/recommend
+│   └── report.ts         # GET /api/recommend/report
+└── __tests__/
+    ├── utils.test.ts     # Validation & security tests (27 tests)
+    └── bandwidth.test.ts # Bandwidth estimation tests (28 tests)
 ```
 
 ### Key Data Flow
@@ -181,11 +198,23 @@ window.open(reportUrl); // Opens printable HTML
 
 ### Security Features
 
-- **Input validation**: Comprehensive checks with length limits (tech_stack ≤20, use_case ≤500 chars)
+- **XSS prevention**: `escapeHtml()` applied to all user data in HTML reports
+- **Input validation**: Comprehensive checks with length limits (tech_stack ≤20, use_case ≤500, region_preference ≤10 items)
+- **Cache integrity**: Validates cached JSON structure before returning
 - **Rate limiting**: 60 req/min per IP with in-memory fallback when KV unavailable
-- **SQL injection prevention**: All queries use parameterized statements
+- **SQL injection prevention**: All queries use parameterized statements via Repository pattern
 - **Security headers**: CSP, HSTS, X-Frame-Options, X-Content-Type-Options
 - **API key protection**: Keys never logged, sanitized from error messages
+- **Prompt injection protection**: `sanitizeForAIPrompt()` filters malicious patterns
+- **Type safety**: No `any` types - uses `unknown` + type guards
+
+### AI Fallback System (`services/ai-service.ts`)
+
+When OpenAI API is unavailable, the system automatically falls back to rule-based recommendations:
+- Sorts candidates by price
+- Selects 3 tiers: Budget (cheapest), Balanced (median), Premium (top 25%)
+- Provides basic capacity estimates based on vCPU count
+- Warns user that AI is temporarily unavailable
 
 ### Configuration (`config.ts`)
 
@@ -248,7 +277,33 @@ echo $REPORT_URL
 
 ## Recent Changes
 
-### Region Diversity & Bug Fixes (Latest)
+### Major Architecture Refactoring (Latest)
+
+**Security Hardening**:
+- Fixed XSS vulnerability in HTML reports with `escapeHtml()`
+- Added cache data integrity validation
+- Added `region_preference` input validation (max 10 items, 50 chars each)
+- Replaced all `any` types with `unknown` + type guards
+
+**Architecture Improvements**:
+- Split `utils.ts` (801 lines) → 6 modular files in `utils/`
+- Extracted AI logic to `services/ai-service.ts` (recommend.ts -49%)
+- Added Repository pattern: `repositories/AnvilServerRepository.ts`
+- Reduced DB query duplication across handlers
+
+**New Features**:
+- AI fallback: Rule-based recommendations when OpenAI unavailable
+- Vitest testing: 55 tests covering validation, security, bandwidth
+- Duplicate server prevention in AI recommendations
+
+**Files Added**:
+- `src/utils/{index,http,validation,bandwidth,cache,ai,exchange-rate}.ts`
+- `src/services/ai-service.ts`
+- `src/repositories/AnvilServerRepository.ts`
+- `src/__tests__/{utils,bandwidth}.test.ts`
+- `vitest.config.ts`
+
+### Region Diversity & Bug Fixes
 - **Region diversity**: No region specified → same spec from 3 different regions for comparison
 - **Cache key fix**: `region_preference` now included in cache key
 - **Server ID fix**: Changed from `ai.id` (instance) to `ap.id` (pricing) for unique region+instance identification