O.D.D. Companion — Build Recipe

Take a bare machine to a running copy of O.D.D. Companion — an offline-first companion app a caregiver uses to track a child's behavior over time: a daily behavior tracker (eight rated dimensions with trend averages), an escalation log (severity, triggers, what helped), a file cabinet, a calendar, a contacts book, and notes — all in one place, installable as a PWA and usable with no network. React 18 (Vite PWA) front end + a small FastAPI / SQLite back end that stores everything as opaque JSON and serves the built SPA.

Status: ✅ Verified 2026-07-31 — built from this clean clone on a laptop with a single docker compose up --build. The image builds (multi-stage: Node builds the front end → Python serves it), the container comes up healthy, seed_demo.py loaded the synthetic demo, and a real browser at http://localhost:8260 rendered the full dashboard — brand mark, "Ann T. Gonist's overview", the correct module counts (8 daily / 4 escalations / 4 documents / 3 notes / 5 contacts), recent escalations with severities, the computed 7-day averages, upcoming appointments, and key contacts — with 0 console errors. The 12-test backend suite passes in the shipped runtime. See demo-dashboard.png for the rendered result. The clean clone lives in clone/. All three tiers are covered — prebuilt container, build-from-source, and bare-metal; the prebuilt image tarball is ~279 MB (verified 2026-08-01).

Sensitive data — read this. The real app holds a real child's behavioral-health records. None of that is here. The clone ships zero data (no SQLite DB, no backups, no exported reports); the demo you see is entirely fictional — "Ann T. Gonist" (say it aloud), the providers, the school, and every phone number are invented by seed_demo.py. The app is a personal, single-caregiver tool with no authentication and no encryption at rest — it is not a HIPAA-compliant system. Run it for yourself, on your own machine or a private network.

What it is

Two pieces:

• Front end — a React 18 single-page app built by Vite into a PWA (installable, offline via a service worker). State lives in IndexedDB first, so the app works with no network; a small sync engine (sync.js) pushes local writes to the back end and, on boot, pulls the server's copy so a fresh device/browser hydrates from the server.
• Back end — a FastAPI app over SQLite exposing a tiny key-value API (GET/PUT/DELETE /api/store/{key}, plus /api/store/since/{ts} for incremental sync), a text extractor, a PDF/DOCX report exporter, and a static-file mount that serves the built SPA. It stores each of the app's seven records as opaque JSON — it never parses the domain model, which keeps the server trivial and the data format entirely owned by the front end.

There is no training and no dataset — it's an application, not a model. "Reproducing" it is building the front end and running the server.

Prerequisites

New machine? Install the base tools first — see ../SETUP.md. Then, per tier:

The prebuilt tarball and the from-source build reproduce the same single artifact by different routes — Tier 1 loads an image someone already built; Tier 2 builds that image in one command.

Tier 1 — Run the prebuilt container(s) (recommended)

Availability: the prebuilt image bundle is available on request — it is not published or linked anywhere. Ask Kevin for it, or build everything from source via Tier 2/3 below.

Skip the build entirely: load an image someone already built and start it. There's a single image, clone-odd-companion (the multi-stage build bakes in the Vite SPA and the FastAPI server).

# --- Produce the tarball once, on a machine that has built the image (see Tier 2): ---
docker save clone-odd-companion -o odd-companion-image.tar   # ~279 MB

# --- Consume it anywhere Docker runs (no build needed): ---
docker load -i odd-companion-image.tar          # loads clone-odd-companion
cd clone
docker compose up -d                            # no --build — the image is already loaded
# → http://localhost:8260
curl http://localhost:8260/api/health           # → {"ok":true}
python seed_demo.py                             # load the fictional "Ann T. Gonist" demo (optional)

Open http://localhost:8260 — an empty app on first run, or the demo if you seeded it. The SQLite DB persists in ./data/ (git-ignored); delete it to start clean.

The tarball is ~279 MB (verified 2026-08-01) and holds just the one clone-odd-companion image — there are no opt-in profiles or extra images to bundle separately.

Tier 2 — Build the image from source

cd clone
docker compose up -d --build      # stage 1 builds the SPA, stage 2 serves it
# → http://localhost:8260
curl http://localhost:8260/api/health          # → {"ok":true}
python seed_demo.py                             # load the fictional "Ann T. Gonist" demo (optional)

