72275096f8
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 31s
Deploy to Staging / Deploy to Staging (pull_request) Successful in 22s
Deploy to Staging / Verify Staging (pull_request) Successful in 2m31s
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 8s
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
- Update staging workflow to use LOG_LEVEL=DEBUG - Create docs/LOGGING.md with unified logging documentation - Delete docs/UX-DEBUGGING.md (replaced by LOGGING.md) - Update architecture to 9-container (6 app + 3 logging) - Update CLAUDE.md, README.md, docs/README.md, docs/CLAUDE.md - Update docs/PLATFORM-SERVICES.md deployment section Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
255 lines
14 KiB
Markdown
255 lines
14 KiB
Markdown
# MotoVaultPro — Simplified Architecture
|
|
|
|
9-container architecture (6 application + 3 logging) with integrated platform feature.
|
|
|
|
## Requirements
|
|
- Mobile + Desktop: Implement and test every feature on both.
|
|
- Docker-first, production-only: All testing and validation in containers.
|
|
- See `CLAUDE.md` for development partnership guidelines.
|
|
|
|
## Staging and Production Commands. NOT FOR DEVELOPMENT (containers)
|
|
```bash
|
|
make setup # build + start + migrate (uses mvp-* containers)
|
|
make start # start 5 services
|
|
make rebuild #
|
|
make logs # tail all logs
|
|
make migrate # run DB migrations
|
|
```
|
|
|
|
## Documentation
|
|
- AI context: `.ai/context.json` (architecture, quick start, metadata)
|
|
- Sprint workflow: `.ai/workflow-contract.json` (issue tracking)
|
|
- Docs hub: `docs/README.md`
|
|
- Features: `backend/src/features/{name}/README.md`
|
|
- Frontend: `frontend/README.md`
|
|
- Backend core: `backend/src/core/README.md`
|
|
|
|
## URLs and Hosts
|
|
- Frontend: `https://motovaultpro.com`
|
|
- Backend health: `https://motovaultpro.com/api/health`
|
|
|
|
## Operational Commands
|
|
- View active environment on production: `sudo cat /opt/motovaultpro/config/deployment/state.json`
|
|
- Switch traffic between environments on production: `sudo ./scripts/ci/switch-traffic.sh blue instant`
|
|
- View which container images are running: `docker ps --format 'table {{.Names}}\t{{.Image}}'`
|
|
- Flush all redis cache: `docker compose exec -T mvp-redis sh -lc "redis-cli FLUSHALL"`
|
|
- Flush all backup data on staging before restoring: `docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "TRUNCATE TABLE backup_history, backup_schedules, backup_settings RESTART IDENTITY CASCADE;"`
|
|
|
|
## Development Workflow
|
|
|
|
```
|
|
MotoVaultPro Development Workflow
|
|
============================================================================
|
|
|
|
SPRINT ISSUE SELECTION
|
|
----------------------
|
|
|
|
+--------------------+ +---------------------+
|
|
| Gitea Issue Board | | status/backlog |
|
|
| (Source of Truth) |------->| |
|
|
+--------------------+ +----------+----------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
| status/ready |
|
|
| (Current Sprint) |
|
|
+----------+----------+
|
|
|
|
|
Select smallest + highest priority
|
|
|
|
|
v
|
|
+---------------------+
|
|
| status/in-progress |
|
|
+----------+----------+
|
|
|
|
|
============================================================================
|
|
|
|
PRE-PLANNING SKILLS (Optional)
|
|
------------------------------
|
|
|
|
|
|
|
+-----------------------------------+-----------------------------------+
|
|
| | |
|
|
v v v
|
|
+------------------+ +------------------+ +------------------+
|
|
| CODEBASE | | PROBLEM | | DECISION |
|
|
| ANALYSIS SKILL | | ANALYSIS SKILL | | CRITIC SKILL |
|
|
+------------------+ +------------------+ +------------------+
|
|
| When: Unfamiliar | | When: Complex | | When: Uncertain |
|
|
| area | | problem | | approach |
|
|
+------------------+ +------------------+ +------------------+
|
|
|
|
============================================================================
|
|
|
|
PLANNER SKILL: PLANNING WORKFLOW
|
|
---------------------------------
|
|
|
|
+---------------------+
|
|
| PLANNING |
|
|
| (Context, Scope, |
|
|
| Decision, Refine) |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------------------------+
|
|
| PLAN REVIEW CYCLE |
|
|
| (All results posted to Issue) |
|
|
+---------------------------------------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
+------>| QR: plan-complete- |
|
|
| | ness |
|
|
| +----------+----------+
|
|
| |
|
|
[FAIL] | [PASS] |
|
|
| v
|
|
| +---------------------+
|
|
| | QR: plan-code |
|
|
| | (RULE 0/1/2) |
|
|
| +----------+----------+
|
|
| |
|
|
[FAIL]-----+ [PASS] |
|
|
v
|
|
+---------------------+
|
|
+------>| TW: plan-scrub |
|
|
| +----------+----------+
|
|
| |
|
|
| v
|
|
| +---------------------+
|
|
| | QR: plan-docs |
|
|
| +----------+----------+
|
|
| |
|
|
[FAIL]-----+ [PASS] |
|
|
v
|
|
+---------------------+
|
|
| PLAN APPROVED |
|
|
+----------+----------+
|
|
|
|
|
============================================================================
|
|
|
|
EXECUTION
|
|
---------
|
|
|
|
|
|
|
v
|
|
+---------------------+
|
|
| Create Branch |
|
|
| issue-{N}-{slug} |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------------------------+
|
|
| MILESTONE EXECUTION |
|
|
| (Parallel Developer Agents) |
|
|
+---------------------------------------+
|
|
|
|
|
+---------------------------------------------------------+
|
|
| +---------------+ +---------------+ +---------------+
|
|
| | FEATURE AGENT | | FRONTEND | | PLATFORM |
|
|
| | (Backend) | | AGENT (React) | | AGENT |
|
|
| +-------+-------+ +-------+-------+ +-------+-------+
|
|
| | | |
|
|
| +------------------+------------------+
|
|
| |
|
|
| Delegate to DEVELOPER role-agent
|
|
| |
|
|
+---------------------------------------------------------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
+------>| QR: post- |
|
|
| | implementation |
|
|
| +----------+----------+
|
|
| |
|
|
| [FAIL] | [PASS]
|
|
| | |
|
|
+------+ v
|
|
+---------------------+
|
|
| TW: Documentation |
|
|
+----------+----------+
|
|
|
|
|
============================================================================
|
|
|
|
PR AND REVIEW
|
|
-------------
|
|
|
|
|
|
|
v
|
|
+---------------------+
|
|
| Open PR |
|
|
| Fixes #{N} |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
| status/review |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------------------------+
|
|
| QUALITY AGENT |
|
|
| (Final Gatekeeper - ALL GREEN) |
|
|
+---------------------------------------+
|
|
|
|
|
+-----------------------+-----------------------+
|
|
v v v
|
|
+------------------+ +------------------+ +------------------+
|
|
| npm run lint | | npm run type- | | npm test |
|
|
| | | check | | |
|
|
+------------------+ +------------------+ +------------------+
|
|
| | |
|
|
v v v
|
|
+------------------+ +------------------+ +------------------+
|
|
| Mobile Viewport | | Desktop Viewport | | RULE 0/1/2 |
|
|
| (320px, 768px) | | (1920px) | | Review |
|
|
+------------------+ +------------------+ +------------------+
|
|
| | |
|
|
+-----------------------+-----------------------+
|
|
|
|
|
[FAIL] | [PASS]
|
|
| | |
|
|
v | v
|
|
+---------------+ | +---------------------+
|
|
| Fix & Iterate |<--------+ | PR APPROVED |
|
|
+---------------+ +----------+----------+
|
|
|
|
|
============================================================================
|
|
|
|
COMPLETION
|
|
----------
|
|
|
|
+---------------------+
|
|
| Merge PR to main |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
| status/done |
|
|
+----------+----------+
|
|
|
|
|
v
|
|
+---------------------+
|
|
| DOC-SYNC SKILL |
|
|
+---------------------+
|
|
|
|
============================================================================
|
|
|
|
LEGEND
|
|
------
|
|
Skills: codebase-analysis, problem-analysis, decision-critic, planner, doc-sync
|
|
Role-Agents: Developer, Technical Writer (TW), Quality Reviewer (QR), Debugger
|
|
Domain Agents: Feature Agent, Frontend Agent, Platform Agent, Quality Agent
|
|
|
|
Labels: status/backlog -> status/ready -> status/in-progress -> status/review -> status/done
|
|
Commits: {type}: {summary} (refs #{N}) | Types: feat, fix, chore, docs, refactor, test
|
|
Branches: issue-{N}-{slug} | Example: issue-42-add-fuel-report
|
|
|
|
QUALITY RULES
|
|
-------------
|
|
RULE 0 (CRITICAL): Production reliability - unhandled errors, security, resource exhaustion
|
|
RULE 1 (HIGH): Project conformance - mobile+desktop, naming conventions, CI/CD pass
|
|
RULE 2 (SHOULD_FIX): Structural quality - god objects, duplicate logic, dead code
|
|
```
|
|
|
|
See `.ai/workflow-contract.json` for the complete workflow specification. |