chore: update docs

.gitea/CLAUDE.md

@@ -0,0 +1,14 @@
+# .gitea/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `PULL_REQUEST_TEMPLATE.md` | PR template | Creating pull requests |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `workflows/` | CI/CD workflow definitions | Pipeline configuration |
+| `ISSUE_TEMPLATE/` | Issue templates (bug, feature, chore) | Creating issues |

CLAUDE.md

@@ -8,6 +8,9 @@ Single-tenant vehicle management application with 9-container architecture (6 ap
 | ---- | ---- | ------------ |
 | `Makefile` | Build, test, deploy commands | Running any make command |
 | `docker-compose.yml` | Development container orchestration | Local development setup |
+| `docker-compose.staging.yml` | Staging container orchestration | Staging deployment |
+| `docker-compose.prod.yml` | Production container orchestration | Production deployment |
+| `docker-compose.blue-green.yml` | Blue-green deployment orchestration | Zero-downtime deploys |
 | `package.json` | Root workspace dependencies | Dependency management |
 | `README.md` | Project overview | First-time setup |
 
@@ -17,13 +20,17 @@ Single-tenant vehicle management application with 9-container architecture (6 ap
 | --------- | ---- | ------------ |
 | `backend/` | Fastify API server with feature capsules | Backend development |
 | `frontend/` | React/Vite SPA with MUI | Frontend development |
+| `ocr/` | Python OCR microservice (Tesseract) | OCR pipeline, receipt/VIN extraction |
 | `docs/` | Project documentation hub | Architecture, APIs, testing |
-| `config/` | Configuration files (Traefik, monitoring) | Infrastructure setup |
+| `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
-| `scripts/` | Utility scripts (backup, deploy) | Automation tasks |
+| `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks |
 | `.ai/` | AI context and workflow contracts | AI-assisted development |
 | `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
 | `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
 | `ansible/` | Ansible deployment playbooks | Server provisioning |
+| `certs/` | TLS certificates | SSL/TLS configuration |
+| `secrets/` | Docker secrets (Stripe keys, Traefik) | Secret management |
+| `data/` | Persistent data volumes (backups, documents) | Storage paths, volume mounts |
 
 ## Build for staging and production. NOT FOR DEVELOPMENT
 

ansible/CLAUDE.md

@@ -0,0 +1,11 @@
+# ansible/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `deploy-production-runner.yml` | Production runner deployment | Production deployments |
+| `deploy-staging-runner.yml` | Staging runner deployment | Staging deployments |
+| `inventory.yml` | Server inventory | Server host configuration |
+| `inventory.yml.example` | Example inventory template | Setting up new environments |
+| `config.yaml.j2` | Jinja2 config template | Runner configuration |

backend/CLAUDE.md

@@ -7,7 +7,8 @@
 | `README.md` | Backend quickstart and commands | Getting started with backend development |
 | `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
 | `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
-| `jest.config.ts` | Jest test configuration | Test setup, coverage settings |
+| `eslint.config.js` | ESLint configuration | Linting rules, code style |
+| `jest.config.js` | Jest test configuration | Test setup, coverage settings |
 | `Dockerfile` | Container build definition | Docker builds, deployment |
 
 ## Subdirectories
@@ -15,4 +16,4 @@
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
 | `src/` | Application source code | Any backend development |
-| `scripts/` | Utility scripts | Database scripts, automation |
+| `scripts/` | Utility scripts (docker-entrypoint) | Container startup, automation |

backend/src/_system/CLAUDE.md

@@ -0,0 +1,10 @@
+# _system/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `cli/` | CLI commands and tools | Running backend CLI commands |
+| `migrations/` | Database migration runner | Running or writing migrations |
+| `schema/` | Database schema generation | Schema export, documentation |
+| `scripts/` | System utility scripts | Database maintenance, automation |

backend/src/features/CLAUDE.md

@@ -1,7 +1,5 @@
 # backend/src/features/
 
-Feature capsule directory. Each feature is 100% self-contained with api/, domain/, data/, migrations/, tests/.
-
 ## Subdirectories
 
 | Directory | What | When to read |
@@ -16,8 +14,10 @@ Feature capsule directory. Each feature is 100% self-contained with api/, domain
 | `notifications/` | Email and push notifications | Alert system, email templates |
 | `ocr/` | OCR proxy to mvp-ocr service | Image text extraction, async jobs |
 | `onboarding/` | User onboarding flow | First-time user setup |
+| `ownership-costs/` | Ownership cost tracking and reports | Cost aggregation, expense analysis |
 | `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation |
 | `stations/` | Gas station search and favorites | Google Maps integration, station data |
+| `subscriptions/` | Stripe payment and billing | Subscription tiers, donations, webhooks |
 | `terms-agreement/` | Terms & Conditions acceptance audit | Signup T&C, legal compliance |
 | `user-export/` | User data export | GDPR compliance, data portability |
 | `user-import/` | User data import | Restore from backup, data migration |

backend/src/features/admin/CLAUDE.md

@@ -0,0 +1,18 @@
+# admin/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding admin functionality |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core admin logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `scripts/` | Admin utility scripts | Admin automation |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/audit-log/CLAUDE.md

@@ -1,12 +1,11 @@
 # audit-log/
 
-Centralized audit logging system for tracking all user and system actions.
-
 ## Files
 
 | File | What | When to read |
 | ---- | ---- | ------------ |
-| `README.md` | Architecture and API documentation | Understanding audit log system |
+| `README.md` | Architecture, usage patterns, categories | Understanding audit log system |
+| `audit-log.instance.ts` | Singleton service instance | Cross-feature logging integration |
 
 ## Subdirectories
 
@@ -18,38 +17,3 @@ Centralized audit logging system for tracking all user and system actions.
 | `jobs/` | Scheduled cleanup job | Retention policy |
 | `migrations/` | Database schema | Schema changes |
 | `__tests__/` | Integration tests | Adding or modifying tests |
-
-## Key Files
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `audit-log.instance.ts` | Singleton service instance | Cross-feature logging |
-| `domain/audit-log.types.ts` | Types, categories, severities | Type definitions |
-| `domain/audit-log.service.ts` | Core logging operations | Creating/searching logs |
-| `data/audit-log.repository.ts` | Database queries | Data access patterns |
-| `jobs/cleanup.job.ts` | 90-day retention cleanup | Retention enforcement |
-
-## Usage
-
-Import the singleton for cross-feature logging:
-
-```typescript
-import { auditLogService } from '../../audit-log';
-
-// Log with convenience methods
-await auditLogService.info('vehicle', userId, 'Vehicle created', 'vehicle', vehicleId);
-await auditLogService.warning('auth', userId, 'Password reset requested');
-await auditLogService.error('system', null, 'Backup failed', 'backup', backupId);
-```
-
-## Categories
-
-- `auth`: Login, logout, password changes
-- `vehicle`: Vehicle CRUD operations
-- `user`: User management actions
-- `system`: Backups, imports/exports
-- `admin`: Admin-specific actions
-
-## Retention
-
-Logs older than 90 days are automatically deleted by a daily cleanup job (3 AM).

backend/src/features/auth/CLAUDE.md

@@ -0,0 +1,16 @@
+# auth/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding auth flow |
+| `index.ts` | Feature barrel export | Importing auth services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core auth logic |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/backup/CLAUDE.md

@@ -1,7 +1,5 @@
 # backup/
 
-Complete backup and restore system with tiered retention.
-
 ## Files
 
 | File | What | When to read |
@@ -18,13 +16,3 @@ Complete backup and restore system with tiered retention.
 | `jobs/` | Scheduled job handlers | Cron job modifications |
 | `migrations/` | Database schema | Schema changes |
 | `tests/` | Unit and integration tests | Adding or modifying tests |
-
-## Key Files
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `domain/backup.types.ts` | Types, constants, TIERED_RETENTION | Type definitions |
-| `domain/backup.service.ts` | Core backup operations | Creating/managing backups |
-| `domain/backup-classification.service.ts` | Tiered retention classification | Category/expiration logic |
-| `domain/backup-retention.service.ts` | Retention enforcement | Deletion logic |
-| `data/backup.repository.ts` | Database queries | Data access patterns |

backend/src/features/documents/CLAUDE.md

@@ -0,0 +1,18 @@
+# documents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding document management |
+| `index.ts` | Feature barrel export | Importing document services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core document logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/fuel-logs/CLAUDE.md

@@ -0,0 +1,21 @@
+# fuel-logs/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding fuel log tracking |
+| `index.ts` | Feature barrel export | Importing fuel-log services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core fuel-log logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Fuel-log design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | External service integrations | Third-party API work |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/maintenance/CLAUDE.md

@@ -0,0 +1,21 @@
+# maintenance/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding maintenance tracking |
+| `index.ts` | Feature barrel export | Importing maintenance services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core maintenance logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Maintenance design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | External service integrations | Third-party API work |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/notifications/CLAUDE.md

@@ -0,0 +1,19 @@
+# notifications/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding notification system |
+| `index.ts` | Feature barrel export | Importing notification services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, email layout, types | Core notification logic |
+| `data/` | Repository, database queries | Database operations |
+| `jobs/` | Scheduled notification jobs | Background notification processing |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/ocr/CLAUDE.md

@@ -0,0 +1,16 @@
+# ocr/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding OCR proxy |
+| `index.ts` | Feature barrel export | Importing OCR services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, types | Core OCR proxy logic |
+| `external/` | External OCR service client | OCR service integration |

backend/src/features/onboarding/CLAUDE.md

@@ -0,0 +1,17 @@
+# onboarding/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding onboarding flow |
+| `index.ts` | Feature barrel export | Importing onboarding services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core onboarding logic |
+| `data/` | Repository, database queries | Database operations |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/ownership-costs/CLAUDE.md

@@ -0,0 +1,17 @@
+# ownership-costs/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding cost tracking |
+| `index.ts` | Feature barrel export | Importing ownership-cost services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core cost calculation logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |

backend/src/features/platform/CLAUDE.md

@@ -0,0 +1,20 @@
+# platform/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding platform/VIN services |
+| `index.ts` | Feature barrel export | Importing platform services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core platform logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Platform design details |
+| `models/` | Data models and interfaces | Type definitions |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/stations/CLAUDE.md

@@ -0,0 +1,23 @@
+# stations/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding station search |
+| `COMMUNITY-STATIONS.md` | Community station pricing design | Community-contributed data |
+| `index.ts` | Feature barrel export | Importing station services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core station logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Station design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | Google Maps API integration | Maps API work |
+| `jobs/` | Scheduled station jobs | Background station processing |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/subscriptions/CLAUDE.md

@@ -1,12 +1,10 @@
-# backend/src/features/subscriptions/
+# subscriptions/
-
-Stripe payment integration for subscription tiers and donations.
 
 ## Files
 
 | File | What | When to read |
 | ---- | ---- | ------------ |
-| `README.md` | Feature overview with architecture diagram | Understanding subscription flow |
+| `README.md` | Feature overview, API endpoints, configuration | Understanding subscription flow |
 
 ## Subdirectories
 
@@ -15,44 +13,7 @@ Stripe payment integration for subscription tiers and donations.
 | `api/` | HTTP controllers and routes | API endpoint changes |
 | `domain/` | Services and type definitions | Business logic changes |
 | `data/` | Repository for database operations | Database queries |
-| `external/stripe/` | Stripe API client wrapper | Stripe integration |
+| `external/` | Stripe API client wrapper | Stripe integration |
 | `migrations/` | Database schema | Schema changes |
 | `jobs/` | Scheduled background jobs | Grace period processing |
-
+| `tests/` | Unit and integration tests | Adding or modifying tests |
-## Key Patterns
-
-- Repository mapRow() converts snake_case to camelCase
-- Webhook idempotency via stripe_event_id unique constraint
-- Tier sync to user_profiles.subscription_tier on changes
-- Grace period: 30 days after payment failure
-- Vehicle selections for tier downgrades (not deleted, just gated)
-
-## API Endpoints
-
-### Subscriptions (Authenticated)
-- GET /api/subscriptions - Current subscription
-- POST /api/subscriptions/checkout - Create subscription
-- POST /api/subscriptions/cancel - Schedule cancellation
-- POST /api/subscriptions/reactivate - Cancel pending cancellation
-- POST /api/subscriptions/downgrade - Downgrade with vehicle selection
-- PUT /api/subscriptions/payment-method - Update payment
-- GET /api/subscriptions/invoices - Billing history
-
-### Donations (Authenticated)
-- POST /api/donations - Create payment intent
-- GET /api/donations - Donation history
-
-### Webhooks (Public)
-- POST /api/webhooks/stripe - Stripe webhook (signature verified)
-
-## Configuration
-
-### Secrets (files via config-loader)
-- `/run/secrets/stripe-secret-key` - Stripe API secret key
-- `/run/secrets/stripe-webhook-secret` - Stripe webhook signing secret
-
-### Environment Variables (docker-compose)
-- STRIPE_PRO_MONTHLY_PRICE_ID
-- STRIPE_PRO_YEARLY_PRICE_ID
-- STRIPE_ENTERPRISE_MONTHLY_PRICE_ID
-- STRIPE_ENTERPRISE_YEARLY_PRICE_ID

backend/src/features/terms-agreement/CLAUDE.md

@@ -0,0 +1,17 @@
+# terms-agreement/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding T&C acceptance |
+| `index.ts` | Feature barrel export | Importing terms services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `domain/` | Business logic, services, types | Core terms logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/user-export/CLAUDE.md

@@ -0,0 +1,16 @@
+# user-export/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding data export |
+| `index.ts` | Feature barrel export | Importing export services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core export logic |
+| `tests/` | Unit tests | Adding or modifying tests |

backend/src/features/user-import/CLAUDE.md

@@ -4,35 +4,13 @@
 
 | File | What | When to read |
 | ---- | ---- | ------------ |
-| `README.md` | Feature overview, architecture, API endpoints, performance benchmarks | Understanding user-import functionality, import modes, tradeoffs |
+| `README.md` | Feature overview, architecture, API endpoints, benchmarks | Understanding import functionality, modes, tradeoffs |
 | `index.ts` | Feature barrel export | Importing user-import service or types |
 
 ## Subdirectories
 
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
-| `domain/` | Core business logic: import orchestration, archive extraction, types | Implementing import logic, understanding data flow |
+| `domain/` | Import orchestration, archive extraction, types | Implementing import logic, data flow |
-| `api/` | HTTP handlers, route definitions, validation schemas | API endpoint development, request handling |
+| `api/` | HTTP handlers, route definitions, validation | API endpoint development |
-| `tests/` | Integration tests with performance benchmarks | Testing, understanding test scenarios |
+| `tests/` | Integration tests with performance benchmarks | Testing, test scenarios |
-
-## domain/
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `user-import.types.ts` | Type definitions for manifest, validation, preview, results, config | Understanding data structures, import contracts |
-| `user-import.service.ts` | Main import orchestration: merge/replace modes, batch operations | Import workflow, conflict resolution, transaction handling |
-| `user-import-archive.service.ts` | Archive extraction, validation, manifest parsing | Archive format validation, file extraction logic |
-
-## api/
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `user-import.controller.ts` | HTTP handlers for upload, import, preview endpoints | Multipart upload handling, endpoint implementation |
-| `user-import.routes.ts` | Fastify route registration | Route configuration, middleware setup |
-| `user-import.validation.ts` | Zod schemas for request validation | Request validation rules |
-
-## tests/
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `user-import.integration.test.ts` | End-to-end tests: export-import cycle, performance, conflicts, replace mode | Test scenarios, performance requirements, error handling |

backend/src/features/user-preferences/CLAUDE.md

@@ -0,0 +1,14 @@
+# user-preferences/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding user preferences API |
+| `index.ts` | Feature barrel export | Importing preference services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |

backend/src/features/user-profile/CLAUDE.md

@@ -0,0 +1,18 @@
+# user-profile/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding profile management |
+| `index.ts` | Feature barrel export | Importing profile services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core profile logic |
+| `data/` | Repository, database queries | Database operations |
+| `jobs/` | Scheduled profile jobs | Background profile processing |
+| `migrations/` | Database schema | Schema changes |

backend/src/features/vehicles/CLAUDE.md

@@ -0,0 +1,21 @@
+# vehicles/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding vehicle management |
+| `index.ts` | Feature barrel export | Importing vehicle services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core vehicle logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Vehicle design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | External service integrations (NHTSA) | VIN decoding, third-party APIs |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |

backend/src/features/vehicles/external/CLAUDE.md

@@ -1,43 +1,13 @@
 # vehicles/external/
 
-External service integrations for the vehicles feature.
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Integration patterns, adding new services | Understanding external service conventions |
 
 ## Subdirectories
 
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
 | `nhtsa/` | NHTSA vPIC API client for VIN decoding | VIN decode feature work |
-
-## Integration Pattern
-
-External integrations follow a consistent pattern:
-
-1. **Client class** (`{service}.client.ts`) - axios-based HTTP client with:
-   - Timeout configuration (prevent hanging requests)
-   - Error handling with specific error types
-   - Caching strategy (database or Redis)
-   - Input validation before API calls
-
-2. **Types file** (`{service}.types.ts`) - TypeScript interfaces for:
-   - Raw API response types
-   - Mapped internal types (camelCase)
-   - Error types
-
-3. **Cache strategy** - Each integration defines:
-   - Cache location (vin_cache table for NHTSA)
-   - TTL (1 year for static vehicle data)
-   - Cache invalidation rules (if applicable)
-
-## Adding New Integrations
-
-To add a new external service (e.g., Carfax, KBB):
-
-1. Create subdirectory: `external/{service}/`
-2. Add client: `{service}.client.ts` following NHTSAClient pattern
-3. Add types: `{service}.types.ts`
-4. Update this CLAUDE.md with new directory
-5. Add tests in `tests/unit/{service}.client.test.ts`
-
-## See Also
-
-- `../../../stations/external/google-maps/` - Sister pattern for Google Maps integration

backend/src/features/vehicles/external/README.md

@@ -0,0 +1,25 @@
+# External Service Integrations
+
+## Overview
+
+External integrations for the vehicles feature, following a consistent client/types/cache pattern.
+
+## Integration Pattern
+
+Each integration follows this structure:
+
+1. **Client class** (`{service}.client.ts`) - axios-based HTTP client with timeout, error handling, caching, and input validation
+2. **Types file** (`{service}.types.ts`) - Raw API response types, mapped internal types (camelCase), error types
+3. **Cache strategy** - Each integration defines cache location, TTL, and invalidation rules
+
+## Adding New Integrations
+
+1. Create subdirectory: `external/{service}/`
+2. Add client: `{service}.client.ts` following NHTSAClient pattern
+3. Add types: `{service}.types.ts`
+4. Update `CLAUDE.md` with new directory
+5. Add tests in `tests/unit/{service}.client.test.ts`
+
+## See Also
+
+- `../../../stations/external/google-maps/` - Sister pattern for Google Maps integration

config/CLAUDE.md

@@ -1,13 +1,14 @@
 # config/
 
-Configuration files for the 9-container architecture (6 application + 3 logging).
-
 ## Subdirectories
 
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
-| `app/` | Application configuration | App-specific settings |
+| `app/` | Application environment configuration | App-specific settings |
-| `deployment/` | Deployment configuration | Deploy scripts, environment configs |
+| `alloy/` | Grafana Alloy log collector config | Log collection pipeline |
-| `monitoring/` | Monitoring and alerts | Prometheus, alerting rules |
+| `deployment/` | Deployment environment configs | Deploy scripts, environment configs |
-| `shared/` | Shared configuration | Cross-service settings |
+| `grafana/` | Grafana dashboards and datasources | Log visualization setup |
+| `loki/` | Loki log storage config | Log storage, retention |
+| `monitoring/` | Monitoring and alert rules | Alerting rules, health checks |
+| `shared/` | Shared cross-service configuration | Cross-service settings |
 | `traefik/` | Traefik reverse proxy config | Routing, SSL, middleware |

docs/CLAUDE.md

@@ -18,4 +18,5 @@
 | `AUDIT.md` | Audit documentation | Security audits, compliance |
 | `MVP-COLOR-SCHEME.md` | Color scheme reference | UI styling decisions |
 | `LOGGING.md` | Unified logging system | Log levels, correlation IDs, Grafana |
-
+| `ocr-pipeline-tech-stack.md` | OCR pipeline technology decisions | OCR architecture, Tesseract setup |
+| `TIER-GATING.md` | Subscription tier gating rules | Feature access by tier, vehicle limits |

frontend/CLAUDE.md

@@ -8,8 +8,11 @@
 | `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
 | `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
 | `vite.config.ts` | Vite build configuration | Build optimization, plugins |
+| `eslint.config.js` | ESLint configuration | Linting rules, code style |
 | `jest.config.ts` | Jest test configuration | Test setup |
 | `tailwind.config.js` | Tailwind CSS configuration | Styling, theme customization |
+| `index.html` | HTML entry point | SPA shell, meta tags |
+| `nginx.conf` | Nginx server configuration | Production serving, SPA routing |
 | `Dockerfile` | Container build definition | Docker builds, deployment |
 
 ## Subdirectories

frontend/src/CLAUDE.md

@@ -17,4 +17,6 @@
 | `core/` | Shared infrastructure (auth, api, store) | Cross-cutting concerns |
 | `components/` | Root-level shared components | App-wide UI components |
 | `pages/` | Page-level components | Page structure, routing targets |
+| `shared/` | Shared feature components (CameraCapture) | Cross-feature reusable components |
 | `shared-minimal/` | Minimal shared UI (skeletons, theme) | Reusable UI primitives |
+| `utils/` | General utilities (logger) | Logging, helper functions |

frontend/src/features/CLAUDE.md

@@ -1,7 +1,5 @@
 # frontend/src/features/
 
-Feature module directory. Each feature contains pages/, components/, hooks/, api/, types/.
-
 ## Subdirectories
 
 | Directory | What | When to read |
@@ -14,6 +12,8 @@ Feature module directory. Each feature contains pages/, components/, hooks/, api
 | `maintenance/` | Maintenance record UI | Service tracking, reminders |
 | `notifications/` | Notification display | Alert UI, notification center |
 | `onboarding/` | Onboarding wizard | First-time user experience |
+| `ownership-costs/` | Ownership cost tracking UI | Cost displays, expense forms |
 | `settings/` | User settings pages | Preferences, account settings |
 | `stations/` | Gas station finder UI | Station search, favorites, map |
+| `subscription/` | Subscription and billing UI | Stripe integration, plan management |
 | `vehicles/` | Vehicle management UI | Vehicle list, details, forms |

frontend/src/features/subscription/CLAUDE.md

@@ -1,12 +1,11 @@
-# frontend/src/features/subscription/
+# subscription/
-
-Subscription and billing management feature with Stripe integration.
 
 ## Files
 
 | File | What | When to read |
 | ---- | ---- | ------------ |
 | `README.md` | Feature overview and API integration | Understanding subscription flow |
+| `index.ts` | Feature barrel export | Importing subscription components |
 
 ## Subdirectories
 
@@ -19,15 +18,3 @@ Subscription and billing management feature with Stripe integration.
 | `pages/` | Desktop subscription page | Desktop implementation |
 | `mobile/` | Mobile subscription screen | Mobile implementation |
 | `constants/` | Subscription plan configurations | Plan pricing and features |
-
-## Key Patterns
-
-- Desktop: MUI components with sx props
-- Mobile: Tailwind classes with GlassCard
-- Stripe Elements for payment methods
-- React Query for data fetching
-- Toast notifications for user feedback
-
-## Environment Variables
-
-- `VITE_STRIPE_PUBLISHABLE_KEY` - Required for Stripe Elements initialization

frontend/src/shared/CLAUDE.md

@@ -1,32 +1,7 @@
 # frontend/src/shared/
 
-Shared components that are reusable across multiple features.
-
 ## Subdirectories
 
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
-| `components/CameraCapture/` | Camera capture with crop tool | Building OCR features, image upload |
+| `components/` | Shared components (CameraCapture) | Cross-feature reusable components |
-
-## Components
-
-### CameraCapture
-
-Full-featured camera capture component with:
-- `getUserMedia` API for camera access
-- Translucent guidance overlays (VIN, receipt, document)
-- Post-capture crop tool
-- File input fallback for desktop/unsupported browsers
-- HEIC, JPEG, PNG support
-
-Usage:
-```tsx
-import { CameraCapture } from '@/shared/components/CameraCapture';
-
-<CameraCapture
-  onCapture={(file, croppedFile) => handleCapture(file, croppedFile)}
-  onCancel={() => setShowCamera(false)}
-  guidanceType="vin"
-  allowCrop={true}
-/>
-```

ocr/CLAUDE.md

@@ -0,0 +1,15 @@
+# ocr/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `Dockerfile` | Container build definition | Docker builds, deployment |
+| `requirements.txt` | Python dependencies | Adding dependencies |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `app/` | FastAPI application source | OCR endpoint development |
+| `tests/` | Test suite | Adding or modifying tests |

ocr/app/CLAUDE.md

@@ -0,0 +1,22 @@
+# ocr/app/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `main.py` | FastAPI application entry point | Route registration, app setup |
+| `config.py` | Configuration settings | Environment variables, settings |
+| `__init__.py` | Package init | Package structure |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `extractors/` | Data extraction logic | Adding new extraction types |
+| `models/` | Data models and schemas | Request/response types |
+| `patterns/` | Regex and parsing patterns | Pattern matching rules |
+| `preprocessors/` | Image preprocessing pipeline | Image preparation before OCR |
+| `routers/` | FastAPI route handlers | API endpoint changes |
+| `services/` | Business logic services | Core OCR processing |
+| `table_extraction/` | Table detection and parsing | Structured data extraction |
+| `validators/` | Input validation | Validation rules |