k8s prepwork

.gitignore

@@ -17,3 +17,13 @@ obj/
 /data/
 MotoVaultPro.csproj.user
 Properties/launchSettings.json
+
+# K8s-aligned configuration and secret mounts (real files ignored; examples committed)
+config/**
+!config/
+!config/**/
+!config/**/*.example
+secrets/**
+!secrets/
+!secrets/**/
+!secrets/**/*.example

AGENTS.md

@@ -1,159 +0,0 @@
-# Development Partnership Guidelines
-
-## Core Development Principles
-
-### AI Context Efficiency
-**CRITICAL**: All development practices and choices should be made taking into account the most context efficient interaction with another AI. Any AI should be able to understand this application with minimal prompting.
-
-### Codebase Integrity Rules
-- Never create new files that don't already exist
-- Never make up things that aren't part of the actual project
-- Never skip or ignore existing system architecture
-- Only work with the files and structure that already exist
-- Be precise and respectful of the current codebase
-- **Delete** old code when replacing it
-- **Meaningful names**: `userID` not `id`
-
-## Docker-First Implementation Strategy
-
-### 1. Package.json Updates Only
-File: `frontend/package.json`
-- Add `"{package}": "{version}"` to dependencies
-- No npm install needed - handled by container rebuild
-- Testing: `make rebuild` then verify container starts
-
-### 2. Container-Validated Development Workflow (Production-only)
-```bash
-# After each change:
-make rebuild        # Rebuilds containers with new dependencies
-make logs           # Monitor for build/runtime errors
-```
-
-### 3. Docker-Tested Component Development (Production-only)
-- All testing in containers: `make shell-frontend` for debugging
-- No dev servers; production builds served by nginx
-- Changes require rebuild to reflect in production containers
-
-## Quality Standards
-
-### Automated Checks Are Mandatory
-**ALL hook issues are BLOCKING - EVERYTHING must be ✅ GREEN!**
-- No errors. No formatting issues. No linting problems. Zero tolerance
-- These are not suggestions. Fix ALL issues before continuing
-
-### Code Completion Criteria
-Our code is complete when:
-- ✅ All linters pass with zero issues
-- ✅ All tests pass  
-- ✅ Feature works end-to-end
-- ✅ Old code is deleted
-
-## AI Collaboration Strategy
-
-### Use Multiple Agents
-Leverage subagents aggressively for better results:
-- Spawn agents to explore different parts of the codebase in parallel
-- Use one agent to write tests while another implements features
-- Delegate research tasks: "I'll have an agent investigate the database schema while I analyze the API structure"
-- For complex refactors: One agent identifies changes, another implements them
-
-### Reality Checkpoints
-**Stop and validate** at these moments:
-- After implementing a complete feature
-- Before starting a new major component  
-- When something feels wrong
-- Before declaring "done"
-
-## Performance & Security Standards
-
-### Measure First
-- No premature optimization
-- Benchmark before claiming something is faster
-
-### Security Always
-- Validate all inputs
-- Use crypto/rand for randomness
-- Prepared statements for SQL (never concatenate!)
-
-## AI Loading Context Strategies
-
-### For AI Assistants: Instant Codebase Understanding
-To efficiently understand and maintain this codebase, follow this exact sequence:
-
-#### 1. Load Core Context (Required - 2 minutes)
-```
-Read these files in order:
-1. AI_PROJECT_GUIDE.md - Complete project overview and architecture
-2. .ai/context.json - Loading strategies and feature metadata
-3. docs/README.md - Documentation navigation hub
-```
-
-#### 2. For Specific Tasks
-
-**Working on Application Features**
-- Load entire feature directory: `backend/src/features/[feature-name]/`
-- Start with README.md for complete API and business rules
-- Everything needed is in this single directory
-- Remember: Features are modules within a single application service, not independent microservices
-
-**Working on Platform Services**
-- Load `docs/PLATFORM-SERVICES.md` for complete service architecture
-- Hierarchical vehicle API patterns
-- Service-to-service communication
-- Platform service deployment and operations
-
-**Cross-Service Work**
-- Load platform service docs + consuming feature documentation
-
-**Database Work**
-- Application DB: Load `docs/DATABASE-SCHEMA.md` for app schema
-- Platform Services: Load `docs/PLATFORM-SERVICES.md` for service schemas
-
-**Testing Work**
-- Load `docs/TESTING.md` for Docker-based testing workflow
-- Only use docker containers for testing. Never install local tools if they do not exist already
-- Frontend now uses Jest (like backend). `make test` runs backend + frontend tests
-- Jest config file: `frontend/jest.config.ts` (TypeScript configuration)
-- Only vehicles feature has implemented tests; other features have scaffolded test directories
-
-## Architecture Context for AI
-
-### Hybrid Platform Architecture
-**MotoVaultPro uses a hybrid architecture:** MVP Platform Services are true microservices, while the application is a modular monolith containing feature capsules. Application features in `backend/src/features/[name]/` are self-contained modules within a single service that consumes platform services via HTTP APIs.
-
-### Key Principles for AI Understanding
-- **Production-Only**: All services use production builds and configuration
-- **Docker-First**: All development in containers, no local installs
-- **Platform Service Independence**: Platform services are independent microservices
-- **Feature Capsule Organization**: Application features are self-contained modules within a monolith
-- **Hybrid Deployment**: Platform services deploy independently, application features deploy together
-- **Service Boundaries**: Clear separation between platform microservices and application monolith
-- **User-Scoped Data**: All application data isolated by user_id
-
-### Common AI Tasks
-```bash
-# Run all migrations (inside containers)
-make migrate
-
-# Run all tests (backend + frontend) inside containers
-make test
-
-# Run specific application feature tests (backend)
-make shell-backend
-npm test -- features/vehicles
-
-# Run frontend tests only (inside disposable node container)
-make test-frontend
-
-# View logs (all services)
-make logs
-
-# Container shell access
-make shell-backend           # Application service
-```
-
-## Never Use Emojis
-Maintain professional documentation standards without emoji usage.
-
-## Mobile + Desktop Requirement
-**ALL features MUST be implemented and tested on BOTH mobile and desktop.** This is a hard requirement that cannot be skipped. Every component, page, and feature needs responsive design and mobile-first considerations.

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -6,10 +6,9 @@
 **CRITICAL**: All development practices and choices should be made taking into account the most context efficient interaction with another AI. Any AI should be able to understand this application with minimal prompting.
 
 ### Codebase Integrity Rules
