chore: update docs
This commit is contained in:
Eric Gullickson
14
.gitea/CLAUDE.md
Normal file
14
.gitea/CLAUDE.md
Normal file
@@ -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 |
|
||||
11
CLAUDE.md
11
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 |
|
||||
| `scripts/` | Utility scripts (backup, deploy) | Automation tasks |
|
||||
| `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
|
||||
| `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
|
||||
|
||||
|
||||
11
ansible/CLAUDE.md
Normal file
11
ansible/CLAUDE.md
Normal file
@@ -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 |
|
||||
@@ -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 |
|
||||
|
||||
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
|
||||
@@ -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 |
|
||||
| `deployment/` | Deployment configuration | Deploy scripts, environment configs |
|
||||
| `monitoring/` | Monitoring and alerts | Prometheus, alerting rules |
|
||||
| `shared/` | Shared configuration | Cross-service settings |
|
||||
| `app/` | Application environment configuration | App-specific settings |
|
||||
| `alloy/` | Grafana Alloy log collector config | Log collection pipeline |
|
||||
| `deployment/` | Deployment environment configs | Deploy scripts, environment configs |
|
||||
| `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 |
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -1,12 +1,11 @@
|
||||
# frontend/src/features/subscription/
|
||||
|
||||
Subscription and billing management feature with Stripe integration.
|
||||
# subscription/
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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
|
||||
|
||||
### 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}
|
||||
/>
|
||||
```
|
||||
| `components/` | Shared components (CameraCapture) | Cross-feature reusable components |
|
||||
|
||||
15
ocr/CLAUDE.md
Normal file
15
ocr/CLAUDE.md
Normal file
@@ -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 |
|
||||
22
ocr/app/CLAUDE.md
Normal file
22
ocr/app/CLAUDE.md
Normal file
@@ -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 |
|
||||
Reference in New Issue
Block a user