egullickson/motovaultpro
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Fix documentation drift across repository #7

New Issue
Closed
opened 2026-01-03 20:59:58 +00:00 by egullickson · 6 comments
egullickson commented 2026-01-03 20:59:58 +00:00
Owner
Copy Link
Copy Source

Problem Statement

Significant documentation drift discovered across MotoVaultPro's documentation:

  • 15 backend features exist, but high-level documentation only covers 7
  • Dead link to docs/ADMIN.md (feature removed)
  • VEHICLES-API.md has multiple incorrect file paths, wrong CI system references
  • DATABASE-SCHEMA.md missing tables from 8+ features
  • context.json missing 8 feature entries

Scope

In Scope:

  • .ai/context.json - add 8 missing features
  • docs/README.md - add features, remove dead ADMIN.md link
  • docs/DATABASE-SCHEMA.md - document all tables
  • docs/ARCHITECTURE-OVERVIEW.md - add 9 missing features
  • docs/TESTING.md - add 8 missing features
  • docs/VEHICLES-API.md - complete rewrite
  • backend/src/features/user-preferences/README.md - create missing doc

Out of Scope:

  • Feature-level README.md content (already accurate)

Missing Features (8)

These features exist in code but are missing from high-level documentation:

  1. auth - Authentication endpoints
  2. backup - Database backup/restore
  3. notifications - Email/push notifications
  4. onboarding - User onboarding flow
  5. terms-agreement - Terms & Conditions acceptance
  6. user-export - GDPR data export
  7. user-preferences - User settings
  8. user-profile - Profile management

Milestones

  • M1: Update .ai/context.json - add 8 missing features
  • M2: Update docs/README.md - add features, remove ADMIN.md dead link
  • M3: Update docs/DATABASE-SCHEMA.md - document all tables
  • M4: Update docs/ARCHITECTURE-OVERVIEW.md - add 9 missing features
  • M5: Update docs/TESTING.md - add 8 missing features
  • M6: Rewrite docs/VEHICLES-API.md - complete rewrite
  • M7: Create backend/src/features/user-preferences/README.md

Key Decisions

Decision Reasoning
CLAUDE.md = navigation only User specified no duplication with README.md
Remove ADMIN.md reference Feature is gone - remove link, don't create file
Rewrite VEHICLES-API.md Too many errors to patch (wrong paths, wrong CI, outdated params)

Acceptance Criteria

  • All 15 features documented in context.json
  • No dead links in documentation
  • All file paths in docs reference actual files
  • VEHICLES-API.md matches current implementation
  • All database tables documented
## Problem Statement Significant documentation drift discovered across MotoVaultPro's documentation: - **15 backend features exist**, but high-level documentation only covers 7 - Dead link to `docs/ADMIN.md` (feature removed) - `VEHICLES-API.md` has multiple incorrect file paths, wrong CI system references - `DATABASE-SCHEMA.md` missing tables from 8+ features - `context.json` missing 8 feature entries ## Scope **In Scope:** - `.ai/context.json` - add 8 missing features - `docs/README.md` - add features, remove dead ADMIN.md link - `docs/DATABASE-SCHEMA.md` - document all tables - `docs/ARCHITECTURE-OVERVIEW.md` - add 9 missing features - `docs/TESTING.md` - add 8 missing features - `docs/VEHICLES-API.md` - complete rewrite - `backend/src/features/user-preferences/README.md` - create missing doc **Out of Scope:** - Feature-level README.md content (already accurate) ## Missing Features (8) These features exist in code but are missing from high-level documentation: 1. `auth` - Authentication endpoints 2. `backup` - Database backup/restore 3. `notifications` - Email/push notifications 4. `onboarding` - User onboarding flow 5. `terms-agreement` - Terms & Conditions acceptance 6. `user-export` - GDPR data export 7. `user-preferences` - User settings 8. `user-profile` - Profile management ## Milestones - [ ] **M1**: Update `.ai/context.json` - add 8 missing features - [ ] **M2**: Update `docs/README.md` - add features, remove ADMIN.md dead link - [ ] **M3**: Update `docs/DATABASE-SCHEMA.md` - document all tables - [ ] **M4**: Update `docs/ARCHITECTURE-OVERVIEW.md` - add 9 missing features - [ ] **M5**: Update `docs/TESTING.md` - add 8 missing features - [ ] **M6**: Rewrite `docs/VEHICLES-API.md` - complete rewrite - [ ] **M7**: Create `backend/src/features/user-preferences/README.md` ## Key Decisions | Decision | Reasoning | |----------|-----------| | CLAUDE.md = navigation only | User specified no duplication with README.md | | Remove ADMIN.md reference | Feature is gone - remove link, don't create file | | Rewrite VEHICLES-API.md | Too many errors to patch (wrong paths, wrong CI, outdated params) | ## Acceptance Criteria - [ ] All 15 features documented in `context.json` - [ ] No dead links in documentation - [ ] All file paths in docs reference actual files - [ ] `VEHICLES-API.md` matches current implementation - [ ] All database tables documented
egullickson added the
status
in-progress
type
docs
 labels 2026-01-03 21:00:13 +00:00
