48 lines
3.3 KiB
Markdown
48 lines
3.3 KiB
Markdown
# 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.
|