Skip to content

Reference App — Overview

The standards ship a runnable sample of the whole blueprint: the vet veterinary-clinic application. It exists to be copied — it is the reference for how a real domain sits on the architecture, and the code an agent pulls through the MCP tools (get_app_template, get_app_component).

One sample, two templates

The server sample lives at standards/src/templates/app/ (FastAPI + openapi-first + mongo-ops + hexa). The client sample lives at standards/src/templates/client/ (Vite + MUI + @aetoskia/react-openapi + @aetoskia/react-auth). Together they are the full-stack reference.

The domain at a glance

Aggregate What it demonstrates
parents The simplest CRUD slice (no foreign keys) — copy this first
pets Embedded list-of-refs (parents[]), file upload, enum fields
treatments Plain resource with pricing fields
vets Plain resource; target of prefetch FKs
appointments Single FKs (pet, vet, treatment) expanded on read, filtered list
jobs The worker's queue — durable status machine

The pipeline axis ships one worked family, appointment_reminder, plus the reusable pipelines/shared/ scaffold and a worker.py that dispatches jobs by job.kind.

Run it

1
2
3
4
5
6
7
cp -r <docs>/standards/src/templates/app apps/vet-sample
cd apps/vet-sample
pip install -e ".[dev]"

uvicorn main:app --reload     # API on :8020 (memory backend, zero services)
python worker.py              # background worker (polls jobs)
python -m scripts.seed        # optional: seed demo data (mongo backend)

The default REPO_BACKEND=memory means the API boots with no external services — repositories are process-local dictionaries. Switch to REPO_BACKEND=mongo for persistence (see .env.example).

The client pairs with it:

1
2
3
4
5
6
cp -r <docs>/standards/src/templates/client apps/vet-sample-client
cd apps/vet-sample-client
echo "VITE_API_BASE_URL=http://localhost:8020" > .env.local
echo "VITE_AUTH_BASE_URL=http://localhost:8020" >> .env.local
npm install
npm run dev                   # Vite dev server

Auth

The server ships with the bearerAuth security scheme declared ({AUTH_SERVER} introspection). Without a reachable auth-server the API answers 401 on resource routes; /health stays public. For a local no-auth demo, remove the security block from openapi.yaml and the global security entry — see Auth Integration.

Next