egullickson commented 2026-01-03 21:02:10 +00:00
Author
Owner
Copy Link
Copy Source

M1 Complete: Updated .ai/context.json

Added 8 missing features to application_features:

  • auth - User signup, email verification workflow using Auth0
  • backup - Manual and scheduled database/document backups with retention policies
  • notifications - Email and toast notifications for maintenance due/overdue and expiring documents
  • onboarding - User onboarding flow after email verification
  • terms-agreement - Legal audit trail for Terms & Conditions acceptance at signup
  • user-export - GDPR-compliant user data export
  • user-preferences - User preference management (unit system, currency, timezone)
  • user-profile - User profile management (email, display name, notification email)

Also updated:

  • feature_dependencies.sequence - now includes all 15 features in dependency order
  • external_services.external_apis - added Resend

Status: context.json now documents all 15 features with correct paths, types, database tables, and descriptions.

## M1 Complete: Updated `.ai/context.json` Added 8 missing features to `application_features`: - `auth` - User signup, email verification workflow using Auth0 - `backup` - Manual and scheduled database/document backups with retention policies - `notifications` - Email and toast notifications for maintenance due/overdue and expiring documents - `onboarding` - User onboarding flow after email verification - `terms-agreement` - Legal audit trail for Terms & Conditions acceptance at signup - `user-export` - GDPR-compliant user data export - `user-preferences` - User preference management (unit system, currency, timezone) - `user-profile` - User profile management (email, display name, notification email) Also updated: - `feature_dependencies.sequence` - now includes all 15 features in dependency order - `external_services.external_apis` - added Resend **Status**: context.json now documents all 15 features with correct paths, types, database tables, and descriptions.
egullickson commented 2026-01-03 21:02:42 +00:00
Author
Owner
Copy Link
Copy Source

M2 Complete: Updated docs/README.md

Changes:

  • Removed dead link to docs/ADMIN.md (feature removed)
  • Added 8 missing feature README links to navigation
  • Updated feature count from 7 to 15
  • Alphabetized feature list for consistency

All 15 features now have navigation links in the documentation hub.

## M2 Complete: Updated `docs/README.md` Changes: - Removed dead link to `docs/ADMIN.md` (feature removed) - Added 8 missing feature README links to navigation - Updated feature count from 7 to 15 - Alphabetized feature list for consistency All 15 features now have navigation links in the documentation hub.
egullickson commented 2026-01-03 21:04:38 +00:00
Author
Owner
Copy Link
Copy Source

M3 Complete: Updated docs/DATABASE-SCHEMA.md

Major rewrite documenting all database tables:

Added sections:

  • Admin Tables: admin_users, admin_audit_logs
  • User Tables: user_profiles, user_preferences, terms_agreements
  • Station Tables: Added community_stations
  • Platform Tables: engines, transmissions, vehicle_options
  • Notification Tables: email_templates, notification_logs
  • Backup Tables: backup_schedules, backup_history, backup_settings

Fixed:

  • Renamed maintenance -> maintenance_logs and maintenance_schedules (split tables)
  • Updated vehicles table to include new columns (trim, engine, transmission, image_bucket, image_key)
  • Added documents table with email_notifications column
  • Updated Migration Order to include all 12 features with migrations
  • Added notes about features without migrations (auth, onboarding, user-export)

Database schema documentation now covers all 25+ tables.

## M3 Complete: Updated `docs/DATABASE-SCHEMA.md` Major rewrite documenting all database tables: **Added sections:** - Admin Tables: `admin_users`, `admin_audit_logs` - User Tables: `user_profiles`, `user_preferences`, `terms_agreements` - Station Tables: Added `community_stations` - Platform Tables: `engines`, `transmissions`, `vehicle_options` - Notification Tables: `email_templates`, `notification_logs` - Backup Tables: `backup_schedules`, `backup_history`, `backup_settings` **Fixed:** - Renamed `maintenance` -> `maintenance_logs` and `maintenance_schedules` (split tables) - Updated vehicles table to include new columns (trim, engine, transmission, image_bucket, image_key) - Added documents table with email_notifications column - Updated Migration Order to include all 12 features with migrations - Added notes about features without migrations (auth, onboarding, user-export) Database schema documentation now covers all 25+ tables.
egullickson commented 2026-01-03 21:05:49 +00:00
Author
Owner
Copy Link
Copy Source

M4 & M5 Complete

M4: Updated docs/ARCHITECTURE-OVERVIEW.md

  • Updated Feature Capsule Architecture section to list all 15 features
  • Rewrote Current Features section with all 15 features including tables, integrations, and endpoints
  • Fixed table names (maintenance_logs, maintenance_schedules instead of maintenance_records)
  • Added community_stations to stations feature

M5: Updated docs/TESTING.md

  • Updated Coverage and Availability section to list all 15 features
  • Noted which features have unit-only vs unit+integration tests

