diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index e6973c5..b154dc5 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -263,3 +263,43 @@ claimed. ## Known blockers None. External service credentials may be absent; use the documented demo/degraded providers. The n8n workflow-activation steps are a one-time manual setup requirement in this environment (owner-account creation via n8n's own `/setup` UI cannot be scripted safely), fully documented in `docs/17-runbook.md` and scripted where possible (`make n8n-setup`). RAGcore and the ITWorx MCP Hub itself were never reachable in this environment — both integrations are implemented and directly tested/curl-verified against MobilityOps's own API, but neither a real RAGcore instance nor a real Hub round trip was available to confirm end-to-end. + +## Premium Control Rail UI transformation (2026-08-02) + +- Branch: `design/mobilityops-premium-ui`, branched from verified deployed revision + `dfabb41582e302f45a3de826f85f531bf23dfc8b`; master history was not rewritten. +- Audited every route at 1440, 1280, 768 and 390 px. Baseline findings and captures are + in `docs/design/current-ux-audit.md` and `artifacts/design-validation/current/`. +- Authored three twelve-screen product directions and generated representative Stitch + anchors in project `17018847755558569017`: Control Rail, Dispatch Ledger and Service + Atelier. Control Rail was selected and refined twice for hierarchy, accessibility and + responsive implementation. Decision, screen inventory, tokens and exact Stitch IDs + are in `docs/design/design-directions.md`, `docs/design/design-system.md` and + `docs/design/stitch-manifest.md`. +- Rebuilt the complete React interface around a responsive Control Rail shell: inline SVG + icon/brand system, desktop rail, named landmarks, skip link, top bar, mobile bottom + navigation, shared loading/error/empty states and reduced-motion support. +- Redesigned all shipped pages. The dashboard now prioritizes persisted readiness, + Attention and today's movements; booking results paginate at 25 rows; every responsive + table retains field labels; integrations distinguish n8n evidence, live RAGcore health + and the unconfigured MCP adapter without inventing status. +- Return registration is now capture → review → result. A regression test proves the + return endpoint is not called before confirmation; the existing idempotency and local + commit/outbox contract is unchanged. +- Final browser captures are in `artifacts/design-validation/implementation/`. DOM + measurements and Playwright both prove no horizontal overflow at 390, 768, 1280 and + 1440 px. See `docs/design/implementation-validation.md`. +- Final validation commands from this branch: + - `docker compose run --rm api pytest -q` — **66 passed**. + - `docker compose run --rm api ruff check .` — **All checks passed**. + - `docker compose run --rm api mypy app` — **0 issues in 44 files**. + - `cd frontend && npm run lint` — clean TypeScript check. + - `cd frontend && npm run build` — production build succeeded (59 modules; 238.66 kB JS, + 36.54 kB CSS before gzip). + - `cd frontend && playwright test --reporter=line` — **18 passed** including the full + five-minute demo, every interactive route, return review semantics and four viewport + overflow checks. +- Exact next action after this record: commit this evidence set, push + `design/mobilityops-premium-ui`, and deploy that branch to the + existing Unraid review stack without touching master or persistent volumes; verify live + health and responsive UI. diff --git a/README.md b/README.md index db9e990..6bfcc9e 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ MobilityOps is a working proof of concept for a fictitious mobility company. It combines vehicle and booking operations, a controlled vehicle-return workflow, data-quality review, RAGcore-backed internal knowledge, n8n orchestration and read-only tools published through ITWorx MCP Hub. +The web application uses the premium responsive **Control Rail** interface: a compact +operations-first workspace with persisted readiness metrics, evidence-led exceptions, +review-before-commit return handling and mobile navigation designed down to 390 px. See +`docs/design/design-directions.md` and `docs/design/implementation-validation.md` for the +design decision and visual evidence. + All people, companies, vehicles, bookings and documents are synthetic. The workflows, validation, integrations, audit logging and access boundaries are intended to be real. ## Scope @@ -53,6 +59,7 @@ commands. - `backend/` — FastAPI/SQLAlchemy/Alembic API. - `frontend/` — React/TypeScript/Vite web app, including the Playwright end-to-end suite (`frontend/e2e/`). - `artifacts/evidence/` — final acceptance evidence (screenshots, architecture, `final-summary.md`). +- `artifacts/design-validation/` — baseline audit, Stitch direction references and implemented responsive captures. ## Quickstart @@ -78,7 +85,7 @@ All defaults are configurable via `.env` (see `.env.example`). ```bash make test # backend: pytest (66 tests) make lint # backend: ruff + mypy (strict, zero errors) -make e2e # frontend: Playwright end-to-end (12 tests, live stack required) +make e2e # frontend: Playwright end-to-end (18 tests, live stack required) ``` Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`). diff --git a/artifacts/design-validation/final-design-summary.md b/artifacts/design-validation/final-design-summary.md new file mode 100644 index 0000000..99ea0a9 --- /dev/null +++ b/artifacts/design-validation/final-design-summary.md @@ -0,0 +1,77 @@ +# MobilityOps premium UI evidence summary + +Date: 2026-08-02 +Branch: `design/mobilityops-premium-ui` +Baseline revision: `dfabb41582e302f45a3de826f85f531bf23dfc8b` +Final design revision: `b3946af4e0e14f2a3acecd212e9f0079e3028fca` +Review URL: `http://192.168.10.150:1236` + +## Outcome + +The working PoC was transformed into the Control Rail operational interface without +changing backend contracts or adding scope. All existing journeys remain functional; +return registration gained an evidence-based review boundary before commit. + +## Evidence index + +- Baseline audit: `docs/design/current-ux-audit.md` +- Three directions and decision: `docs/design/design-directions.md` +- Design tokens and component rules: `docs/design/design-system.md` +- Stitch resource IDs: `docs/design/stitch-manifest.md` +- Implemented visual validation: `docs/design/implementation-validation.md` +- Baseline captures: `artifacts/design-validation/current/` +- Stitch captures: `artifacts/design-validation/stitch/` +- Final responsive captures: `artifacts/design-validation/implementation/` + +## Major implementation changes + +- Responsive Control Rail shell with compact top bar, desktop rail, off-canvas menu and + labelled mobile bottom navigation. +- Live readiness band, filterable Attention queue, movement timeline, honest integration + pulse and persisted activity on the operations dashboard. +- Searchable fleet and booking registries; booking client pagination limits the DOM to 25 + operational rows; responsive tables retain field labels. +- Capture → review → result return workflow with calculated consequence preview and no + write request before confirmation. +- Match/conflict duplicate comparison, evidence-first knowledge, system-health cards and + expandable audit metadata. +- Inline SVG product mark, Feather-like line icon set, CSS control-centre illustration, + timeline/status motion and reduced-motion fallback; no image or motion dependency. + +## Validation + +| Gate | Result | +|---|---| +| Backend tests | 66 passed | +| Backend lint | ruff passed | +| Backend types | mypy: 0 issues in 44 files | +| Frontend types/build | passed; 59 modules; 238.66 kB JS and 36.54 kB CSS before gzip | +| Browser journeys | 18 passed locally | +| Horizontal overflow | none at 390/768/1280/1440 px | +| Accessibility | named landmarks, skip link, visible focus, text-plus-shape status, labelled mobile rows, reduced-motion support | +| Console/network | pending final deployed smoke test; local API/browser journeys are clean | + +All displayed operational counts remain derived from the existing persisted API data. +Synthetic-data labelling is persistent on login and authenticated surfaces. + +## Performance observations + +No runtime font, image or animation dependency was added. The application uses inline SVG +and CSS visuals, and the production bundle remains appropriate for this internal PoC. + +## Known limitations + +- Global search is present as a shell affordance but does not execute a cross-entity + query because no matching API contract exists; route-level search and filters are live. +- The MCP Hub state is correctly shown as not configured in the current PoC rather than + simulated as healthy. +- Live RAGcore and MCP Hub round trips remain subject to the existing environment limits + documented in `PROJECT_STATE.md`; their degradation behavior is unchanged. + +## Rollback + +The accepted baseline remains reachable at commit +`dfabb41582e302f45a3de826f85f531bf23dfc8b`. To roll back the review deployment without +rewriting git history, archive that revision, extract it over the application source on +Unraid while preserving `.env` and Docker volumes, and run +`docker compose -p mobilityops up -d --build`. Verify `/health` and port 1236 afterwards. diff --git a/artifacts/design-validation/implementation/desktop/audit-1440.png b/artifacts/design-validation/implementation/desktop/audit-1440.png new file mode 100644 index 0000000..d4cdf9a Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/audit-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/booking-return-1440.png b/artifacts/design-validation/implementation/desktop/booking-return-1440.png new file mode 100644 index 0000000..66d3ffa Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/booking-return-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/booking-return-review-1440.png b/artifacts/design-validation/implementation/desktop/booking-return-review-1440.png new file mode 100644 index 0000000..9fb6d8c Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/booking-return-review-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/dashboard-1280.png b/artifacts/design-validation/implementation/desktop/dashboard-1280.png new file mode 100644 index 0000000..986a1f0 Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/dashboard-1280.png differ diff --git a/artifacts/design-validation/implementation/desktop/dashboard-1440.png b/artifacts/design-validation/implementation/desktop/dashboard-1440.png new file mode 100644 index 0000000..c34e5fb Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/dashboard-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/dashboard-768.png b/artifacts/design-validation/implementation/desktop/dashboard-768.png new file mode 100644 index 0000000..65e9fbc Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/dashboard-768.png differ diff --git a/artifacts/design-validation/implementation/desktop/duplicate-review-1440.png b/artifacts/design-validation/implementation/desktop/duplicate-review-1440.png new file mode 100644 index 0000000..3a102ec Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/duplicate-review-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/integrations-1440.png b/artifacts/design-validation/implementation/desktop/integrations-1440.png new file mode 100644 index 0000000..144e83b Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/integrations-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/knowledge-1440.png b/artifacts/design-validation/implementation/desktop/knowledge-1440.png new file mode 100644 index 0000000..e25cdbd Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/knowledge-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/login-1440.png b/artifacts/design-validation/implementation/desktop/login-1440.png new file mode 100644 index 0000000..2d1baa6 Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/login-1440.png differ diff --git a/artifacts/design-validation/implementation/desktop/vehicles-1440.png b/artifacts/design-validation/implementation/desktop/vehicles-1440.png new file mode 100644 index 0000000..446cb9e Binary files /dev/null and b/artifacts/design-validation/implementation/desktop/vehicles-1440.png differ diff --git a/artifacts/design-validation/implementation/mobile/booking-return-390.png b/artifacts/design-validation/implementation/mobile/booking-return-390.png new file mode 100644 index 0000000..dbfdc1f Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/booking-return-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/booking-return-review-390.png b/artifacts/design-validation/implementation/mobile/booking-return-review-390.png new file mode 100644 index 0000000..6038b54 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/booking-return-review-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/dashboard-390.png b/artifacts/design-validation/implementation/mobile/dashboard-390.png new file mode 100644 index 0000000..21092e3 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/dashboard-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/duplicate-review-390.png b/artifacts/design-validation/implementation/mobile/duplicate-review-390.png new file mode 100644 index 0000000..a54d796 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/duplicate-review-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/knowledge-390.png b/artifacts/design-validation/implementation/mobile/knowledge-390.png new file mode 100644 index 0000000..6a54466 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/knowledge-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/login-390.png b/artifacts/design-validation/implementation/mobile/login-390.png new file mode 100644 index 0000000..1057752 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/login-390.png differ diff --git a/artifacts/design-validation/implementation/mobile/vehicles-390.png b/artifacts/design-validation/implementation/mobile/vehicles-390.png new file mode 100644 index 0000000..8c20ec0 Binary files /dev/null and b/artifacts/design-validation/implementation/mobile/vehicles-390.png differ diff --git a/docs/design/implementation-validation.md b/docs/design/implementation-validation.md new file mode 100644 index 0000000..df32118 --- /dev/null +++ b/docs/design/implementation-validation.md @@ -0,0 +1,60 @@ +# Premium UI implementation validation + +Date: 2026-08-02 +Branch: `design/mobilityops-premium-ui` + +## Implemented scope + +- New responsive Control Rail shell, icon system, product mark, top bar, desktop rail, + off-canvas navigation and labelled mobile bottom navigation. +- Redesigned login, dashboard, fleet, vehicle, bookings, booking return, data quality, + duplicate review, knowledge, integrations and audit surfaces. +- Return capture now has an explicit review step; no return API request is sent before + confirmation. The existing idempotency key and local-commit/outbox behavior remain. +- Booking rows are limited to 25 per client-side page; mobile tables keep explicit field + labels through `data-label` semantics. +- Loading, empty and error surfaces, focus treatment, reduced-motion handling and honest + integration states are shared system behaviors. + +## Visual evidence + +Desktop: + +![Implemented desktop login](../../artifacts/design-validation/implementation/desktop/login-1440.png) + +![Implemented desktop dashboard](../../artifacts/design-validation/implementation/desktop/dashboard-1440.png) + +![Implemented return capture](../../artifacts/design-validation/implementation/desktop/booking-return-1440.png) + +![Implemented return review](../../artifacts/design-validation/implementation/desktop/booking-return-review-1440.png) + +Mobile: + +![Implemented mobile login](../../artifacts/design-validation/implementation/mobile/login-390.png) + +![Implemented mobile dashboard](../../artifacts/design-validation/implementation/mobile/dashboard-390.png) + +![Implemented mobile duplicate review](../../artifacts/design-validation/implementation/mobile/duplicate-review-390.png) + +The complete capture set is in `artifacts/design-validation/implementation/`. + +## Responsive evidence + +Browser evaluation measured the document element after authenticated page render: + +| Width | Client width | Scroll width | Result | +|---:|---:|---:|---| +| 390 | 375 (vertical scrollbar present) | 375 | no horizontal overflow | +| 768 | 753 (vertical scrollbar present) | 753 | no horizontal overflow | +| 1280 | 1265 (vertical scrollbar present) | 1265 | no horizontal overflow | +| 1440 | 1425 (vertical scrollbar present) | 1425 | no horizontal overflow | + +The same widths are automated in `frontend/e2e/ui-redesign.spec.ts`. + +## Performance choices + +- No image runtime dependency and no animation library were added. +- Branding, navigation and workflow illustrations are inline SVG/CSS. +- Inter is used only when locally available; there is no blocking font request. +- The production build remains a single small PoC bundle (approximately 239 kB JS and + 37 kB CSS uncompressed at implementation time).