100 lines
3.5 KiB
Markdown
100 lines
3.5 KiB
Markdown
# MotoVaultPro - AI Onboarding Guide
|
|
|
|
## 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. Understand the Architecture (30 seconds)
|
|
**Modified Feature Capsules**: Each feature in `backend/src/features/[name]/` is 100% self-contained with everything needed in one directory. No shared business logic.
|
|
|
|
### 3. For Specific Tasks
|
|
|
|
#### Working on a Feature
|
|
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
|
|
|
|
#### Cross-Feature Work
|
|
Load each feature's `index.ts` and `README.md`
|
|
|
|
#### Database Work
|
|
Load `docs/database-schema.md` for complete schema overview
|
|
|
|
#### 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.
|
|
|
|
### 4. Development Environment (Production-Only)
|
|
```bash
|
|
# One-time setup (copies .env and builds containers)
|
|
make setup
|
|
|
|
# Start/rebuild the full environment
|
|
make dev
|
|
```
|
|
|
|
**Production-Only Development**: This application runs in production mode only. All development happens with production builds and configurations.
|
|
|
|
### 5. Key Principles
|
|
- **Production-Only**: All development uses production builds and configuration
|
|
- **Docker-First**: All development in containers, no local installs
|
|
- **Feature Independence**: Each feature is completely isolated
|
|
- **Single Directory Context**: Load one directory for complete understanding
|
|
- **User-Scoped Data**: All data isolated by user_id
|
|
|
|
### 6. Common Tasks
|
|
```bash
|
|
# Run all migrations (inside containers)
|
|
make migrate
|
|
|
|
# Run all backend tests (inside containers)
|
|
make test
|
|
|
|
# Run tests for a specific feature (from backend container shell)
|
|
make shell-backend
|
|
npm test -- features/vehicles
|
|
|
|
# View logs
|
|
make logs
|
|
|
|
# Container shell access
|
|
make shell-backend
|
|
```
|
|
|
|
### 7. Feature Status
|
|
- **vehicles**: Complete (primary entity, VIN decoding)
|
|
- **fuel-logs**: Implemented (depends on vehicles); tests pending
|
|
- **maintenance**: Scaffolded (depends on vehicles)
|
|
- **stations**: Partial (Google Maps integration)
|
|
|
|
## SSL for Frontend (Production Development)
|
|
- Place `motovaultpro.com.crt` and `motovaultpro.com.key` in `./certs`.
|
|
- To generate self-signed certs for production development:
|
|
```bash
|
|
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
|
|
-keyout certs/motovaultpro.com.key \
|
|
-out certs/motovaultpro.com.crt \
|
|
-subj "/CN=motovaultpro.com"
|
|
```
|
|
- **Access frontend at**: `https://motovaultpro.com` (requires DNS or hosts file entry)
|
|
- **Hosts file setup**: Add `127.0.0.1 motovaultpro.com` to `/etc/hosts`
|
|
- HTTP requests redirect to HTTPS automatically.
|
|
|
|
## Architecture Summary
|
|
Vehicle management platform using Modified Feature Capsule design where each feature is self-contained with API, domain logic, database layer, migrations, external integrations, tests, and documentation in a single directory. Built for AI maintainability with production-only Docker development.
|
|
|
|
## Quick Navigation
|
|
- **Setup**: AI_PROJECT_GUIDE.md
|
|
- **Features**: backend/src/features/[name]/README.md
|
|
- **Database**: docs/database-schema.md
|
|
- **Testing**: docs/testing.md
|
|
- **Security**: docs/security.md
|