Open http://localhost:8260 — an empty app on first run, or the demo if you seeded it. The SQLite DB persists in ./data/ (git-ignored); delete it to start clean.

Tier 3 — Bare-metal (no Docker)

cd clone

# 1) build the front end  (outputs frontend/dist)
cd frontend
npm ci
npm run build

# 2) put the build where the server serves it, then run the server
cd ../backend
#   copy the built SPA into src/static  (any copy works; e.g.)
#   Windows PowerShell:  Copy-Item -Recurse ..\frontend\dist\* src\static\
#   bash:                mkdir -p src/static && cp -r ../frontend/dist/* src/static/
python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn src.main:app --host 0.0.0.0 --port 8260

Then seed if you like: python ../seed_demo.py http://localhost:8260.

(The server also runs fine with an empty src/static — the API works and the SPA fallback just returns a "frontend bundle not built" 404 until you build it. The DB path is configurable via the ODD_DB_PATH env var; it defaults to ./odd.db bare-metal, /data/odd.db in the container.)

Verify

curl http://localhost:8260/api/health
# → {"ok":true}

# after seeding, the server returns all seven records:
curl -s http://localhost:8260/api/store | python -m json.tool | head
# → {"odd-app:profile": {"value": {"childName": "Ann T. Gonist"}, "updated_at": ...}, ...}

Then open the page — the dashboard should show the child's name, the module counts, recent escalations, the 7-day behavior averages, upcoming appointments, and key contacts.

Run the backend tests. They exercise the DB layer and the store API (12 tests). Easiest in the shipped runtime (has everything installed):

docker compose cp ../backend/tests odd-companion:/app/tests    # or: docker cp
docker compose exec odd-companion sh -c "pip install -q pytest httpx && cd /app && python -m pytest tests -q"
# → 12 passed

Bare-metal equivalent (Python 3.11+): from backend/, pip install pytest httpx then pytest -q.

Notes & gotchas

• The server is the source of truth at boot; the browser is offline-first after that. A fresh browser (empty IndexedDB) pulls GET /api/store on load and renders it — which is exactly why seeding the server is enough to populate the UI. In-session, local edits go to IndexedDB immediately and flush to the server in the background.
• PDF export needs WeasyPrint's native libs. They're in the Docker image; on bare-metal Windows they usually aren't. WeasyPrint is lazy-imported inside the export path, so this never affects startup, the API, the UI, or DOCX export (pure-Python) — only POST /api/export with format=pdf would fail there.
• No auth, no multi-tenant. One app = one child's records. Point different ODD_DB_PATH values (or different containers/ports) at different databases if you need more than one.
• data/ and *.db are git-ignored. The clone intentionally carries no database; that's the whole point — you bring your own data (or the synthetic seed).
• Front-end bundle: Vite emits ~250 kB JS (~72 kB gzipped) + ~32 kB CSS and a 10-entry PWA precache — small enough to install and run fully offline.

Provenance (no training data, no GPU, no model)

O.D.D. Companion trains nothing and calls no external service — there are no datasets, no model weights, and no GPU anywhere in the build. It is a self-contained local application; the only network traffic is between the browser and its own back end on the same origin.

What was stripped from the personal version (de-identification + recipe minimalism)

• All real data — the live SQLite database, the backups/*.db snapshots, and any exported sample-report.pdf (which could carry the child's real name) → excluded entirely. The clone ships no data; the demo is synthetic (seed_demo.py).
• The child's initial in the brand mark — the sidebar glyph and the generated PWA icons showed the real child's first initial → changed to a neutral "A", and the icons were regenerated. The rest of the UI already reads the child's name from the (now-synthetic) profile record, so nothing else was hardcoded.
• Server-specific deploy tooling — deploy.sh, the scripts/ bootstrap, CLAUDE.md, and the docs/ folder (all describing the author's private home-server host) → removed. The clone adds a clean, self-contained Dockerfile + docker-compose.yml instead.
• A backup-to-server UI string that named the author's host → genericized.
• Git history (.git) and build artifacts (node_modules, dist, src/static) → excluded; the image rebuilds them from source.