Stuff

docs/DATABASE-SCHEMA.md

@@ -66,27 +66,30 @@ vin_cache (
 **TTL**: 30 days (application-managed)
 
 ### fuel_logs
-Tracks fuel purchases and efficiency.
+Tracks fuel purchases and efficiency metrics.
 
 ```sql
 fuel_logs (
   id UUID PRIMARY KEY,
   user_id VARCHAR(255) NOT NULL,
-  vehicle_id UUID NOT NULL REFERENCES vehicles(id),
-  date DATE NOT NULL,
-  odometer_reading INTEGER NOT NULL,
-  gallons DECIMAL(8,3) NOT NULL,
-  price_per_gallon DECIMAL(6,3),
-  total_cost DECIMAL(8,2),
-  station_name VARCHAR(200),
+  vehicle_id UUID NOT NULL REFERENCES vehicles(id) ON DELETE CASCADE,
+  date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+  odometer INTEGER,
+  trip_distance DECIMAL(10,2),
+  fuel_type VARCHAR(50),
+  fuel_grade VARCHAR(50),
+  fuel_units DECIMAL(10,3) NOT NULL,
+  cost_per_unit DECIMAL(10,3) NOT NULL,
+  total_cost DECIMAL(10,2),
+  location_data VARCHAR(500),
   notes TEXT,
   created_at TIMESTAMP WITH TIME ZONE,
   updated_at TIMESTAMP WITH TIME ZONE
 )
 ```
 
-**Foreign Keys**: vehicle_id → vehicles.id
-**Indexes**: user_id, vehicle_id, date
+**Foreign Keys**: vehicle_id → vehicles.id (ON DELETE CASCADE)
+**Indexes**: user_id, vehicle_id, date_time, created_at
 
 ### stations
 Gas station locations and details.
@@ -107,7 +110,8 @@ stations (
 ```
 
 **External Source**: Google Maps Places API
-**Cache Strategy**: 1 hour TTL via Redis
+**Storage**: Persisted in PostgreSQL with station_cache table
+**Cache Strategy**: Postgres-based cache with TTL management
 
 ### maintenance
 Vehicle maintenance records and scheduling.
@@ -116,8 +120,9 @@ Vehicle maintenance records and scheduling.
 maintenance (
   id UUID PRIMARY KEY,
   user_id VARCHAR(255) NOT NULL,
-  vehicle_id UUID NOT NULL REFERENCES vehicles(id),
-  type VARCHAR(100) NOT NULL, -- oil_change, tire_rotation, etc
+  vehicle_id UUID NOT NULL REFERENCES vehicles(id) ON DELETE CASCADE,
+  type VARCHAR(100) NOT NULL,
+  category VARCHAR(50),
   description TEXT,
   due_date DATE,
   due_mileage INTEGER,
@@ -132,8 +137,9 @@ maintenance (
 )
 ```
 
-**Foreign Keys**: vehicle_id → vehicles.id
+**Foreign Keys**: vehicle_id → vehicles.id (ON DELETE CASCADE)
 **Indexes**: user_id, vehicle_id, due_date, is_completed
+**Constraints**: Unique(vehicle_id, type), Check(category IN valid values)
 
 ## Relationships
 
@@ -153,9 +159,10 @@ stations (independent - no FK relationships)
 - No cross-user data access possible
 
 ### Referential Integrity
-- fuel_logs.vehicle_id → vehicles.id (CASCADE on update, RESTRICT on delete)
-- maintenance.vehicle_id → vehicles.id (CASCADE on update, RESTRICT on delete)
-- Soft deletes on vehicles (deleted_at) preserve referential data
+- fuel_logs.vehicle_id → vehicles.id (ON DELETE CASCADE)
+- maintenance.vehicle_id → vehicles.id (ON DELETE CASCADE)
+- Cascading deletes ensure related logs/maintenance are removed when vehicle is deleted
+- Soft deletes on vehicles (deleted_at) may result in orphaned hard-deleted related records
 
 ### VIN Validation
 - Exactly 17 characters
@@ -166,14 +173,16 @@ stations (independent - no FK relationships)
 ## Caching Strategy
 
 ### Application-Level Caching (Redis)
-- **VIN decodes**: 30 days (key: `vpic:vin:{vin}`)
+- **Platform dropdown data**: 6 hours (key: `dropdown:{dataType}:{params}`)
+- **VIN decodes**: 7 days (key: `vin:decode:{vin}`)
 - **User vehicle lists**: 5 minutes (key: `vehicles:user:{userId}`)
-- **Station searches**: 1 hour (key: `stations:search:{query}`)
-- **Maintenance upcoming**: 1 hour (key: `maintenance:upcoming:{userId}`)
+- **Fuel logs per vehicle**: 5 minutes (key: `fuel-logs:vehicle:{vehicleId}:{unitSystem}`)
+- **Vehicle statistics**: Real-time (no caching, fresh queries)
+- **Maintenance data**: Unit system-aware caching where applicable
 
 ### Database-Level Caching
-- **vin_cache table**: Persistent 30-day cache for vPIC API results
-- **Cleanup**: Application-managed, removes entries older than 30 days
+- **vin_cache table**: Persistent cache for VIN decodes
+- **Cleanup**: Application-managed based on TTL strategy
 
 ## Migration Commands