-- Never create new files that don't already exist
+- Justify every new file and folder as being needed for the final production application.
 - Never make up things that aren't part of the actual project
 - Never skip or ignore existing system architecture
-- Only work with the files and structure that already exist
 - Be precise and respectful of the current codebase
 - **Delete** old code when replacing it
 - **Meaningful names**: `userID` not `id`
@@ -83,9 +82,8 @@ To efficiently understand and maintain this codebase, follow this exact sequence
 #### 1. Load Core Context (Required - 2 minutes)
 ```
 Read these files in order:
-1. AI_PROJECT_GUIDE.md - Complete project overview and architecture
+1. .ai/context.json - Loading strategies and feature metadata
-2. .ai/context.json - Loading strategies and feature metadata
+2. docs/README.md - Documentation navigation hub
-3. docs/README.md - Documentation navigation hub
 ```
 
 #### 2. For Specific Tasks

K8S-REDESIGN.md

@@ -2,20 +2,20 @@
 
 ## Overview
 
-This document outlines the comprehensive redesign of MotoVaultPro's Docker Compose architecture to closely replicate a Kubernetes deployment pattern. The goal is to maintain all current functionality while preparing for seamless K8s migration and improving development experience.
+This document outlines the aggressive redesign of MotoVaultPro's Docker Compose architecture to closely replicate a Kubernetes deployment pattern. **Breaking changes are acceptable** as this is a pre-production application. The goal is to completely replace the current architecture with a production-ready K8s-equivalent setup in 2-3 days, eliminating all development shortcuts and implementing true production constraints.
+
+**SCOPE**: ETL services have been completely removed from the architecture. This migration covers the 11 remaining core services with a focus on security, observability, and K8s compatibility over backward compatibility.
 
 ## Current Architecture Analysis
 
-### Existing Services (13 containers)
+### Core Services for Migration (11 containers)
 
 **MVP Platform Services (Microservices)**
 - `mvp-platform-landing` - Marketing/landing page (nginx)
 - `mvp-platform-tenants` - Multi-tenant management API (FastAPI)
 - `mvp-platform-vehicles-api` - Vehicle data API (FastAPI)
-- `mvp-platform-vehicles-etl` - Data processing pipeline (Python)
 - `mvp-platform-vehicles-db` - Vehicle data storage (PostgreSQL)
 - `mvp-platform-vehicles-redis` - Vehicle data cache (Redis)
-- `mvp-platform-vehicles-mssql` - Monthly ETL source (SQL Server)
 
 **Application Services (Modular Monolith)**
 - `admin-backend` - Application API with feature capsules (Node.js)
@@ -25,66 +25,97 @@ This document outlines the comprehensive redesign of MotoVaultPro's Docker Compo
 - `admin-minio` - Object storage (MinIO)
 
 **Infrastructure**
-- `nginx-proxy` - Load balancer and SSL termination
 - `platform-postgres` - Platform services database
 - `platform-redis` - Platform services cache
+- `nginx-proxy` - **TO BE COMPLETELY REMOVED** (replaced by Traefik)
 
-### Current Limitations
+### Current Limitations (TO BE BROKEN)
 
-1. **Single Network**: All services on default network
+1. **Single Network**: All services on default network - **BREAKING: Move to isolated networks**
-2. **Manual Routing**: nginx configuration requires manual updates
+2. **Manual Routing**: nginx configuration requires manual updates - **BREAKING: Complete removal**
-3. **Port Exposure**: Many services expose ports directly
+3. **Excessive Port Exposure**: 10+ services expose ports directly - **BREAKING: Remove all except Traefik**
-4. **Configuration**: Environment variables scattered across services
+4. **Environment Variable Configuration**: 35+ env vars scattered across services - **BREAKING: Mandatory file-based config**
-5. **Service Discovery**: Hard-coded service names
+5. **Development Shortcuts**: Debug modes, open CORS, no authentication - **BREAKING: Production-only mode**
-6. **Observability**: Limited monitoring and debugging capabilities
+6. **No Resource Limits**: Services can consume unlimited resources - **BREAKING: Enforce limits on all services**
 
 ## Target Kubernetes-like Architecture
 
-### Network Segmentation
+### Network Segmentation (Aggressive Isolation)
 
 ```yaml
 networks:
   frontend:
     driver: bridge
+    internal: false  # Only for Traefik public access
     labels:
       - "com.motovaultpro.network=frontend"
-      - "com.motovaultpro.purpose=public-facing"
+      - "com.motovaultpro.purpose=public-traffic-only"
 
   backend:
     driver: bridge
-    internal: true
+    internal: true   # Complete isolation from host
     labels:
       - "com.motovaultpro.network=backend"
       - "com.motovaultpro.purpose=api-services"
 
   database:
     driver: bridge
-    internal: true
+    internal: true   # Application data isolation
     labels:
       - "com.motovaultpro.network=database"
-      - "com.motovaultpro.purpose=data-layer"
+      - "com.motovaultpro.purpose=app-data-layer"
 
   platform:
     driver: bridge
-    internal: true
+    internal: true   # Platform microservices isolation
     labels:
       - "com.motovaultpro.network=platform"
-      - "com.motovaultpro.purpose=microservices"
+      - "com.motovaultpro.purpose=platform-services"
 ```
 
-### Service Placement Strategy
+**BREAKING CHANGE**: No `egress` network. Services requiring external API access (Auth0, Google Maps, VPIC) will connect through the `backend` network with Traefik handling external routing. This forces all external communication through the ingress controller, matching Kubernetes egress gateway patterns.
 
-| Network | Services | Purpose | K8s Equivalent |
+### Service Placement Strategy (Aggressive Isolation)
+
+| Service | Networks | Purpose | K8s Equivalent |
 |---------|----------|---------|----------------|
