Environment & reference

This is the shared reference for both phases: how to get the app in front of you, the API surface, and what the app already provides for you to build on.

Accessing the app

Hosted demo

A hosted instance is available at:

• App: https://app.vendomo.redis-field-engineering.com
• API docs (Swagger): https://app.vendomo.redis-field-engineering.com/docs

The full source is on GitHub: https://github.com/slorello89/vendomo

Running locally

Running locally is preferred for the AI-assisted phase so your AI tool has real file access. Clone the repo and bring the whole stack up with one command — docker compose up:

git clone https://github.com/slorello89/vendomo.git
cd vendomo
cp .env.example .env        # optional — sensible defaults are baked in
docker compose up --build

That single command starts everything: Postgres, Redis, the FastAPI backend, the revenue worker, and the React frontend. Give it a minute on the first run (it builds the images and seeds the fleet), then open:

• App (React UI): http://localhost:5173
• API docs (Swagger): http://localhost:8000/docs

On first boot the API seeds the fleet with ~1,000 vending machines scattered across ~30 US metros, plus historical service logs. Data persists in a Postgres volume across restarts (the seed only runs when the table is empty).

Services & ports

Service	Port	Notes
frontend	5173	Vite dev server (proxies /api → backend)
backend	8000	FastAPI; /docs for Swagger
postgres	5432	user / pass / db all vendomo
redis	6379	cache + streams
worker	—	pushes simulated sales to a Redis stream

API reference

Base URL: http://localhost:8000

Method	Path	Description
GET	/api/health	Liveness check
GET	/api/machines	Paginated list (limit/offset/status/region/q)
GET	/api/machines/map	Lightweight markers for the map (cached)
GET	/api/machines/{id}	Machine detail + stocked products + service logs
GET	/api/products	Canonical product catalog
POST	/api/machines	Create a single machine
POST	/api/machines/bulk	Create many machines (JSON array)
GET	/api/service/logs	Service log feed (machine_id/type)
POST	/api/service/logs	Record a service visit
GET	/api/stats	Counts by status / region, totals

What's provided (scaffolding)

The following already exist in the app. You'll build on them in Phase 2 — refer back here as needed.

Machine metadata

Machines have latitude / longitude (floats), region (US state code), status (operational / needs_service / offline), city, address, and a free-text location_description (e.g. "In the back by the pinball machines").

Machine inventory

Every machine carries the products it stocks, returned on the machine detail endpoint (GET /api/machines/{id}) and shown in the detail panel. Each entry is a { "product": <name>, "quantity": <int> } — and quantity == 0 means sold out:

"products": [{ "product": "Cola", "quantity": 7 }, { "product": "Pretzels", "quantity": 0 }]

Canonical product catalog

GET /api/products returns the canonical product vocabulary as a sorted list of strings (~27 items). The catalog uses canonical names — for example the catalog entry is "Cola", not "Coke".

Revenue stream

The worker service simulates sales. Each sale is appended to the Redis stream vendomo:revenue:events. Entries have these fields (all stored as strings, as Redis streams always store field values as strings):

Field	Example	Notes
machine_id	"4f1c…uuid"	UUID of a real machine
region	"CA"	US state code
item	"Energy Drink"	product sold
amount	"3.50"	USD as a string — parse to a number to sum
ts	"1719772800123"	epoch milliseconds as a string

Other facts about the stream:

• It's appended with a MAXLEN cap (approximate), so it's trimmed — only the most recent entries are retained; the full history is not available.
• Throughput is roughly 8 events/sec.
• Newly added machines start selling within about a minute, without a restart.

You can inspect the live stream directly:

docker compose exec redis redis-cli XINFO STREAM vendomo:revenue:events
docker compose exec redis redis-cli XREVRANGE vendomo:revenue:events + - COUNT 5

Redis 8

Redis 8 is the cache/bus. The query engine (FT.*), GEO, JSON, and vector are built into core — no extra modules to install.

LLM configuration

Natural-language features can use Anthropic Claude. An API key and model are configured via environment: ANTHROPIC_API_KEY (and optionally ANTHROPIC_MODEL, default claude-haiku-4-5-20251001) are read into the backend settings, and the anthropic package is already installed.