§ 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:
- 01Wrote the product discovery, business workflows, domain contracts (state machines, business rules, exception catalog, priority model) and 13 architecture decision records before building.
- 02Modelled orders with three independent status axes (lifecycle, payment, fulfillment) and an import sync that only moves an order to a reachable state.
- 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.
- 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.
- 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.
- 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.
- 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
- L1Client
- Next.js App Router
- TanStack Query
- Generated API types (OpenAPI)
same-origin /api calls - L2API
- FastAPI modular monolith
- Session auth · CSRF · role permissions
- Copilot tool registry
domain services per module - L3Domain
- Order state machine
- Inventory ledger & reservations
- Exception engine (9 rules)
evaluations write exceptions - L4Async
- Scheduled evaluation worker
- Import-triggered evaluation
read-only tools for the copilot - 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
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.
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.
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




§ 09Links
- GitHub (opens in a new tab)github.com/tinhne/retailops-intelligence
No hosted demo yet. One docker compose command runs the whole stack with a fictional demo store; the repository also ships ten fictional Vietnamese sample shops.