a35d05f08a
Implements Milestone 3: Backend import service and API with: Service Layer (user-import.service.ts): - generatePreview(): extract archive, validate, detect VIN conflicts - executeMerge(): chunk-based import (100 records/batch), UPDATE existing by VIN, INSERT new via batchInsert - executeReplace(): transactional DELETE all user data, batchInsert all records - Conflict detection: VIN duplicates in vehicles - Error handling: collect errors per record, continue, report in summary - File handling: copy vehicle images and documents from archive to storage - Cleanup: delete temp directory in finally block API Layer: - POST /api/user/import: multipart upload, mode selection (merge/replace) - POST /api/user/import/preview: preview without executing import - Authentication: fastify.authenticate preHandler - Content-Type validation: application/gzip or application/x-gzip - Magic byte validation: FileType.fromBuffer verifies tar.gz - Request validation: Zod schema for mode selection - Response: ImportResult with success, mode, summary, warnings Files Created: - backend/src/features/user-import/domain/user-import.service.ts - backend/src/features/user-import/api/user-import.controller.ts - backend/src/features/user-import/api/user-import.routes.ts - backend/src/features/user-import/api/user-import.validation.ts Files Updated: - backend/src/app.ts: register userImportRoutes with /api prefix Quality: - Type-check: PASS (0 errors) - Linting: PASS (0 errors, 470 warnings - all pre-existing) - Repository pattern: snake_case→camelCase conversion - User-scoped: all queries filter by user_id - Transaction boundaries: Replace mode atomic, Merge mode per-batch Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
MotoVaultPro Backend
Modified Feature Capsule Architecture
Each feature is 100% self-contained in src/features/[name]/:
- api/ - HTTP endpoints and routing
- domain/ - Business logic and types
- data/ - Database operations
- migrations/ - Feature-specific schema
- external/ - External API integrations
- tests/ - All feature tests
- docs/ - Feature documentation
Quick Start (Containerized)
# From project root directory
# Ensure a valid .env exists at project root (production values provided by your team)
# Build and start all services (including backend)
make setup
# View logs
make logs-backend
# Run migrations
make migrate
Available Commands (Containerized)
From project root:
make start- Build and start all services (production)make migrate- Run database migrationsmake logs-backend- View backend logsmake shell-backend- Open shell in backend container
Inside container (via make shell-backend):
npm run build- Build for productionnpm start- Run production buildnpm test- Run all testsnpm test -- features/vehicles- Test specific featurenpm test -- features/vehicles/tests/unit- Test specific test typenpm run test:watch- Run tests in watch modenpm run schema:generate- Generate combined schema
Core Modules
Configuration (src/core/config/)
config-loader.ts- Environment variable loading and validationdatabase.ts- PostgreSQL connection poolredis.ts- Redis client and cache serviceuser-context.ts- User context extraction utilities
Security (Fastify Plugins)
src/core/plugins/auth.plugin.ts- Auth0 JWT via JWKS (@fastify/jwt + get-jwks)src/core/plugins/error.plugin.ts- Error handlingsrc/core/plugins/logging.plugin.ts- Request logging
Logging (src/core/logging/)
logger.ts- Structured logging with Winston
Middleware
src/core/middleware/user-context.ts- User ID extraction from JWT
Storage
src/core/storage/- Storage abstractionssrc/core/storage/adapters/minio.adapter.ts- MinIO S3-compatible adapter
Feature Development
To create a new feature capsule:
../scripts/generate-feature-capsule.sh feature-name
This creates the complete capsule structure with all necessary files.
Testing
Tests mirror the source structure:
features/vehicles/
├── domain/
│ └── vehicles.service.ts
└── tests/
└── unit/
└── vehicles.service.test.ts
Run tests (inside container via make shell-backend):
# All tests
npm test
# Specific feature
npm test -- features/vehicles
# Unit tests for specific feature
npm test -- features/vehicles/tests/unit
# Integration tests for specific feature
npm test -- features/vehicles/tests/integration
# Watch mode
npm run test:watch
# With coverage
npm test -- features/vehicles --coverage
Environment Variables
Ensure .env includes these key variables:
- Database connection (DB_*)
- Redis connection (REDIS_*)
- Auth0 configuration (AUTH0_*) — backend validates JWTs via Auth0 JWKS (@fastify/jwt + get-jwks)
- External API keys