# Fleet Ops — portfolio case study

## Product

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

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.

## Engineering approach

- 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 result

- 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`.

## Product decisions worth discussing

**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, Vite, FastAPI, SQLAlchemy 2, PostgreSQL, Alembic, n8n, RAGcore, ITWorx MCP Hub, Docker Compose, Prometheus, Grafana and Playwright.

## Honest boundary

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.