Next: M6 - Complete rewrite of VEHICLES-API.md

## M4 & M5 Complete ### M4: Updated `docs/ARCHITECTURE-OVERVIEW.md` - Updated Feature Capsule Architecture section to list all 15 features - Rewrote Current Features section with all 15 features including tables, integrations, and endpoints - Fixed table names (`maintenance_logs`, `maintenance_schedules` instead of `maintenance_records`) - Added community_stations to stations feature ### M5: Updated `docs/TESTING.md` - Updated Coverage and Availability section to list all 15 features - Noted which features have unit-only vs unit+integration tests Next: M6 - Complete rewrite of VEHICLES-API.md
egullickson commented 2026-01-03 21:07:56 +00:00
Author
Owner
Copy Link
Copy Source

M6 Complete: Rewrote docs/VEHICLES-API.md

Complete rewrite of the Vehicles API documentation:

Removed outdated content:

  • Wrong database schema (fake tables like make, model, model_year, trim)
  • Wrong API parameters (make_id, model_id, trim_id - actual API uses string names)
  • Reference to .github/workflows/ci.yml (we use .gitea/workflows/)
  • References to non-existent migration files
  • Complex operational information that was outdated

Added accurate content:

  • All actual vehicle CRUD endpoints from vehicles.routes.ts
  • Image upload/download/delete endpoints
  • Complete dropdown cascade API with correct parameters
  • Platform API endpoints
  • Correct database schema references (engines, transmissions, vehicle_options)
  • Accurate migration file location
  • Frontend integration section

Document now accurately reflects the current implementation.

## M6 Complete: Rewrote `docs/VEHICLES-API.md` Complete rewrite of the Vehicles API documentation: **Removed outdated content:** - Wrong database schema (fake tables like `make`, `model`, `model_year`, `trim`) - Wrong API parameters (`make_id`, `model_id`, `trim_id` - actual API uses string names) - Reference to `.github/workflows/ci.yml` (we use `.gitea/workflows/`) - References to non-existent migration files - Complex operational information that was outdated **Added accurate content:** - All actual vehicle CRUD endpoints from `vehicles.routes.ts` - Image upload/download/delete endpoints - Complete dropdown cascade API with correct parameters - Platform API endpoints - Correct database schema references (engines, transmissions, vehicle_options) - Accurate migration file location - Frontend integration section Document now accurately reflects the current implementation.
egullickson commented 2026-01-03 21:08:59 +00:00
Author
Owner
Copy Link
Copy Source

M7 Complete: Created backend/src/features/user-preferences/README.md

Created missing documentation for the user-preferences feature:

  • Overview and architecture
  • GET and PUT endpoint documentation with request/response examples
  • Validation rules
  • Default values
  • Integration points
  • Database table reference

All Milestones Complete

All 7 milestones have been completed:

  • M1: Updated .ai/context.json - added 8 missing features
  • M2: Updated docs/README.md - added features, removed ADMIN.md dead link
  • M3: Updated docs/DATABASE-SCHEMA.md - documented all 25+ tables
  • M4: Updated docs/ARCHITECTURE-OVERVIEW.md - added all 15 features
  • M5: Updated docs/TESTING.md - added all 15 features
  • M6: Rewrote docs/VEHICLES-API.md - complete rewrite
  • M7: Created backend/src/features/user-preferences/README.md

Summary of changes:

  • 8 previously undocumented features are now in all high-level docs
  • Dead link to docs/ADMIN.md removed
  • All database tables documented
  • VEHICLES-API.md rewritten with correct API parameters and file paths
  • All 15 features now documented with correct table names and descriptions
## M7 Complete: Created `backend/src/features/user-preferences/README.md` Created missing documentation for the user-preferences feature: - Overview and architecture - GET and PUT endpoint documentation with request/response examples - Validation rules - Default values - Integration points - Database table reference --- ## All Milestones Complete All 7 milestones have been completed: - [x] M1: Updated `.ai/context.json` - added 8 missing features - [x] M2: Updated `docs/README.md` - added features, removed ADMIN.md dead link - [x] M3: Updated `docs/DATABASE-SCHEMA.md` - documented all 25+ tables - [x] M4: Updated `docs/ARCHITECTURE-OVERVIEW.md` - added all 15 features - [x] M5: Updated `docs/TESTING.md` - added all 15 features - [x] M6: Rewrote `docs/VEHICLES-API.md` - complete rewrite - [x] M7: Created `backend/src/features/user-preferences/README.md` **Summary of changes:** - 8 previously undocumented features are now in all high-level docs - Dead link to `docs/ADMIN.md` removed - All database tables documented - VEHICLES-API.md rewritten with correct API parameters and file paths - All 15 features now documented with correct table names and descriptions
egullickson added
status
done
 and removed
status
in-progress
 labels 2026-01-03 21:09:46 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
status
backlog
status/blocked
status
done
status
in-progress
status
ready
status
review
type
bug
type
chore
type
docs
type
feature
No labels
status
done
type
docs
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
egullickson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: egullickson/motovaultpro#7