-| `frontend` | traefik, admin-frontend, mvp-platform-landing | Public-facing services | Public LoadBalancer services |
+| `traefik` | `frontend`, `backend` | **ONLY** public routing + API access | LoadBalancer + IngressController |
-| `backend` | admin-backend, mvp-platform-tenants, mvp-platform-vehicles-api | API services | ClusterIP services |
+| `admin-frontend`, `mvp-platform-landing` | `frontend` | Public web applications | Ingress frontends |
-| `database` | All PostgreSQL, Redis, MinIO | Data persistence | StatefulSets with PVCs |
+| `admin-backend` | `backend`, `database`, `platform` | Application API with cross-service access | ClusterIP with multiple network attachment |
-| `platform` | Platform microservices communication | Internal service mesh | Service mesh networking |
+| `mvp-platform-tenants`, `mvp-platform-vehicles-api` | `backend`, `platform` | Platform APIs + data access | ClusterIP (platform namespace) |
+| `admin-postgres`, `admin-redis`, `admin-minio` | `database` | Application data isolation | StatefulSets with PVCs |
+| `platform-postgres`, `platform-redis`, `mvp-platform-vehicles-db`, `mvp-platform-vehicles-redis` | `platform` | Platform data isolation | StatefulSets with PVCs |
+
+**BREAKING CHANGES**:
+- **No external network access** for individual services
+- **No host port exposure** except Traefik (80, 443, 8080)
+- **Mandatory network isolation** - services cannot access unintended networks
+- **No development bypasses** - all traffic through Traefik
+
+**Service Communication Matrix (Restricted)**
+```
+# Internal service communication (via backend network)
+admin-backend → mvp-platform-vehicles-api:8000 (authenticated API calls)
+admin-backend → mvp-platform-tenants:8000 (authenticated API calls)
+
+# Data layer access (isolated networks)
+admin-backend → admin-postgres:5432, admin-redis:6379, admin-minio:9000
+mvp-platform-vehicles-api → mvp-platform-vehicles-db:5432, mvp-platform-vehicles-redis:6379
+mvp-platform-tenants → platform-postgres:5432, platform-redis:6379
+
+# External integrations (BREAKING: via Traefik proxy only)
+admin-backend → External APIs (Auth0, Google Maps, VPIC) via Traefik middleware
+Platform services → External APIs via Traefik middleware (no direct access)
+```
+
+**BREAKING CHANGE**: All external API calls must be proxied through Traefik middleware. No direct external network access for any service.
 
 ## Traefik Configuration
 
 ### Core Traefik Setup
 
+- New directories `config/traefik/` and `secrets/traefik/` will store production-bound configuration and certificates. These folders are justified as they mirror their eventual Kubernetes ConfigMap/Secret counterparts and replace the legacy nginx configuration.
+
 ```yaml
 traefik:
   image: traefik:v3.0
@@ -98,15 +129,15 @@ traefik:
     - "8080:8080"  # Dashboard
   volumes:
     - /var/run/docker.sock:/var/run/docker.sock:ro
-    - ./config/traefik:/config:ro
+    - ./config/traefik/traefik.yml:/etc/traefik/traefik.yml:ro
-    - ./certs:/certs:ro
+    - ./config/traefik/middleware.yml:/etc/traefik/middleware.yml:ro
-  configs:
+    - ./secrets/traefik/certs:/certs:ro
-    - source: traefik-config
-      target: /etc/traefik/traefik.yml
   labels:
     - "traefik.enable=true"
     - "traefik.http.routers.dashboard.rule=Host(`traefik.motovaultpro.local`)"
     - "traefik.http.routers.dashboard.tls=true"
+    - "traefik.http.routers.dashboard.middlewares=dashboard-allowlist@docker"
+    - "traefik.http.middlewares.dashboard-allowlist.ipwhitelist.sourcerange=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
 ```
 
 ### Service Discovery Labels
@@ -197,6 +228,12 @@ http:
         authResponseHeaders:
           - "X-Auth-User"
           - "X-Auth-Roles"
+    dashboard-allowlist:
+      ipWhiteList:
+        sourceRange:
+          - "10.0.0.0/8"
+          - "172.16.0.0/12"
+          - "192.168.0.0/16"
 ```
 
 ## Enhanced Health Checks
@@ -241,60 +278,101 @@ All services must expose:
 
 ## Configuration Management
 
-### Docker Configs (K8s ConfigMaps equivalent)
+### Configuration & Secret Management (Compose-compatible)
 
-```yaml
+- Application and platform settings will live in versioned files under `config/app/` and `config/platform/`, mounted read-only into the containers (`volumes:`). This mirrors ConfigMaps without relying on Docker Swarm-only `configs`.
-configs:
+- Secrets (Auth0, database, API keys) will be stored as individual files beneath `secrets/app/` and `secrets/platform/`, mounted as read-only volumes. At runtime the containers will read from `/run/secrets/*`, matching the eventual Kubernetes Secret mount pattern.
-  traefik-config:
+- Committed templates: `.example` files now reside in `config/app/production.yml.example`, `config/platform/production.yml.example`, and `secrets/**/.example` to document required keys while keeping live credentials out of Git. The real files stay untracked via `.gitignore`.
-    file: ./config/traefik/traefik.yml
+- Runtime loader: extend `backend/src/core/config/environment.ts` (and equivalent FastAPI settings) to hydrate configuration by reading `CONFIG_PATH` YAML and `SECRETS_DIR` file values before falling back to `process.env`. This ensures parity between Docker Compose mounts and future Kubernetes ConfigMap/Secret projections.
-  traefik-middleware:
+
-    file: ./config/traefik/middleware.yml
+#### Configuration Migration Strategy
-  app-config-production:
+
-    file: ./config/app/production.yml
+**Current Environment Variables (45 total) to File Mapping:**
-  platform-config:
+
-    file: ./config/platform/services.yml
+**Application Secrets** (`secrets/app/`):
+```
+auth0-client-secret.txt        # AUTH0_CLIENT_SECRET
+postgres-password.txt          # DB_PASSWORD
+minio-access-key.txt          # MINIO_ACCESS_KEY
+minio-secret-key.txt          # MINIO_SECRET_KEY
+platform-vehicles-api-key.txt # PLATFORM_VEHICLES_API_KEY
+google-maps-api-key.txt       # GOOGLE_MAPS_API_KEY
 ```
 
