chore: update docs
This commit is contained in:
Eric Gullickson
10
backend/src/_system/CLAUDE.md
Normal file
10
backend/src/_system/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -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 |
|
||||
|
||||
18
backend/src/features/admin/CLAUDE.md
Normal file
18
backend/src/features/admin/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -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).
|
||||
|
||||
16
backend/src/features/auth/CLAUDE.md
Normal file
16
backend/src/features/auth/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -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 |
|
||||
|
||||
18
backend/src/features/documents/CLAUDE.md
Normal file
18
backend/src/features/documents/CLAUDE.md
Normal file
@@ -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 |
|
||||
21
backend/src/features/fuel-logs/CLAUDE.md
Normal file
21
backend/src/features/fuel-logs/CLAUDE.md
Normal file
@@ -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 |
|
||||
21
backend/src/features/maintenance/CLAUDE.md
Normal file
21
backend/src/features/maintenance/CLAUDE.md
Normal file
@@ -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 |
|
||||
19
backend/src/features/notifications/CLAUDE.md
Normal file
19
backend/src/features/notifications/CLAUDE.md
Normal file
@@ -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 |
|
||||
16
backend/src/features/ocr/CLAUDE.md
Normal file
16
backend/src/features/ocr/CLAUDE.md
Normal file
@@ -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 |
|
||||
17
backend/src/features/onboarding/CLAUDE.md
Normal file
17
backend/src/features/onboarding/CLAUDE.md
Normal file
@@ -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 |
|
||||
17
backend/src/features/ownership-costs/CLAUDE.md
Normal file
17
backend/src/features/ownership-costs/CLAUDE.md
Normal file
@@ -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 |
|
||||
20
backend/src/features/platform/CLAUDE.md
Normal file
20
backend/src/features/platform/CLAUDE.md
Normal file
@@ -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 |
|
||||
23
backend/src/features/stations/CLAUDE.md
Normal file
23
backend/src/features/stations/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -1,12 +1,10 @@
|
||||
# backend/src/features/subscriptions/
|
||||
|
||||
Stripe payment integration for subscription tiers and donations.
|
||||
# subscriptions/
|
||||
|
||||
## 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 |
|
||||
|
||||
## 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
|
||||
| `tests/` | Unit and integration tests | Adding or modifying tests |
|
||||
|
||||
17
backend/src/features/terms-agreement/CLAUDE.md
Normal file
17
backend/src/features/terms-agreement/CLAUDE.md
Normal file
@@ -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 |
|
||||
16
backend/src/features/user-export/CLAUDE.md
Normal file
16
backend/src/features/user-export/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -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 |
|
||||
| `api/` | HTTP handlers, route definitions, validation schemas | API endpoint development, request handling |
|
||||
| `tests/` | Integration tests with performance benchmarks | Testing, understanding 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 |
|
||||
| `domain/` | Import orchestration, archive extraction, types | Implementing import logic, data flow |
|
||||
| `api/` | HTTP handlers, route definitions, validation | API endpoint development |
|
||||
| `tests/` | Integration tests with performance benchmarks | Testing, test scenarios |
|
||||
|
||||
14
backend/src/features/user-preferences/CLAUDE.md
Normal file
14
backend/src/features/user-preferences/CLAUDE.md
Normal file
@@ -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 |
|
||||
18
backend/src/features/user-profile/CLAUDE.md
Normal file
18
backend/src/features/user-profile/CLAUDE.md
Normal file
@@ -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 |
|
||||
21
backend/src/features/vehicles/CLAUDE.md
Normal file
21
backend/src/features/vehicles/CLAUDE.md
Normal file
@@ -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 |
|
||||
40
backend/src/features/vehicles/external/CLAUDE.md
vendored
40
backend/src/features/vehicles/external/CLAUDE.md
vendored
@@ -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
|
||||
|
||||
25
backend/src/features/vehicles/external/README.md
vendored
Normal file
25
backend/src/features/vehicles/external/README.md
vendored
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user