Skip to content
All workCase study 01 / 04

P—012026Source available

RetailOps Intelligence

An operations inbox for online stores: tested rules find the problems, an AI copilot explains them.

Role
Solo developer — product discovery, domain design, full stack, AI, testing, Docker and CI
Type
Full-stack B2B SaaS · Personal project
Focus
Domain modelling and grounded AI
Year
2026
RetailOps Intelligence overview: KPI tiles, a priority-ranked attention list and value at risk per category
fig. P01 — RetailOps Intelligence overview: KPI tiles, a priority-ranked attention list and value at risk per category

§ 01Overview

Small online shops run on exports and spreadsheets, so problems surface late: a SKU sold more times than it exists, a paid order past its handling deadline, a cancelled order that was never refunded.

RetailOps Intelligence imports the store's data, runs nine rules that each produce structured evidence, and turns every finding into one exception with a transparent 0–100 priority, an owner, a due date and a lifecycle. When someone marks it resolved, the next evaluation checks the data again and reopens it if the problem is still there.

§ 02Problem & solution

Problem

An operations tool is only useful if its numbers can be trusted: stock must not be double-counted when imports arrive late, an order's payment and fulfillment must not be collapsed into one status, and an AI assistant must never invent a fact or change data.

Solution

Keep every business calculation deterministic and tested, and let AI explain on top of it. A modular FastAPI monolith owns the domain rules, an append-only inventory ledger and the exception engine; the copilot only reads through allowlisted, permission-checked tools, and its answers carry references to the records they use.

§ 03My role

Solo developer — product discovery, domain design, full stack, AI, testing, Docker and CI. What I personally implemented:

  1. 01Wrote the product discovery, business workflows, domain contracts (state machines, business rules, exception catalog, priority model) and 13 architecture decision records before building.
  2. 02Modelled orders with three independent status axes (lifecycle, payment, fulfillment) and an import sync that only moves an order to a reachable state.
  3. 03Built an append-only inventory ledger with reservations, available = on hand − reserved, and stock counts applied as of the time they were taken so a late import cannot double-count shipments.
  4. 04Implemented the exception engine: nine pure rules, deduplication, auto-resolve, supersede, verification of manual fixes and a per-store lock for scheduled, manual and import-triggered evaluations.
  5. 05Built the CSV import pipeline: validation with issue codes, a preview of expected changes, strict or valid-rows-only apply in one transaction, idempotency and a formula-safe issues export.
  6. 06Built the Next.js app (overview, exception inbox and investigation, orders, inventory, imports, copilot, admin) and an AI copilot with a deterministic fallback, so it works without an LLM key; free-tier Gemini or any OpenAI-compatible model can be plugged in.
  7. 07Covered it with 887 backend tests against real PostgreSQL, 268 component tests, and a Playwright suite (the 12-step operations journey, a 375 px pass and axe WCAG 2.1 AA scans) that runs in GitHub Actions against the Docker Compose stack.

§ 04Architecture

fig. A01 — Architecture
  1. L1Client
    • Next.js App Router
    • TanStack Query
    • Generated API types (OpenAPI)
    same-origin /api calls
  2. L2API
    • FastAPI modular monolith
    • Session auth · CSRF · role permissions
    • Copilot tool registry
    domain services per module
  3. L3Domain
    • Order state machine
    • Inventory ledger & reservations
    • Exception engine (9 rules)
    evaluations write exceptions
  4. L4Async
    • Scheduled evaluation worker
    • Import-triggered evaluation
    read-only tools for the copilot
  5. L5Data & AI
    • PostgreSQL 16 + Alembic
    • Gemini / OpenAI-compatible (free tier)
    • Deterministic fallback
  • Business facts are computed by tested rules; the AI only explains and drafts, and a person saves every note.
  • Every store-scoped query is filtered by store, and another tenant's data answers 404.

§ 05Technology stack

Backend
Python 3.12FastAPIPydantic v2SQLAlchemy 2Alembic
Frontend
Next.jsReactTypeScriptTailwind CSSshadcn/uiTanStack Query
Data
PostgreSQL 16OpenAPI-generated TypeScript contracts
AI
Gemini (free tier)OpenAI-compatible providersDeterministic fallback engine
Quality & delivery
pytestmypy --strictVitestPlaywright + axe-coreDocker ComposeGitHub Actions

§ 06Key features

  • F01

    Exception inbox

    Triage views, filters, a transparent priority score and the full lifecycle: acknowledge, assign, resolve, dismiss, reopen.

  • F02

    Verified fixes

    A manual resolution waits for fresh data; if the condition is still there, the exception reopens with the reason.

  • F03

    Safe CSV imports

    Every row validated, a preview of the changes, atomic apply and a downloadable list of issues.

  • F04

    Inventory you can audit

    Append-only movement ledger, reservations for paid orders, stock health per product.

  • F05

    Grounded copilot

    Answers split into facts, metrics, estimates and recommendations, each linked to its records.

  • F06

    Roles and audit

    Owner, manager, staff, analyst and read-only viewer roles, enforced in the API and recorded in an audit log.

§ 07Engineering challenges

C1

Cancelled, but still paid

Problem

A single order status cannot say that a cancelled order still holds the customer's money, or that a refunded order was already delivered.

Approach

Three status axes with an explicit compatibility matrix and transition graph; a dedicated rule raises "refund pending" when a cancelled order is still paid.

C2

Was it actually fixed?

Problem

People mark issues resolved before the data proves it, and a correct fix can look unresolved until the next export arrives.

Approach

Manual resolutions stay "awaiting verification"; the engine reopens them only if the condition persists after fresh data is imported or 24 hours pass.

C3

An AI that cannot make things up

Problem

A copilot over business data must not invent numbers, leak another store's data or follow instructions hidden in imported text.

Approach

Eleven allowlisted read-only tools with permission and store checks, references validated against the tool results, imported text treated as data, and a rule-based engine that answers when no model is available.

§ 08Screens

Operations overview with KPIs and the attention list
S1 — Overview of the fictional demo store, signed in as the read-only demo viewer
Exception page with the priority breakdown and the recommended action
S2 — One exception: why it ranks P1 (score breakdown), the rule's recommended action and the lifecycle actions
Copilot answer split into facts and metrics, each with a record reference
S3 — Copilot answer: labelled facts and metrics, each linked to the record it rests on
Exceptions inbox with triage views, filters and search
S4 — The exceptions inbox with triage views and filters
Next case study / P—02Meet.AIVideo meetings where an AI agent joins the call, then writes the notes.