-### Docker Secrets (K8s Secrets equivalent)
+**Platform Secrets** (`secrets/platform/`):
-
+```
-```yaml
+platform-db-password.txt      # PLATFORM_DB_PASSWORD
-secrets:
+vehicles-db-password.txt      # POSTGRES_PASSWORD (vehicles)
-  auth0-client-secret:
-    file: ./secrets/auth0-client-secret.txt
-  database-passwords:
-    file: ./secrets/database-passwords.txt
-  platform-api-keys:
-    file: ./secrets/platform-api-keys.txt
-  ssl-certificates:
-    file: ./secrets/ssl-certs.txt
 ```
 
-### Environment Configuration
+**Network attachments for outbound-enabled services:**
-
 ```yaml
-# config/app/production.yml
+mvp-platform-vehicles-api:
+  networks:
+    - backend
+    - platform
+    - egress
+
+mvp-platform-tenants:
+  networks:
+    - backend
+    - platform
+    - egress
+```
+
+**Application Configuration** (`config/app/production.yml`):
+```yaml
+server:
+  port: 3001
+  tenant_id: admin
+
 database:
   host: admin-postgres
   port: 5432
   name: motovaultpro
-  pool_size: 20
+  user: postgres
 
 redis:
   host: admin-redis
   port: 6379
-  db: 0
+
+minio:
+  endpoint: admin-minio
+  port: 9000
+  bucket: motovaultpro
 
 auth0:
-  domain: ${AUTH0_DOMAIN}
+  domain: motovaultpro.us.auth0.com
-  audience: ${AUTH0_AUDIENCE}
+  audience: https://api.motovaultpro.com
 
 platform:
-  vehicles_api:
+  vehicles_api_url: http://mvp-platform-vehicles-api:8000
-    url: http://mvp-platform-vehicles-api:8000
+  tenants_api_url: http://mvp-platform-tenants:8000
-    timeout: 30s
+
-  tenants_api:
+external:
-    url: http://mvp-platform-tenants:8000
+  vpic_api_url: https://vpic.nhtsa.dot.gov/api/vehicles
-    timeout: 15s
+```
+
+**Compose Example:**
+```yaml
+  admin-backend:
+    volumes:
+      - ./config/app/production.yml:/app/config/production.yml:ro
+      - ./secrets/app/auth0-client-secret.txt:/run/secrets/auth0-client-secret:ro
+      - ./secrets/app/postgres-password.txt:/run/secrets/postgres-password:ro
+      - ./secrets/app/minio-access-key.txt:/run/secrets/minio-access-key:ro
+      - ./secrets/app/minio-secret-key.txt:/run/secrets/minio-secret-key:ro
+      - ./secrets/app/platform-vehicles-api-key.txt:/run/secrets/platform-vehicles-api-key:ro
+      - ./secrets/app/google-maps-api-key.txt:/run/secrets/google-maps-api-key:ro
+    environment:
+      - NODE_ENV=production
+      - CONFIG_PATH=/app/config/production.yml
+      - SECRETS_DIR=/run/secrets
+    networks:
+      - backend
+      - database
+      - platform
+      - egress
 ```
 
 ## Resource Management
@@ -303,34 +381,23 @@ platform:
 
 **Tier 1: Critical Services**
 ```yaml
-deploy:
+  admin-backend:
-  resources:
+    mem_limit: 2g
-    limits: { memory: 2G, cpus: '2.0' }
+    cpus: 2.0
-    reservations: { memory: 1G, cpus: '1.0' }
-  restart_policy:
-    condition: on-failure
-    max_attempts: 3
 ```
 
 **Tier 2: Supporting Services**
 ```yaml
-deploy:
+  admin-frontend:
-  resources:
+    mem_limit: 1g
-    limits: { memory: 1G, cpus: '1.0' }
+    cpus: 1.0
-    reservations: { memory: 512M, cpus: '0.5' }
-  restart_policy:
-    condition: on-failure
-    max_attempts: 3
 ```
 
 **Tier 3: Infrastructure Services**
 ```yaml
-deploy:
+  traefik:
-  resources:
+    mem_limit: 512m
-    limits: { memory: 512M, cpus: '0.5' }
+    cpus: 0.5
-    reservations: { memory: 256M, cpus: '0.25' }
-  restart_policy:
-    condition: unless-stopped
 ```
 
 ### Service Tiers
@@ -339,126 +406,299 @@ deploy:
 |------|----------|------------------|----------|
 | 1 | admin-backend, mvp-platform-vehicles-api, admin-postgres | High | Critical |
 | 2 | admin-frontend, mvp-platform-tenants, mvp-platform-landing | Medium | Important |
-| 3 | traefik, redis services, etl services | Low | Supporting |
+| 3 | traefik, redis services, storage services | Low | Supporting |
 
-## Migration Implementation Plan
+### Development Port Exposure Policy
 
-### Phase 1: Infrastructure Foundation (Week 1)
+**Exposed Ports for Development Debugging:**
+```yaml
+# Database Access (development debugging)
+- 5432:5432    # admin-postgres (application DB access)
+- 5433:5432    # mvp-platform-vehicles-db (platform DB access)
+- 5434:5432    # platform-postgres (platform services DB access)
 
-**Objectives:**
+# Cache Access (development debugging)
-- Implement Traefik service
+- 6379:6379    # admin-redis
-- Create network segmentation
+- 6380:6379    # mvp-platform-vehicles-redis
-- Establish basic routing
+- 6381:6379    # platform-redis
+
+# Storage Access (development/admin)
+- 9000:9000    # admin-minio API
+- 9001:9001    # admin-minio console
+
+# Traefik Dashboard (development monitoring)
+- 8080:8080    # traefik dashboard
+```
+
+**Internal-Only Services (no port exposure):**
+- All HTTP application services (routed through Traefik)
+- Platform APIs (accessible via application backend only)
+
+**Mobile Testing Considerations:**
+- Self-signed certificates require device-specific trust configuration
+- Development URLs must be accessible from mobile devices on same network
+- Certificate CN must match both `motovaultpro.com` and `admin.motovaultpro.com`
+
+## Migration Implementation Plan (Aggressive Approach)
+
+### **BREAKING CHANGE STRATEGY**: Complete Architecture Replacement (2-3 Days)
+
+**Objective**: Replace entire Docker Compose architecture with K8s-equivalent setup in a single migration event. No backward compatibility, no gradual transition, no service uptime requirements.
+
+### **Day 1: Complete Infrastructure Replacement**
+
+**Breaking Changes Implemented:**
+1. **Remove nginx-proxy completely** - no parallel operation
+2. **Implement Traefik with full production configuration**
+3. **Break all current networking** - implement 4-network isolation from scratch
+4. **Remove ALL development port exposure** (10+ ports → 3 ports)
+5. **Break environment variable patterns** - implement mandatory file-based configuration
 
 **Tasks:**
-1. Create new network topology
+```bash
-2. Add Traefik service with basic configuration
+# 1. Backup current state
-3. Migrate nginx routing to Traefik labels
+cp docker-compose.yml docker-compose.old.yml
-4. Test SSL certificate handling
+docker compose down
-5. Verify all existing functionality
 
