M29: polish recruiter engineering story

docs/16-portfolio-case-study.md

@@ -1,43 +1,47 @@
-# Portfolio case-study template
+# Fleet Ops — portfolio case study
 
-## Title
+## Product
 
-MobilityOps — connected operations for vehicle rental and service teams
-
-## One-sentence summary
-
-A working synthetic-data PoC that unifies vehicle and booking operations, automates vehicle returns, surfaces data-quality problems and exposes grounded internal knowledge through reusable RAG and MCP platforms.
+Fleet Ops is a working operations platform for a fictional Belgian mobility company. It unifies vehicle and booking work, makes data defects resolvable, automates post-return follow-up and turns internal procedures into cited answers.
 
 ## Problem
 
-Operational information was modelled as fragmented across booking, vehicle and procedure sources, causing manual checks, inconsistent states and slow access to instructions.
+Rental operations often span booking records, vehicle state, inspections and separate procedure documents. The difficult part is not another dashboard; it is preserving one trustworthy state while people, automation and AI consume the same workflow.
 
-## Approach
+## Engineering approach
 
-- MobilityOps owns canonical operational data and business rules.
-- A transactional return workflow persists inspections, derives status and queues post-commit orchestration.
-- Explainable rules detect duplicates, mileage regressions, overlaps, missing fields and status conflicts.
-- RAGcore provides source-grounded procedure answers.
-- ITWorx MCP Hub exposes narrowly scoped read-only AI tools.
-- n8n orchestrates secondary processing without becoming the business-rule engine.
+- Keep business invariants in a FastAPI/SQLAlchemy domain layer backed by PostgreSQL constraints and row locks.
+- Commit vehicle returns, audit evidence and an outbox message in one transaction.
+- Let the existing central n8n execute secondary work asynchronously, with leases, retries and authenticated callbacks.
+- Detect five classes of data-quality issue and require bounded, explicit human resolution.
+- Integrate RAGcore through a provider adapter that refuses unsupported answers and preserves citation provenance.
+- Publish only four narrow read-only tools through ITWorx MCP Hub; never give external AI systems database access.
+- Expose correlation-based evidence in the product so architecture claims can be inspected, not merely read in a diagram.
 
-## Demonstrable results
+## Demonstrable result
 
-Use only facts actually measured in the final build, such as:
+- 50 vehicles, 180 customers and 254 bookings in a deterministic synthetic dataset;
+- one complete controlled return workflow and five persisted quality-rule types;
+- 11 authoritative Dutch procedure sources with localized grounded retrieval;
+- four tenant-bound, service-authenticated read-only MCP tools;
+- trilingual responsive UI, server-backed roles, global search, privacy controls and audit;
+- degraded-mode coverage for n8n and RAGcore, production health/metrics and verified backups;
+- complete backend and browser acceptance recorded in `artifacts/evidence/final-summary.md`.
 
-- 50 deterministic synthetic vehicles and 245 bookings;
-- five automated data-quality rule types;
-- one end-to-end return workflow;
-- ten versioned source procedures;
-- four read-only MCP tools;
-- tested degraded modes for RAGcore and n8n.
+## Product decisions worth discussing
 
-Do not claim real customer adoption, production use or percentage time savings.
+**Why an outbox?** A return must remain committed when n8n is unavailable. Persisting the event in the same database transaction closes the gap between business success and later orchestration.
+
+**Why no generative fallback?** A fluent procedure answer without evidence is worse than a clear unavailable state. Knowledge answers require cited provider evidence.
+
+**Why read-only MCP tools?** Recruiter demos should show credible AI integration without granting autonomous mutation rights. Operational writes remain explicit product workflows with authorization, validation and audit.
+
+**Why synthetic but production-shaped data?** The public demo can remain safely open while still exercising realistic state transitions, failure recovery and resettable scenarios.
 
 ## Stack
 
-React, TypeScript, FastAPI, PostgreSQL, n8n, RAGcore, ITWorx MCP Hub, Docker Compose and Playwright.
+React, TypeScript, Vite, FastAPI, SQLAlchemy 2, PostgreSQL, Alembic, n8n, RAGcore, ITWorx MCP Hub, Docker Compose, Prometheus, Grafana and Playwright.
 
-## Demo disclosure
+## Honest boundary
 
-All data and the represented company are fictitious. The software behaviour, integration contracts, audit trail and validation are implemented as a real proof of concept.
+Fleet Ops is a completed locked PoC, not claimed customer adoption or a general ERP. Accounting, payments, public reservations, CRM, inventory, HR and autonomous write agents are intentionally out of scope. A real personal-data rollout would additionally require the adopting organisation's identity provider, retention approvals, secrets lifecycle, alert ownership and disaster-recovery process.