# Dictionary projects

## What is a project?

A project is an independent synthetic-data workspace. It contains one complete
dictionary:

- **Sets** — allowed values such as service types, course levels, or regions.
- **Records** — the shapes of generated objects.
- **Distributions** — weighted or numeric sampling rules.
- **Sequences** — generated identifiers and other counters.

Projects keep unrelated domains from overwriting one another. For example, a
Pest Control project can define `serviceCall`, while a Learning Center project
can define `course`. Both dictionaries can exist under the same account at the
same time.

Projects are currently private to the account that creates them. Sharing and
multi-user collaboration are not part of the current project model.

## Selecting and editing a project

After signing in:

1. Open **Projects** to see your project table.
2. Use the **Project** selector in the top navigation to choose the active
   project.
3. Open **Dictionary** and edit Sets, Records, Distributions, or Sequences.

The active project is reflected in the URL:

```text
/projects/{project_id}/dictionary/sets
/projects/{project_id}/dictionary/records
/projects/{project_id}/settings
```

This makes a project workspace bookmarkable and prevents switching pages from
silently changing dictionary context. The project selector also updates the
navigation links for Docs and API Keys.

## When to create a project

Create a separate project when the domain, record vocabulary, or generation
rules are substantially different. Good examples include:

- `Pest Control` — service calls, technicians, properties, treatments.
- `Learning Center` — students, courses, enrollments, instructors.
- `QA Sandbox` — temporary fixtures and experiments.

Keep related variations in one project when they share definitions and
references. A project should be a coherent dictionary, not a folder for one
individual Set.

## Sampling is project-scoped

Pass `--project` (or run `simhealth projects use ID`) so the CLI samples the
right dictionary:

```sh
simhealth --project pest-control sample serviceCall --count 3
simhealth --project learning-center sample course --count 3
```

API keys stay project-bound for HTTP clients. Create a key while the desired
project is active; the key is permanently bound to that project, and a
`{project_id}` that does not match returns `403`. The original `/v1/random`
and `/v1/catalog` paths remain available for existing clients.

The API key list under **Settings** shows only keys for the active project.
Existing keys created before projects were introduced remain bound to the
default project.

## Isolation rules

- Editing one project never changes another project's dictionary.
- A project-bound API key cannot generate from another project.
- Catalog reads and writes use the project selected by the key or web URL.
- Dictionary versions and generated artifacts are stored under the project
  namespace.
- Project deletion removes its dictionary and project-bound API keys.

## Deleting a project

The **Default dictionary** project is protected and cannot be deleted. For
other projects, use the **Delete** action in the Projects table. Deletion is
destructive: it removes the project's dictionary data and its API keys. Create
a new project instead if you only want a clean experiment while preserving the
old data.
