# Building on 1health — an LLM's guide

> The single entry point for an AI agent tasked with turning a disconnected
> front-end prototype into a working, 1health-compliant application.
> **1health is the ONLY backend.** Read "Start here" before writing any code.

- guide_version: 0.5.0 (draft — setup + a ~125-recipe library across 14 categories + a QA standard; key behaviors confirmed against the demo environment)
- raw_base: https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/
- repo: https://github.com/Tachin-ai-Corporation/1health-app-guide  (clone this for local grep)
- api_docs (tactical, live, maintained by 1health): https://agents.1health.io/public/prod/llms.txt

## If you are an AI agent — your task, start here
You were handed this URL to build a real application on **1health**. Do this now:
1. **Confirm you have three inputs. If any is missing, ASK THE USER for it before continuing:**
   (a) their front-end prototype (code/repo), (b) 1health **demo** access (a login or launch),
   (c) **the user's own 1health app credentials** in **server** env — `APP_ID_DEMO` and
   `ONEHEALTH_SECRET_KEY_DEMO` (the app's decrypt key). The user registers their **own** 1health app
   and provisions these themselves; they are never shipped with this guide and never touch the browser.
   **For QA**, also ask for (d): API keys for a System Admin, a Manager, and an Employee user in a
   demo **QA org**, which the user puts in `.env.local` themselves. These keys are for local and
   dev/stage builds only, never production.
2. **Read these five, in order** (each is short):
   - https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/rules-of-the-road.md
   - https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/auth-and-launch.md
   - https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/scaffold.md
   - https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/prototype-to-app.md
   - https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/qa-and-local-testing.md

   (Faster if your tools allow it: `git clone https://github.com/Tachin-ai-Corporation/1health-app-guide` and read/grep it locally.)
3. **Build the app, screen by screen.** For each feature, find its recipe in
   https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/recipes/INDEX.md ,
   then confirm the exact request/response shape at `agents.1health.io` **before** writing each call.
4. **Obey the Definition of done** (end of this file) and avoid the traps in
   https://raw.githubusercontent.com/Tachin-ai-Corporation/1health-app-guide/main/setup/anti-patterns.md .

## What you need (the user supplies these — they are NOT part of this guide)
- **A front-end-only prototype** — screens and mock data, no backend wired up.
- **The user's own 1health app.** Each customer registers their own app in 1health and obtains its
  **App ID** and **secret / decrypt key** (the "config/decrypt key"), then sets them as **server**
  env vars — `APP_ID_DEMO` + `ONEHEALTH_SECRET_KEY_DEMO` (and `_PROD` for production). **This guide
  ships no credentials; every customer uses their own app.** If the user hasn't registered one yet,
  they do that first — see [setup/auth-and-launch.md](setup/auth-and-launch.md) § "Provision your own app".
- **A 1health demo login** — the user's own account to authenticate as in the demo environment.
- **QA keys (for testing).** The user creates a demo QA org with one user per role (System Admin,
  Manager, Employee) and an API key for each, and puts the keys in `.env.local`. With them, a local
  or dev/stage build can sign in as each role. They are **never** set on the production deployment.
  See [setup/qa-and-local-testing.md](setup/qa-and-local-testing.md).

Your job: wire that prototype to 1health, following the rules below. Add no other backend.

## Prime directives (non-negotiable)
1. **1health is the only backend.** No external database, ORM, or third-party API for app data.
2. **Exactly one server-side route: `/api/token`.** It decrypts the 1health launch payload with
   the secret key and exchanges it for OAuth tokens. *Every other API call is client-side.*
3. **All client calls go through `authFetch`** (Bearer token + automatic refresh) — never raw `fetch`.
4. **Secrets stay server-side.** `ONEHEALTH_SECRET_KEY_*` live in env vars, never shipped to the browser.
   QA keys (`ONEHEALTH_QA_KEY_*`) live only in `.env.local` or on a dev/stage deployment, never on production.
5. **App-specific data lives in `customData`**, namespaced under `appData.<appId>`.

## How to use this guide
- **Preferred:** `git clone` the repo and grep locally — you get the whole tree at once.
- **Or cURL** any file at `raw_base` + `<path>` (e.g. `raw_base` + `setup/rules-of-the-road.md`).
- **Flow:** read *Start here* → open the *Recipe Index* → for each feature, follow the recipe's
  links into the **live API docs** for exact request/response shapes. Never guess a payload shape;
  confirm it in the per-route `agents.md`.
- **Primary vs fallback:** where 1health offers two ways to do one job, the recipe says which is the
  primary and exactly when to switch. Use the primary unless its switch condition applies.
- **⚠ banner:** a few routes are supported for third-party apps but not yet in the published API
  docs; recipes flag them. There's no `agents.md` to confirm against, so test them on demo first.

## Start here — the WHAT (read in order)
- [setup/rules-of-the-road.md](setup/rules-of-the-road.md) — the data model + constraints, one page. **READ FIRST.**
- [setup/auth-and-launch.md](setup/auth-and-launch.md) — launch payload → token → `authFetch`; the one server route.
- [setup/scaffold.md](setup/scaffold.md) — start from the app template; required env vars; the file map.
- [setup/prototype-to-app.md](setup/prototype-to-app.md) — the playbook: prototype screens → 1health features.
- [setup/conventions.md](setup/conventions.md) — the house rules: server routes, comms, SWR, customData, identity.
- [setup/anti-patterns.md](setup/anti-patterns.md) — what NOT to do (non-1health datastores, hardcoded ids, …).
- [setup/qa-and-local-testing.md](setup/qa-and-local-testing.md) — sign a local or dev/stage build in as each role; the QA standard and checklist.

## Recipes — the HOW (abstract, reusable patterns)
- [recipes/INDEX.md](recipes/INDEX.md) — the full, scannable index (~125 recipes, 14 categories). **Navigate from here.**

Foundations (read these first):
- [recipes/query-the-data-graph.md](recipes/query-the-data-graph.md) — read entities + relationships (`/api/v2/query`).
- [recipes/read-write-custom-data.md](recipes/read-write-custom-data.md) — app-specific fields via `customData`.
- [recipes/schema-discovery.md](recipes/schema-discovery.md) — discover types/attributes/relationships at runtime.
- [recipes/grid-list-views.md](recipes/grid-list-views.md) — server-defined list views (`/v3/health/grid/*`).
- [recipes/api-versions-and-layers.md](recipes/api-versions-and-layers.md) — v1 basement, v2 standard wrappers, v3 wrappers or fresh APIs.
- [recipes/choose-a-read-path.md](recipes/choose-a-read-path.md) — which read mechanism fits which job.
- [recipes/sentinel-values-not-null.md](recipes/sentinel-values-not-null.md) — unset values are `"n/a"` / `-1`, not `null`; `/query` booleans are `"true_"`/`"false_"`.

Index categories: reading · writing/extending · workflows (journeys/steps/campaigns) · files & comments ·
sharing & partners · org/tenant onboarding · patients, orders & clinical records ·
population health (cohorts & care gaps — the command center) · external integrations ·
communications · agreements/BAA · app architecture & security · auth & session. Recipes marked **adv**
are advanced/guardrailed — read [setup/conventions.md](setup/conventions.md) first.

## API reference — the TACTICAL (live; we bridge, we do not duplicate)
- [api/README.md](api/README.md) — how to pull any route's exact contract on demand.
- Upstream manifest (all 474 routes): https://agents.1health.io/public/prod/api/manifest.md
- Per route: `https://agents.1health.io/public/prod/api/<version>/<path>/agents.md` (many also have `examples.md`)

## Definition of done
- No backend but 1health. Only `/api/token` is server-side. All reads/writes go through `authFetch`.
- No hardcoded step-field GUIDs (resolve by `label`). `customData` namespaced under `appData.<appId>`.
- Any ⚠-bannered (supported-but-undocumented) route you use has been exercised against demo.
- Runs against the DEMO environment with the provided credentials.
- Passes the QA checklist as **System Admin, Manager, and Employee** against demo
  ([setup/qa-and-local-testing.md](setup/qa-and-local-testing.md)).
- No QA key is set on the production deployment.