-**Success Criteria:**
+# 2. Create configuration structure
-- All services accessible via original URLs
+mkdir -p config/app config/platform secrets/app secrets/platform
-- SSL certificates working
-- Health checks functional
-- No performance degradation
 
-### Phase 2: Service Discovery & Labels (Week 2)
+# 3. Generate production-ready certificates
+make generate-certs  # Multi-domain with mobile compatibility
 
-**Objectives:**
+# 4. Implement new docker-compose.yml with:
-- Convert all services to label-based discovery
+#    - 4 isolated networks
-- Implement middleware for security
+#    - Traefik service with full middleware
-- Add service health monitoring
+#    - No port exposure except Traefik (80, 443, 8080)
+#    - File-based configuration for all services
+#    - Resource limits on all services
+
+# 5. Update all service configurations to use file-based config
+#    - Remove all environment variables from compose
+#    - Implement CONFIG_PATH and SECRETS_DIR loaders
+```
+
+**Expected Failures**: Services will fail to start until configuration files are properly implemented.
+
+### **Day 2: Service Reconfiguration & Authentication**
+
+**Breaking Changes Implemented:**
+1. **Mandatory service-to-service authentication** - remove all debug/open access
+2. **Implement standardized health endpoints** - break existing health check patterns
+3. **Enforce resource limits** - services may fail if exceeding limits
+4. **Remove CORS development shortcuts** - production-only security
 
 **Tasks:**
-1. Convert each service to Traefik labels
+```bash
-2. Implement security middleware
+# 1. Implement /health, /health/ready, /health/live on all HTTP services
-3. Add CORS and authentication middleware
+# 2. Update Dockerfiles and service code for new health endpoints
-4. Test service discovery and failover
+# 3. Configure Traefik labels for all services
-5. Implement Traefik dashboard access
+# 4. Implement service authentication:
+#    - API keys for platform service access
+#    - Remove debug modes and localhost CORS
+#    - Implement production security headers
+# 5. Add resource limits to all services
+# 6. Test new architecture end-to-end
+```
 
-**Success Criteria:**
+**Expected Issues**: Authentication failures, CORS errors, resource limit violations.
-- All services discovered automatically
-- Security middleware working
-- Dashboard accessible and functional
-- Mobile and desktop testing passes
 
-### Phase 3: Configuration Management (Week 3)
+### **Day 3: Validation & Documentation Update**
-
-**Objectives:**
-- Implement Docker configs and secrets
-- Standardize environment configuration
-- Add monitoring and observability
 
 **Tasks:**
-1. Move configuration to Docker configs
+1. **Complete testing** of new architecture
-2. Implement secrets management
+2. **Update all documentation** to reflect new constraints
-3. Standardize health check endpoints
+3. **Update Makefile** with breaking changes to commands
-4. Add service metrics collection
+4. **Validate mobile access** with new certificate and routing
-5. Implement log aggregation
+5. **Performance validation** (baseline not required - new architecture is target)
 
-**Success Criteria:**
+### **BREAKING CHANGES SUMMARY**
-- No hardcoded secrets in compose files
-- Centralized configuration management
-- Enhanced monitoring capabilities
-- Improved debugging experience
 
-### Phase 4: Optimization & Documentation (Week 4)
+#### **Network Access**
+- **OLD**: All services on default network with host access
+- **NEW**: 4 isolated networks, no host access except Traefik
 
-**Objectives:**
+#### **Port Exposure**
-- Optimize resource allocation
+- **OLD**: 10+ ports exposed (databases, APIs, storage)
-- Update development workflow
+- **NEW**: Only 3 ports (80, 443, 8080) - everything through Traefik
-- Complete documentation
 
-**Tasks:**
+#### **Configuration**
-1. Implement resource limits and reservations
+- **OLD**: 35+ environment variables scattered across services
-2. Update Makefile with new commands
+- **NEW**: Mandatory file-based configuration with no env fallbacks
-3. Create troubleshooting documentation
-4. Performance testing and optimization
-5. Final validation of all features
 
-**Success Criteria:**
+#### **Development Access**
-- Optimized resource usage
+- **OLD**: Direct database/service access via exposed ports
-- Updated development workflow
+- **NEW**: Access only via `docker exec` or Traefik routing
-- Complete documentation
-- All tests passing
 
-## Development Workflow Enhancements
+#### **Security**
+- **OLD**: Debug modes, open CORS, no authentication
+- **NEW**: Production security only, mandatory authentication
 
-### New Makefile Commands
+#### **Resource Management**
+- **OLD**: Unlimited resource consumption
+- **NEW**: Enforced limits on all services
 
+### **Risk Mitigation**
+
+1. **Document current working state** before migration (Day 0)
+2. **Keep docker-compose.old.yml** for reference
+3. **Backup all volumes** before starting
+4. **Expect multiple restart cycles** during configuration
+5. **Plan for debugging time** - new constraints will reveal issues
+
+### **Success Criteria (Non-Negotiable)**
+- ✅ All 11 services operational through Traefik only
+- ✅ Zero host port exposure except Traefik
+- ✅ All configuration file-based
+- ✅ Service-to-service authentication working
+- ✅ Mobile and desktop HTTPS access functional
+- ✅ Resource limits enforced and services stable
+
+## Development Workflow Enhancements (BREAKING CHANGES)
+
+### Updated Makefile Commands (BREAKING CHANGES)
+
+**BREAKING CHANGE**: All database and service direct access removed. New K8s-equivalent workflow only.
+
+**Core Commands (Updated for New Architecture):**
 ```makefile
