Docs Cleanup

docs/ARCHITECTURE-OVERVIEW.md

@@ -41,12 +41,6 @@ MotoVaultPro is a single-tenant vehicle management application built with a **6-
          +------------------+                        +--------------------+
               (frontend network)                          (backend network)
                                                               |
-                                                              v
-                                                     +-------------------+
-                                                     |    Platform       |
-                                                     | Python + FastAPI  |
-                                                     |   Port: 8000      |
-                                                     +-------------------+
                                                               |
                             +---------------------------------+
                             |                                 |
@@ -103,14 +97,12 @@ MotoVaultPro is a single-tenant vehicle management application built with a **6-
 7. Backend → Response → Frontend
 ```
 
-### Backend to Platform Flow
+### Backend Platform Flow
 ```
-1. Backend Feature → HTTP Request → Platform Service
-   - URL: http://mvp-platform:8000
-   - Headers: Authorization: Bearer <API_KEY>
-2. Platform → Query PostgreSQL (vehicles schema)
-3. Platform → Check/Update Redis Cache
-4. Platform → Response → Backend
+1. Backend Feature → Calls platform domain services (TypeScript in-process)
+2. Platform module → Query PostgreSQL (vehicles schema)
+3. Platform module → Check/Update Redis cache
+4. Platform response → Returned to caller (vehicles, frontend proxies, etc.)
 ```
 
 ### Data Access Flow
@@ -196,53 +188,51 @@ MotoVaultPro is a single-tenant vehicle management application built with a **6-
   - Session storage (future)
   - Rate limiting (future)
 
-### Platform (Vehicle Data Service)
-- **Technology**: Python 3.11 + FastAPI
-- **Build**: Custom Dockerfile from `mvp-platform-services/vehicles/`
-- **Port**: 8000 (internal)
-- **Networks**: backend, database
-- **Dependencies**: PostgreSQL, Redis
-- **Health Check**: `wget http://localhost:8000/health` (30s interval)
+### Platform Module (Vehicle Data)
+- **Technology**: TypeScript feature capsule inside `backend/src/features/platform/`
+- **Runtime**: Shares the `mvp-backend` Fastify container
+- **Dependencies**: PostgreSQL, Redis (accessed via backend connection pool)
+- **Deployment**: Bundled with backend build; no separate container or port
+- **Health**: Covered by backend `/health` endpoint and feature-specific logs
 - **Configuration**:
-  - `/app/config/production.yml` - Service config
-  - `/app/config/shared.yml` - Shared config
+  - `backend/src/features/platform/domain/*.ts` - Business logic
+  - `backend/src/features/platform/data/*.ts` - Database + vPIC integration
 - **Secrets**:
-  - `postgres-password` - Shared database access
+  - Reuses backend secrets (PostgreSQL, Auth0, etc.)
 - **Purpose**:
   - Vehicle make/model/trim/engine data
   - VIN decoding (planned)
   - Standardized vehicle information
 
-## Platform Service Integration
+## Platform Module Integration
 
 ### Current Architecture
-The Platform service is a **separate Python container** that provides vehicle data capabilities to the backend. This separation exists for:
-- **Technology Independence**: Python ecosystem for data processing
-- **Specialized Caching**: Year-based hierarchical caching strategy
-- **Resource Isolation**: Independent scaling and monitoring
+Platform capabilities now run **in-process** within the backend as a feature capsule. This delivers:
+- **Shared Language & Tooling**: TypeScript across the stack
+- **Centralized Caching**: Reuses backend Redis helpers for year-based lookups
+- **Simplified Operations**: No extra container to build, scale, or monitor
 
 ### Shared Infrastructure
-- **Database**: Both Backend and Platform use `mvp-postgres`
-- **Cache**: Both services share `mvp-redis`
-- **Network**: Connected via `backend` and `database` networks
-- **Secrets**: Share database credentials
+- **Database**: Uses the backend connection pool against `mvp-postgres`
+- **Cache**: Shares the backend Redis client (`mvp-redis`)
+- **Runtime**: Packaged with the `mvp-backend` container and Fastify plugins
+- **Secrets**: Relies on the same secret files as the backend (PostgreSQL, Auth0, etc.)
 
 ### Communication Pattern
-```javascript
-// Backend calls Platform via internal HTTP
-const response = await fetch('http://mvp-platform:8000/api/v1/vehicles/makes?year=2024', {
-  headers: {
-    'Authorization': `Bearer ${platformApiKey}`
-  }
+```typescript
+// Vehicles feature pulling platform data via domain services
+const platformService = new PlatformVehicleDataService({
+  db: postgresPool,
+  cache: redisClient
 });
+
+const makes = await platformService.getMakes({ year: 2024 });
 ```
 
-### Future Evolution
-**Planned**: Absorb Platform service into Backend as a feature capsule
-- Timeline: Post-MVP phase
-- Approach: Rewrite Python service in Node.js
-- Location: `backend/src/features/vehicle-platform/`
-- Benefits: Simplified deployment, shared codebase, reduced containers
+### Ongoing Work
+- Continue migrating remaining FastAPI utilities into TypeScript where needed
+- Expand `/api/platform/*` endpoints as new lookup types are added
+- Monitor backend logs for `platform` namespace entries to verify health
 
 ## Feature Capsule Architecture
 
@@ -255,7 +245,8 @@ backend/src/features/
 ├── fuel-logs/         # Fuel tracking
 ├── maintenance/       # Service records
 ├── stations/          # Gas station locations
-└── documents/         # Document storage
+├── documents/         # Document storage
+└── platform/          # Vehicle data + VIN decoding
 ```
 
 ### Feature Structure
@@ -372,7 +363,6 @@ The application uses Kubernetes-inspired configuration patterns:
 
 **Secrets** (File-based):
 - `/run/secrets/postgres-password` - Database credentials
-- `/run/secrets/platform-vehicles-api-key` - Service auth
 - `/run/secrets/auth0-client-secret` - OAuth credentials
 - `/run/secrets/google-maps-api-key` - External API keys
 
@@ -384,14 +374,13 @@ CONFIG_PATH: /app/config/production.yml
 SECRETS_DIR: /run/secrets
 DATABASE_HOST: mvp-postgres
 REDIS_HOST: mvp-redis
-PLATFORM_VEHICLES_API_URL: http://mvp-platform:8000
 ```
 
 ## Development Workflow
 
 ### Container Commands (via Makefile)
 ```bash
-make start          # Start all 6 containers
+make start          # Start all 5 containers
 make stop           # Stop all containers
 make restart        # Restart all containers
 make rebuild        # Rebuild and restart containers
@@ -407,12 +396,10 @@ docker ps
 
 # View specific service logs
 docker logs mvp-backend -f
-docker logs mvp-platform -f
 docker logs mvp-postgres -f
 
 # Test health endpoints
-curl http://localhost:3001/health  # Backend
-curl http://localhost:8000/health  # Platform
+curl http://localhost:3001/health  # Backend (includes platform module)
 ```
 
 ### Database Access