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

feat: update docs for token efficient usage
Some checks failed
Deploy to Staging / Build Images (push) Has started running
Details
Deploy to Staging / Deploy to Staging (push) Has been cancelled
Details
Deploy to Staging / Verify Staging (push) Has been cancelled
Details
Deploy to Staging / Notify Staging Ready (push) Has been cancelled
Details
Deploy to Staging / Notify Staging Failure (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Eric Gullickson
2026-01-03 11:59:47 -06:00
parent 3dd86c37ff
commit b933329539
19 changed files with 333 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.ai/CLAUDE.md Normal file
View File

@@ -0,0 +1,11 @@
# .ai/
AI context and workflow configuration for Claude Code.
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `context.json` | Architecture metadata, feature registry | Understanding system structure |
| `workflow-contract.json` | Sprint workflow, issue lifecycle | Issue/PR workflow, labels |
| `WORKFLOW-PROMPTS.md` | Workflow prompt templates | Workflow automation |

15
.claude/CLAUDE.md
View File

@@ -1,4 +1,16 @@
# .claude/ Index
# .claude/
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution |
| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
| `skills/` | Reusable skills | Complex multi-step workflows |
| `output-styles/` | Output formatting templates | Customizing agent output |
| `tdd-guard/` | TDD enforcement utilities | Test-driven development |
## Quick Reference
| Path | What | When |
|------|------|------|
@@ -10,5 +22,6 @@
| `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas |
| `skills/doc-sync/` | Documentation sync | After refactors |
| `skills/incoherence/` | Detect doc/code drift | Periodic audits |
| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts |
| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |

11
.claude/agents/CLAUDE.md Normal file
View File

@@ -0,0 +1,11 @@
# agents/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Agent team overview and coordination | Understanding agent workflow |
| `feature-agent.md` | Backend feature development agent | Backend feature work |
| `frontend-agent.md` | React/mobile-first UI agent | Frontend component work |
| `platform-agent.md` | Platform services agent | Platform microservice work |
| `quality-agent.md` | Final validation agent | Pre-merge quality checks |

10
.claude/role-agents/CLAUDE.md Normal file
View File

@@ -0,0 +1,10 @@
# role-agents/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `developer.md` | Developer role agent | Code implementation tasks |
| `technical-writer.md` | Technical writer agent | Documentation tasks |
| `quality-reviewer.md` | Quality reviewer with RULE 0/1/2 | Code review, quality gates |
| `debugger.md` | Debugging specialist agent | Bug investigation, troubleshooting |

13
.claude/skills/CLAUDE.md Normal file
View File

@@ -0,0 +1,13 @@
# skills/
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `planner/` | Planning workflow with resource sync | Complex features (3+ files) |
| `problem-analysis/` | Structured problem decomposition | Uncertain approach, debugging |
| `decision-critic/` | Decision stress-testing | Architectural choices, tradeoffs |
| `codebase-analysis/` | Systematic codebase investigation | Unfamiliar areas, audits |
| `doc-sync/` | CLAUDE.md/README.md synchronization | After refactors, periodic audits |
| `incoherence/` | Detect doc/code drift | Documentation inconsistencies |
| `prompt-engineer/` | Prompt optimization techniques | Improving AI prompts |

14
.claude/skills/doc-sync/CLAUDE.md Normal file
View File

@@ -0,0 +1,14 @@
# skills/doc-sync/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Skill overview and usage examples | Understanding when to use doc-sync |
| `SKILL.md` | Complete skill workflow definition | Executing the doc-sync skill |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `references/` | Trigger pattern examples | Writing good CLAUDE.md triggers |

70
.gitea/ISSUE_TEMPLATE/feature.yml
View File

@@ -1,70 +0,0 @@
name: "Feature"
about: "New capability or enhancement"
title: "[Feature]: "
labels:
- "type/feature"
- "status/backlog"
body:
- type: markdown
attributes:
value: |
Use this for a new feature or enhancement. Keep scope tight and include clear acceptance criteria.
- type: textarea
id: problem
attributes:
label: "Problem / user need"
description: "What problem are we solving, and for whom?"
placeholder: "As a user, I want..., so that..."
validations:
required: true
- type: textarea
id: solution
attributes:
label: "Proposed solution"
description: "Describe the expected behavior at a high level."
placeholder: "When the user does X, the system should..."
validations:
required: true
- type: textarea
id: non_goals
attributes:
label: "Non-goals / out of scope"
description: "What are we explicitly not doing in this feature?"
placeholder: "- Not doing...\n- Not doing..."
validations:
required: false
- type: textarea
id: acceptance
attributes:
label: "Acceptance criteria"
description: "Concrete checks for ‘done’. Prefer bullets and testable statements."
placeholder: |
- [ ] ...
- [ ] ...
- [ ] ...
validations:
required: true
- type: textarea
id: notes
attributes:
label: "Implementation notes (optional)"
description: "Links, APIs, file paths, edge cases."
validations:
required: false
- type: textarea
id: test_plan
attributes:
label: "Test plan"
description: "How will we verify? Include commands or steps."
placeholder: |
- Unit:
- Integration:
- Manual:
validations:
required: true

44
CLAUDE.md
View File

@@ -1,3 +1,47 @@
# MotoVaultPro
Single-tenant vehicle management application with 5-container architecture (Traefik, Frontend, Backend, PostgreSQL, Redis).
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `Makefile` | Build, test, deploy commands | Running any make command |
| `docker-compose.yml` | Development container orchestration | Local development setup |
| `package.json` | Root workspace dependencies | Dependency management |
| `README.md` | Project overview | First-time setup |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `backend/` | Fastify API server with feature capsules | Backend development |
| `frontend/` | React/Vite SPA with MUI | Frontend development |
| `docs/` | Project documentation hub | Architecture, APIs, testing |
| `config/` | Configuration files (Traefik, monitoring) | Infrastructure setup |
| `scripts/` | Utility scripts (backup, deploy) | Automation tasks |
| `.ai/` | AI context and workflow contracts | AI-assisted development |
| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
| `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
| `ansible/` | Ansible deployment playbooks | Server provisioning |
## Build
```bash
make setup # First-time setup (builds containers, runs migrations)
make rebuild # Rebuild containers after changes
```
## Test
```bash
npm test # Run all tests
npm run lint # Linting
npm run type-check # TypeScript validation
```
---
# Development Partnership Guidelines
## Core Development Principles

18
backend/CLAUDE.md Normal file
View File

@@ -0,0 +1,18 @@
# backend/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Backend quickstart and commands | Getting started with backend development |
| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
| `jest.config.ts` | Jest test configuration | Test setup, coverage settings |
| `Dockerfile` | Container build definition | Docker builds, deployment |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `src/` | Application source code | Any backend development |
| `scripts/` | Utility scripts | Database scripts, automation |

18
backend/src/CLAUDE.md Normal file
View File

@@ -0,0 +1,18 @@
# backend/src/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `app.ts` | Fastify application setup and routes | Route registration, middleware setup |
| `index.ts` | Application entry point | Server startup, initialization |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `features/` | Feature capsules (self-contained modules) | Feature development, API endpoints |
| `core/` | Shared infrastructure (auth, config, logging) | Cross-cutting concerns, plugins |
| `_system/` | System utilities (migrations, CLI, schema) | Database migrations, schema generation |
| `shared-minimal/` | Minimal shared utilities | Shared type utilities |
| `scripts/` | Backend-specific scripts | Utility scripts |

20
backend/src/core/CLAUDE.md Normal file
View File

@@ -0,0 +1,20 @@
# backend/src/core/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Core module index with code examples | Understanding core infrastructure |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `auth/` | Authentication utilities | JWT handling, user context |
| `config/` | Configuration loading (env, database, redis) | Environment setup, connection pools |
| `logging/` | Winston structured logging | Log configuration, debugging |
| `middleware/` | Fastify middleware | Request processing, user extraction |
| `plugins/` | Fastify plugins (auth, error, logging) | Plugin registration, hooks |
| `scheduler/` | Job scheduling infrastructure | Scheduled tasks, cron jobs |
| `storage/` | Storage abstraction and adapters | File storage, S3/filesystem |
| `user-preferences/` | User preferences data and migrations | User settings storage |

22
backend/src/features/CLAUDE.md Normal file
View File

@@ -0,0 +1,22 @@
# backend/src/features/
Feature capsule directory. Each feature is 100% self-contained with api/, domain/, data/, migrations/, tests/.
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `admin/` | Admin role management, catalog CRUD | Admin functionality, user oversight |
| `auth/` | Authentication endpoints | Login, logout, session management |
| `backup/` | Database backup and restore | Backup jobs, data export/import |
| `documents/` | Document storage and management | File uploads, document handling |
| `fuel-logs/` | Fuel consumption tracking | Fuel log CRUD, statistics |
| `maintenance/` | Maintenance record management | Service records, reminders |
| `notifications/` | Email and push notifications | Alert system, email templates |
| `onboarding/` | User onboarding flow | First-time user setup |
| `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation |
| `stations/` | Gas station search and favorites | Google Maps integration, station data |
| `user-export/` | User data export | GDPR compliance, data portability |
| `user-preferences/` | User preference management | User settings API |
| `user-profile/` | User profile management | Profile CRUD, avatar handling |
| `vehicles/` | Vehicle management | Vehicle CRUD, fleet operations |

13
config/CLAUDE.md Normal file
View File

@@ -0,0 +1,13 @@
# config/
Configuration files for the 5-container architecture.
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `app/` | Application configuration | App-specific settings |
| `deployment/` | Deployment configuration | Deploy scripts, environment configs |
| `monitoring/` | Monitoring and alerts | Prometheus, alerting rules |
| `shared/` | Shared configuration | Cross-service settings |
| `traefik/` | Traefik reverse proxy config | Routing, SSL, middleware |

28
docs/CLAUDE.md Normal file
View File

@@ -0,0 +1,28 @@
# docs/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Documentation hub and navigation | Starting point for any docs |
| `PLATFORM-SERVICES.md` | 5-container architecture overview | Understanding system topology |
| `ARCHITECTURE-OVERVIEW.md` | Detailed architecture documentation | Deep dive into system design |
| `DATABASE-SCHEMA.md` | Database table definitions | Schema changes, data modeling |
| `DATABASE-MIGRATION.md` | Migration procedures | Running or writing migrations |
| `VEHICLES-API.md` | Vehicles API specification | Vehicle-related API work |
| `ADMIN.md` | Admin feature documentation | Admin role management, catalog CRUD |
| `TESTING.md` | Testing strategy and commands | Writing or running tests |
| `E2E-TESTING.md` | End-to-end testing guide | Cypress E2E test setup |
| `SECURITY.md` | Security guidelines | Security considerations |
| `CICD-DEPLOY.md` | CI/CD and deployment | Pipeline configuration, deployments |
| `BUILD-SERVER-SETUP.md` | Build server setup | Infrastructure setup |
| `AUDIT.md` | Audit documentation | Security audits, compliance |
| `MVP-COLOR-SCHEME.md` | Color scheme reference | UI styling decisions |
| `UX-DEBUGGING.md` | UX debugging techniques | Debugging UI issues |
| `PROMPTS.md` | AI prompt templates | AI-assisted development |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `changes/` | Change logs and migration notes | Understanding historical changes |

24
frontend/CLAUDE.md Normal file
View File

@@ -0,0 +1,24 @@
# frontend/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `README.md` | Frontend quickstart and patterns | Getting started with frontend development |
| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
| `vite.config.ts` | Vite build configuration | Build optimization, plugins |
| `jest.config.ts` | Jest test configuration | Test setup |
| `tailwind.config.js` | Tailwind CSS configuration | Styling, theme customization |
| `Dockerfile` | Container build definition | Docker builds, deployment |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `src/` | Application source code | Any frontend development |
| `public/` | Static assets (images, docs) | Adding static files |
| `cypress/` | E2E test definitions | End-to-end testing |
| `docs/` | Frontend-specific documentation | Frontend patterns, guidelines |
| `test/` | Test utilities and mocks | Test setup, mock data |
| `scripts/` | Frontend utility scripts | Automation scripts |

20
frontend/src/CLAUDE.md Normal file
View File

@@ -0,0 +1,20 @@
# frontend/src/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `App.tsx` | Root component with routing | Route configuration, layout structure |
| `main.tsx` | Application entry point | Provider setup, initialization |
| `index.css` | Global styles | Base styling, CSS imports |
| `vite-env.d.ts` | Vite type definitions | TypeScript environment types |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `features/` | Feature modules (pages, components, hooks) | Feature development |
| `core/` | Shared infrastructure (auth, api, store) | Cross-cutting concerns |
| `components/` | Root-level shared components | App-wide UI components |
| `pages/` | Page-level components | Page structure, routing targets |
| `shared-minimal/` | Minimal shared UI (skeletons, theme) | Reusable UI primitives |

17
frontend/src/core/CLAUDE.md Normal file
View File

@@ -0,0 +1,17 @@
# frontend/src/core/
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `api/` | API client and request handling | HTTP calls, error handling |
| `auth/` | Auth0 provider and auth hooks | Authentication setup, user context |
| `config/` | Runtime configuration | Environment-specific settings |
| `debug/` | Debug utilities | Development helpers |
| `error-boundaries/` | React error boundaries | Error handling UI |
| `hooks/` | Shared React hooks | Reusable hook patterns |
| `query/` | React Query configuration | Server state management |
| `store/` | Zustand state management | Client state, global stores |
| `sync/` | Data synchronization | Offline support, sync logic |
| `units/` | Unit conversion utilities | Measurement formatting |
| `utils/` | General utilities | Helper functions |

19
frontend/src/features/CLAUDE.md Normal file
View File

@@ -0,0 +1,19 @@
# frontend/src/features/
Feature module directory. Each feature contains pages/, components/, hooks/, api/, types/.
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `admin/` | Admin panel and catalog management | Admin UI, user management |
| `auth/` | Authentication pages and components | Login, logout, auth flows |
| `dashboard/` | Dashboard and fleet overview | Home page, summary widgets |
| `documents/` | Document management UI | File upload, document viewer |
| `fuel-logs/` | Fuel log tracking UI | Fuel entry forms, statistics |
| `maintenance/` | Maintenance record UI | Service tracking, reminders |
| `notifications/` | Notification display | Alert UI, notification center |
| `onboarding/` | Onboarding wizard | First-time user experience |
| `settings/` | User settings pages | Preferences, account settings |
| `stations/` | Gas station finder UI | Station search, favorites, map |
| `vehicles/` | Vehicle management UI | Vehicle list, details, forms |

17
scripts/CLAUDE.md Normal file
View File

@@ -0,0 +1,17 @@
# scripts/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
| `config-validator.sh` | Validate configuration files | Pre-deploy validation |
| `export-database.sh` | Export database to backup | Database backup operations |
| `import-database.sh` | Import database from backup | Database restore operations |
| `inject-secrets.sh` | Inject secrets into config | Secret management |
| `rollback.sh` | Rollback deployment | Emergency rollback procedures |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
| `ci/` | CI/CD scripts | Pipeline automation, build scripts |