+SHELL := /bin/bash
+
 # Traefik specific commands
 traefik-dashboard:
-	@echo "Opening Traefik dashboard..."
+	@echo "Traefik dashboard: http://localhost:8080"
-	@open https://traefik.motovaultpro.local:8080
+	@echo "Add to /etc/hosts: 127.0.0.1 traefik.motovaultpro.local"
 
 traefik-logs:
 	@docker compose logs -f traefik
 
 service-discovery:
-	@echo "Discovered services:"
+	@echo "Discovered services and routes:"
-	@docker compose exec traefik traefik api --url=http://localhost:8080/api/rawdata
+	@docker compose exec traefik curl -sf http://localhost:8080/api/rawdata | jq '.http.services, .http.routers' 2>/dev/null || docker compose exec traefik curl -sf http://localhost:8080/api/rawdata
 
 network-inspect:
 	@echo "Network topology:"
 	@docker network ls --filter name=motovaultpro
-	@docker network inspect motovaultpro_frontend motovaultpro_backend motovaultpro_database motovaultpro_platform
+	@docker network inspect motovaultpro_frontend motovaultpro_backend motovaultpro_database motovaultpro_platform motovaultpro_egress 2>/dev/null | jq '.[].Name, .[].Containers' || echo "Networks not yet created"
 
 health-check-all:
 	@echo "Checking health of all services..."
 	@docker compose ps --format "table {{.Service}}\t{{.Status}}\t{{.Health}}"
 
-# Enhanced existing commands
+# Mobile testing support
+mobile-setup:
+	@echo "Mobile Testing Setup:"
+	@echo "1. Connect mobile device to same network as development machine"
+	@echo "2. Find development machine IP: $$(hostname -I | awk '{print $$1}')"
+	@echo "3. Add to mobile device hosts file (if rooted) or use IP directly:"
+	@echo "   $$(hostname -I | awk '{print $$1}') motovaultpro.com"
+	@echo "   $$(hostname -I | awk '{print $$1}') admin.motovaultpro.com"
+	@echo "4. Install certificate from: https://$$(hostname -I | awk '{print $$1}')/certs/motovaultpro.com.crt"
+	@echo "5. Trust certificate in device settings"
+
+# Development database access
+db-admin:
+	@echo "Database Access:"
+	@echo "Application DB: postgresql://postgres:localdev123@localhost:5432/motovaultpro"
+	@echo "Platform DB: postgresql://platform_user:platform123@localhost:5434/platform"
+	@echo "Vehicles DB: postgresql://mvp_platform_user:platform123@localhost:5433/vehicles"
+
+db-shell-app:
+	@docker compose exec admin-postgres psql -U postgres -d motovaultpro
+
+db-shell-platform:
+	@docker compose exec platform-postgres psql -U platform_user -d platform
+
+db-shell-vehicles:
+	@docker compose exec mvp-platform-vehicles-db psql -U mvp_platform_user -d vehicles
+
+# Enhanced existing commands (preserve ETL removal)
 logs:
-	@echo "Available log targets: all, traefik, backend, frontend, platform"
+	@echo "Available log targets: all, traefik, backend, frontend, platform, vehicles-api, tenants"
 	@docker compose logs -f $(filter-out $@,$(MAKECMDGOALS))
 
+# Remove ETL commands
+# etl-load-manual, etl-load-clear, etl-validate-json, etl-shell - REMOVED (out of scope)
+
 %:
 	@:  # This catches the log target argument
 ```
 
-### Enhanced Development Features
+**Updated Core Commands:**
+```makefile
+setup:
+	@echo "Setting up MotoVaultPro K8s-ready development environment..."
+	@echo "1. Checking configuration files..."
+	@if [ ! -d config ]; then echo "Creating config directory structure..."; mkdir -p config/app config/platform secrets/app secrets/platform; fi
+	@echo "2. Checking SSL certificates..."
+	@if [ ! -f certs/motovaultpro.com.crt ]; then echo "Generating multi-domain SSL certificate..."; $(MAKE) generate-certs; fi
+	@echo "3. Building and starting all containers..."
+	@docker compose up -d --build --remove-orphans
+	@echo "4. Running database migrations..."
+	@sleep 15  # Wait for databases to be ready
+	@docker compose exec admin-backend node dist/_system/migrations/run-all.js
+	@echo ""
+	@echo "✅ K8s-ready setup complete!"
+	@echo "Access application at: https://admin.motovaultpro.com"
+	@echo "Access platform landing at: https://motovaultpro.com"
+	@echo "Traefik dashboard: http://localhost:8080"
+	@echo "Mobile setup: make mobile-setup"
+
+generate-certs:
+	@echo "Generating multi-domain SSL certificate for mobile compatibility..."
+	@mkdir -p certs
+	@openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+		-keyout certs/motovaultpro.com.key \
+		-out certs/motovaultpro.com.crt \
+		-config <(echo '[dn]'; echo 'CN=motovaultpro.com'; echo '[req]'; echo 'distinguished_name = dn'; echo '[SAN]'; echo 'subjectAltName=DNS:motovaultpro.com,DNS:admin.motovaultpro.com,DNS:*.motovaultpro.com,IP:127.0.0.1') \
+		-extensions SAN
+	@echo "Certificate generated with SAN for mobile compatibility"
+
+# New K8s-equivalent access patterns
+db-access:
+	@echo "🚫 BREAKING CHANGE: No direct port access"
+	@echo "Database access via container exec only:"
+	@echo "  Application DB: make db-shell-app"
+	@echo "  Platform DB: make db-shell-platform"
+	@echo "  Vehicles DB: make db-shell-vehicles"
+
+# Service inspection (K8s equivalent)
+service-status:
+	@echo "Service health status:"
+	@docker compose ps --format "table {{.Service}}\\t{{.Status}}\\t{{.Health}}"
+
+traefik-dashboard:
+	@echo "Traefik Dashboard: http://localhost:8080"
+
+# Mobile testing (updated for new architecture)
+mobile-setup:
+	@echo "📱 Mobile Testing Setup (New Architecture):"
+	@echo "1. Connect mobile device to same network"
+	@echo "2. Development machine IP: $$(hostname -I | awk '{print $$1}')"
+	@echo "3. Add DNS: $$(hostname -I | awk '{print $$1}') motovaultpro.com admin.motovaultpro.com"
+	@echo "4. Trust certificate and access: https://admin.motovaultpro.com"
+
+# REMOVED COMMANDS (Breaking changes):
+# ❌ All direct port access commands
+# ❌ ETL commands (out of scope)
+# ❌ Development shortcuts
+```
+
+### **BREAKING CHANGES TO DEVELOPMENT WORKFLOW**
+
+#### **Database Access**
+- **OLD**: `psql -h localhost -p 5432` (direct connection)
+- **NEW**: `make db-shell-app` (container exec only)
+
+#### **Service Debugging**
+- **OLD**: `curl http://localhost:8000/health` (direct port)
+- **NEW**: `curl https://admin.motovaultpro.com/api/platform/vehicles/health` (via Traefik)
+
+#### **Storage Access**
+- **OLD**: MinIO console at `http://localhost:9001`
+- **NEW**: Access via Traefik routing only
+
+### Enhanced Development Features (Updated)
 
 **Service Discovery Dashboard**
 - Real-time service status
