diff --git a/.gitea/CLAUDE.md b/.gitea/CLAUDE.md new file mode 100644 index 0000000..746919a --- /dev/null +++ b/.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 | diff --git a/CLAUDE.md b/CLAUDE.md index b177d0c..4f4d0a6 100644 --- a/CLAUDE.md +++ b/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 diff --git a/ansible/CLAUDE.md b/ansible/CLAUDE.md new file mode 100644 index 0000000..463b3ed --- /dev/null +++ b/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 | diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md index a6fdab6..69b7929 100644 --- a/backend/CLAUDE.md +++ b/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 | diff --git a/backend/src/_system/CLAUDE.md b/backend/src/_system/CLAUDE.md new file mode 100644 index 0000000..7e3b646 --- /dev/null +++ b/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 | diff --git a/backend/src/features/CLAUDE.md b/backend/src/features/CLAUDE.md index 096db1d..da31caf 100644 --- a/backend/src/features/CLAUDE.md +++ b/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 | diff --git a/backend/src/features/admin/CLAUDE.md b/backend/src/features/admin/CLAUDE.md new file mode 100644 index 0000000..37997bb --- /dev/null +++ b/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 | diff --git a/backend/src/features/audit-log/CLAUDE.md b/backend/src/features/audit-log/CLAUDE.md index 5891d2c..d975b72 100644 --- a/backend/src/features/audit-log/CLAUDE.md +++ b/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). diff --git a/backend/src/features/auth/CLAUDE.md b/backend/src/features/auth/CLAUDE.md new file mode 100644 index 0000000..7b483ee --- /dev/null +++ b/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 | diff --git a/backend/src/features/backup/CLAUDE.md b/backend/src/features/backup/CLAUDE.md index b1d25ca..8c9c01b 100644 --- a/backend/src/features/backup/CLAUDE.md +++ b/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 | diff --git a/backend/src/features/documents/CLAUDE.md b/backend/src/features/documents/CLAUDE.md new file mode 100644 index 0000000..c1a8ef9 --- /dev/null +++ b/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 | diff --git a/backend/src/features/fuel-logs/CLAUDE.md b/backend/src/features/fuel-logs/CLAUDE.md new file mode 100644 index 0000000..52c744a --- /dev/null +++ b/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 | diff --git a/backend/src/features/maintenance/CLAUDE.md b/backend/src/features/maintenance/CLAUDE.md new file mode 100644 index 0000000..6f80879 --- /dev/null +++ b/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 | diff --git a/backend/src/features/notifications/CLAUDE.md b/backend/src/features/notifications/CLAUDE.md new file mode 100644 index 0000000..2351841 --- /dev/null +++ b/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 | diff --git a/backend/src/features/ocr/CLAUDE.md b/backend/src/features/ocr/CLAUDE.md new file mode 100644 index 0000000..9c0d6cd --- /dev/null +++ b/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 | diff --git a/backend/src/features/onboarding/CLAUDE.md b/backend/src/features/onboarding/CLAUDE.md new file mode 100644 index 0000000..8c8f2ca --- /dev/null +++ b/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 | diff --git a/backend/src/features/ownership-costs/CLAUDE.md b/backend/src/features/ownership-costs/CLAUDE.md new file mode 100644 index 0000000..a46c7ad --- /dev/null +++ b/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 | diff --git a/backend/src/features/platform/CLAUDE.md b/backend/src/features/platform/CLAUDE.md new file mode 100644 index 0000000..5de3ffb --- /dev/null +++ b/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 | diff --git a/backend/src/features/stations/CLAUDE.md b/backend/src/features/stations/CLAUDE.md new file mode 100644 index 0000000..6f5020c --- /dev/null +++ b/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 | diff --git a/backend/src/features/subscriptions/CLAUDE.md b/backend/src/features/subscriptions/CLAUDE.md index b413fbd..a1b273a 100644 --- a/backend/src/features/subscriptions/CLAUDE.md +++ b/backend/src/features/subscriptions/CLAUDE.md @@ -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 | diff --git a/backend/src/features/terms-agreement/CLAUDE.md b/backend/src/features/terms-agreement/CLAUDE.md new file mode 100644 index 0000000..1e95bd1 --- /dev/null +++ b/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 | diff --git a/backend/src/features/user-export/CLAUDE.md b/backend/src/features/user-export/CLAUDE.md new file mode 100644 index 0000000..3ec4196 --- /dev/null +++ b/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 | diff --git a/backend/src/features/user-import/CLAUDE.md b/backend/src/features/user-import/CLAUDE.md index 200bc29..13ebe9a 100644 --- a/backend/src/features/user-import/CLAUDE.md +++ b/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 | -| `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 | diff --git a/backend/src/features/user-preferences/CLAUDE.md b/backend/src/features/user-preferences/CLAUDE.md new file mode 100644 index 0000000..3393ef3 --- /dev/null +++ b/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 | diff --git a/backend/src/features/user-profile/CLAUDE.md b/backend/src/features/user-profile/CLAUDE.md new file mode 100644 index 0000000..ea79830 --- /dev/null +++ b/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 | diff --git a/backend/src/features/vehicles/CLAUDE.md b/backend/src/features/vehicles/CLAUDE.md new file mode 100644 index 0000000..da8c492 --- /dev/null +++ b/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 | diff --git a/backend/src/features/vehicles/external/CLAUDE.md b/backend/src/features/vehicles/external/CLAUDE.md index 92b34ca..fdcb3c7 100644 --- a/backend/src/features/vehicles/external/CLAUDE.md +++ b/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 diff --git a/backend/src/features/vehicles/external/README.md b/backend/src/features/vehicles/external/README.md new file mode 100644 index 0000000..0198ff9 --- /dev/null +++ b/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 diff --git a/config/CLAUDE.md b/config/CLAUDE.md index dd73d62..ca8e127 100644 --- a/config/CLAUDE.md +++ b/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 | -| `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 | diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index a0e2637..e17808d 100644 --- a/docs/CLAUDE.md +++ b/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 | diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 443ae05..d1e0da0 100644 --- a/frontend/CLAUDE.md +++ b/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 diff --git a/frontend/src/CLAUDE.md b/frontend/src/CLAUDE.md index 6878041..2a34176 100644 --- a/frontend/src/CLAUDE.md +++ b/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 | diff --git a/frontend/src/features/CLAUDE.md b/frontend/src/features/CLAUDE.md index 8325d4a..d0b3c7e 100644 --- a/frontend/src/features/CLAUDE.md +++ b/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 | diff --git a/frontend/src/features/subscription/CLAUDE.md b/frontend/src/features/subscription/CLAUDE.md index d33772f..5ce6840 100644 --- a/frontend/src/features/subscription/CLAUDE.md +++ b/frontend/src/features/subscription/CLAUDE.md @@ -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 diff --git a/frontend/src/shared/CLAUDE.md b/frontend/src/shared/CLAUDE.md index 200ff50..c7389f4 100644 --- a/frontend/src/shared/CLAUDE.md +++ b/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 - -### 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'; - - handleCapture(file, croppedFile)} - onCancel={() => setShowCamera(false)} - guidanceType="vin" - allowCrop={true} -/> -``` +| `components/` | Shared components (CameraCapture) | Cross-feature reusable components | diff --git a/ocr/CLAUDE.md b/ocr/CLAUDE.md new file mode 100644 index 0000000..2020969 --- /dev/null +++ b/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 | diff --git a/ocr/app/CLAUDE.md b/ocr/app/CLAUDE.md new file mode 100644 index 0000000..26c799a --- /dev/null +++ b/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 |