chore: update docs

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