@@ -473,10 +713,12 @@ logs:
 - Performance metrics
 
 **Testing Enhancements**
-- Automated health checks
+- Automated health checks across all services
-- Service integration testing
+- Service integration testing with network isolation
-- Load balancing validation
+- Load balancing validation through Traefik
-- SSL certificate verification
+- SSL certificate verification for desktop and mobile
+- Mobile device testing workflow validation
+- Cross-network service communication testing
 
 ## Observability & Monitoring
 
@@ -507,6 +749,32 @@ metrics:
 
 ### Health Monitoring
 
+**Service Health Dashboard**
+- Real-time service status via Traefik dashboard
+- Historical health trends (Phase 4 enhancement)
+- Network connectivity validation
+- Mobile accessibility monitoring
+
+**Critical Monitoring Points:**
+1. **Service Discovery**: All services registered with Traefik
+2. **Network Isolation**: Services only accessible via designated networks
+3. **SSL Certificate Status**: Valid certificates for all domains
+4. **Mobile Compatibility**: Certificate trust and network accessibility
+5. **Database Connectivity**: Cross-network database access patterns
+6. **Platform API Authentication**: Service-to-service authentication working
+
+**Development Health Checks:**
+```bash
+# Quick health validation
+make health-check-all
+make service-discovery
+make network-inspect
+
+# Mobile testing validation
+make mobile-setup
+curl -k https://admin.motovaultpro.com/health  # From mobile device IP
+```
+
 **Service Health Dashboard**
 - Real-time service status
 - Historical health trends
@@ -601,11 +869,13 @@ metrics:
 
 ### Backup Strategy
 
-- Backup current docker-compose.yml
+**Critical Data Backup:**
-- Backup nginx configuration
+- Backup platform services PostgreSQL database:
-- Export service configurations
+  ```bash
-- Document current network topology
+  docker compose exec platform-postgres pg_dump -U platform_user platform > platform_backup_$(date +%Y%m%d_%H%M%S).sql
-- Save working environment variables
+  ```
+
+**Note:** All other services are stateless or use development data that can be recreated. Application database, Redis, and MinIO contain only development data.
 
 ## Success Metrics
 
@@ -650,6 +920,23 @@ metrics:
 
 ## Conclusion
 
-This comprehensive redesign transforms the Docker Compose architecture to closely mirror Kubernetes deployment patterns while maintaining all existing functionality and improving the development experience. The phased migration approach ensures minimal disruption while delivering immediate benefits in observability, security, and maintainability.
+This aggressive redesign completely replaces the Docker Compose architecture with a production-ready K8s-equivalent setup in 2-3 days. **Breaking changes are the strategy** - eliminating all development shortcuts and implementing true production constraints from day one.
 
-The new architecture provides a solid foundation for future Kubernetes migration while enhancing current development workflows with modern service discovery, monitoring, and configuration management practices.
+### **Key Transformation**
+- **11 services** migrated from single-network to 4-network isolation
+- **10+ exposed ports** reduced to 3 (Traefik only)
+- **35+ environment variables** replaced with mandatory file-based configuration
+- **All development bypasses removed** - production security enforced
+- **Direct service access eliminated** - all traffic through Traefik
+
+### **Benefits of Aggressive Approach**
+1. **Faster Implementation**: 2-3 days vs 4 weeks of gradual migration
+2. **Authentic K8s Simulation**: True production constraints from start
+3. **No Legacy Debt**: Clean architecture without compatibility layers
+4. **Better Security**: Production-only mode eliminates development vulnerabilities
+5. **Simplified Testing**: Single target architecture instead of multiple transition states
+
+### **Post-Migration State**
+The new architecture provides an exact Docker Compose equivalent of Kubernetes deployment patterns. All services operate under production constraints with proper isolation, authentication, and resource management. This setup can be directly translated to Kubernetes manifests with minimal changes.
+
+**Development teams gain production-like experience while maintaining local development efficiency through container-based workflows and Traefik-based service discovery.**

backend/src/app.ts

@@ -43,6 +43,28 @@ async function buildApp(): Promise<FastifyInstance> {
     });
   });
 
+  // Traefik forward-auth integration endpoint
+  app.get('/auth/verify', {
+    preHandler: [app.authenticate]
+  }, async (request, reply) => {
+    const user = request.user ?? {};
+    const userId = typeof user.sub === 'string' ? user.sub : 'unknown';
+    const rolesClaim = user['https://motovaultpro.com/roles'];
+    const roles = Array.isArray(rolesClaim) ? rolesClaim : [];
+
+    reply
+      .header('X-Auth-User', userId)
+      .header('X-Auth-Roles', roles.join(','))
+      .code(200)
+      .send({
+        status: 'verified',
+        userId,
+        roles,
+        tenantId: user['https://motovaultpro.com/tenant_id'] ?? null,
+        verifiedAt: new Date().toISOString()
+      });
+  });
+
   // Register Fastify feature routes
   await app.register(vehiclesRoutes, { prefix: '/api' });
   await app.register(fuelLogsRoutes, { prefix: '/api' });

