# MotoVaultPro — Simplified Architecture

Simplified 5-container architecture 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.

## Quick Start (containers)
```bash
make setup    # build + start + migrate (uses mvp-* containers)
make start    # start 5 services
make rebuild  # rebuild on changes
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.