Getting started

This is the unified documentation site for the Cafébec vending-machine operations platform. It combines prose guides with a live API reference generated from the backend's OpenAPI spec at build time — the container serving this site has no runtime dependency on the API or the database.

What lives here

Prose guides cover the business domain, architecture, and operator workflows. These pages are MDX under apps/docs/content/docs/ and rebuild whenever that directory changes.

API reference lives under API → Api and is rendered from api.cafebec.ca/openapi.json. Each endpoint has its own page; search surfaces operations alongside prose.

Search is powered by Fumadocs's built-in Orama index, prerendered to /api/search as static JSON. Open it with ⌘K / Ctrl+K.

Phase 1 — what ships today

• Clients, Contacts, Locations, Machines — full CRUD via the operator console or API, soft-delete everywhere.
• Agreements — time-bounded commission or invoicing terms per machine, with a GiST exclusion constraint preventing overlaps in the same direction.
• Settlement math — pure, tested packages/settlement-engine. Report UI lands in Phase 2; the math is ready.
• Vendsoft CSV imports — dedicated guide. Dry-run first, resolve unmatched clients/machines, commit.
• Auth — dedicated guide. Better Auth for humans, vnd_ API keys for agents, one Actor model on the server.
• MCP server — search_clients + get_client tools over HTTP, authenticated with a system API key.

Next steps

• Operators start at app.cafebec.ca and the Authentication guide.
• Integrators dig into the API reference.
• Agent builders — the MCP server exposes two read tools today; writes land as the REST surface expands.
• Contributors — the Architecture page maps where each piece lives.