config/app/production.yml.example

@@ -0,0 +1,30 @@
+# MotoVaultPro application ConfigMap template
+server:
+  port: 3001
+  tenant_id: admin
+
+database:
+  host: admin-postgres
+  port: 5432
+  name: motovaultpro
+  user: postgres
+
+redis:
+  host: admin-redis
+  port: 6379
+
+minio:
+  endpoint: admin-minio
+  port: 9000
+  bucket: motovaultpro
+
+auth0:
+  domain: motovaultpro.us.auth0.com
+  audience: https://api.motovaultpro.com
+
+platform:
+  vehicles_api_url: http://mvp-platform-vehicles-api:8000
+  tenants_api_url: http://mvp-platform-tenants:8000
+
+external:
+  vpic_api_url: https://vpic.nhtsa.dot.gov/api/vehicles

config/platform/production.yml.example

@@ -0,0 +1,23 @@
+# MotoVaultPro platform services ConfigMap template
+tenants_service:
+  database:
+    host: platform-postgres
+    port: 5432
+    name: platform
+    user: platform_user
+  auth0:
+    domain: motovaultpro.us.auth0.com
+    audience: https://api.motovaultpro.com
+
+vehicles_service:
+  database:
+    host: mvp-platform-vehicles-db
+    port: 5432
+    name: vehicles
+    user: mvp_platform_user
+  redis:
+    host: mvp-platform-vehicles-redis
+    port: 6379
+  cors_allow_origins:
+    - https://admin.motovaultpro.com
+    - https://motovaultpro.com

docker-compose.yml

@@ -302,105 +302,6 @@ services:
       interval: 10s
       timeout: 5s
       retries: 5
-  mvp-platform-vehicles-mssql:
-    image: mcr.microsoft.com/mssql/server:2019-CU32-ubuntu-20.04
-    container_name: mvp-platform-vehicles-mssql
-    profiles:
-    - mssql-monthly
-    user: root
-    environment:
-      ACCEPT_EULA: Y
-      SA_PASSWORD: Platform123!
-      MSSQL_PID: Developer
-    volumes:
-    - platform_vehicles_mssql_data:/var/opt/mssql/data
-    - ./mvp-platform-services/vehicles/mssql/backups:/backups
-    ports:
-    - 1433:1433
-    healthcheck:
-      test:
-      - CMD-SHELL
-      - /opt/mssql-tools18/bin/sqlcmd -C -S localhost -U sa -P 'Platform123!' -Q 'SELECT
-        1' || exit 1
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 60s
-  mvp-platform-vehicles-etl:
-    build:
-      context: ./mvp-platform-services/vehicles
-      dockerfile: docker/Dockerfile.etl
-    container_name: mvp-platform-vehicles-etl
-    environment:
-      MSSQL_HOST: mvp-platform-vehicles-mssql
-      MSSQL_PORT: 1433
-      MSSQL_DATABASE: VPICList
-      MSSQL_USER: sa
-      MSSQL_PASSWORD: Platform123!
-      POSTGRES_HOST: mvp-platform-vehicles-db
-      POSTGRES_PORT: 5432
-      POSTGRES_DATABASE: vehicles
-      POSTGRES_USER: mvp_platform_user
-      POSTGRES_PASSWORD: platform123
-      REDIS_HOST: mvp-platform-vehicles-redis
-      REDIS_PORT: 6379
-      ETL_SCHEDULE: 0 2 * * 0
-    volumes:
-    - ./mvp-platform-services/vehicles/etl:/app/etl
-    - ./mvp-platform-services/vehicles/logs:/app/logs
-    - ./mvp-platform-services/vehicles/mssql/backups:/app/shared
-    depends_on:
-    - mvp-platform-vehicles-db
-    - mvp-platform-vehicles-redis
-    deploy:
-      resources:
-        limits:
-          memory: 6G
-          cpus: '4.0'
-        reservations:
-          memory: 3G
-          cpus: '2.0'
-    healthcheck:
-      test:
-      - CMD
-      - python
-      - -c
-      - import psycopg2; psycopg2.connect(host='mvp-platform-vehicles-db', port=5432,
-        database='vehicles', user='mvp_platform_user', password='platform123').close()
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
-  mvp-platform-vehicles-etl-manual:
-    build:
-      context: ./mvp-platform-services/vehicles
-      dockerfile: docker/Dockerfile.etl
-    container_name: mvp-platform-vehicles-etl-manual
-    profiles:
-    - manual
-    environment:
-      POSTGRES_HOST: mvp-platform-vehicles-db
-      POSTGRES_PORT: 5432
-      POSTGRES_DATABASE: vehicles
-      POSTGRES_USER: mvp_platform_user
-      POSTGRES_PASSWORD: platform123
-      REDIS_HOST: mvp-platform-vehicles-redis
-      REDIS_PORT: 6379
-    volumes:
-    - ./mvp-platform-services/vehicles/etl:/app/etl
-    - ./mvp-platform-services/vehicles/logs:/app/logs
-    depends_on:
-    - mvp-platform-vehicles-db
-    - mvp-platform-vehicles-redis
-    deploy:
-      resources:
-        limits:
-          memory: 4G
-          cpus: '2.0'
-        reservations:
-          memory: 2G
-          cpus: '1.0'
-    command: ["tail", "-f", "/dev/null"]
   mvp-platform-vehicles-api:
     build:
       context: ./mvp-platform-services/vehicles

secrets/app/auth0-client-secret.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_AUTH0_CLIENT_SECRET

secrets/app/google-maps-api-key.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_GOOGLE_MAPS_API_KEY

secrets/app/minio-access-key.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_MINIO_ACCESS_KEY

secrets/app/minio-secret-key.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_MINIO_SECRET_KEY

secrets/app/platform-vehicles-api-key.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_PLATFORM_VEHICLES_API_KEY

secrets/app/postgres-password.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_APPLICATION_DB_PASSWORD

secrets/platform/platform-db-password.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_PLATFORM_DB_PASSWORD

secrets/platform/vehicles-db-password.txt.example

@@ -0,0 +1 @@
+REPLACE_WITH_VEHICLES_DB_PASSWORD