# Overview

SimData is a hosted synthetic records sampler. It is seeded, constrained, and dictionary-backed for engineering, QA, and load tests.

## Core principles

- **Deterministic joins:** the same seed keeps related fields consistent.
- **High throughput:** Avro OCF streaming supports large data pipelines without buffering the complete result.
- **Zero real PII:** every record is synthetic. Never submit real customer or confidential personal data.

## Data flow

The primary client is the [developer CLI](cli.md). The website is where you
edit the dictionary and manage the wallet.

```bash
curl -fsSL https://simdata.interoperabilitypro.com/install.sh | sh
simhealth login
simhealth projects use default
simhealth sample person --count 1 --seed 1842
```

1. Install the CLI and run `simhealth login`.
2. Choose a dictionary project (`simhealth projects use ID`, or create one).
3. Edit that project's dictionary on the website at `/projects/{project_id}/dictionary`.
4. Sample with `simhealth sample person --count 1 --seed 1842`. The same seed replays the same draw.
5. Use the JSON or Avro output in test fixtures or data warehouses.

Projects keep unrelated domains isolated. For example, a pest-control project
and an online-learning project can have different records and vocabularies at
the same time. See [Dictionary projects](projects.md).

## HTTP API

Machine clients that already hold a project-bound API key call the same
sampler over HTTP. The CLI is a thin client of these routes.

| Method and path | Description | Auth |
| --- | --- | --- |
| `GET /v1/projects/{project_id}/random/{recordType}` | Sample coherent synthetic records | Bearer API key. Optional `x-customer-id` ledger override; invalid values return 400 `invalid customer id`. |
| `GET /v1/projects/{project_id}/catalog` | List dictionary definitions | Bearer API key |
| `GET /v1/stats/records` | Public generation counter | Public |

The unscoped `/v1/random/{recordType}` and `/v1/catalog` routes remain
available as compatibility routes for existing integrations. New integrations
should include the project ID explicitly.
