> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshipd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> The shipd mental model in five minutes: organizations, projects, environments, flags, snapshots, and local evaluation.

## Overview

This page connects the pieces you'll see across the docs. If you remember one thing: **you define flags in code, you control them in the dashboard, and your app evaluates them in memory.**

## Where things live

```text theme={null}
Organization            fieldkit
└── Project             web-app          ← flags are defined here, once
    ├── Environment     development      ← each environment has its own
    ├── Environment     staging            enabled state, rules, fallthrough,
    └── Environment     production         SDK keys, and snapshot
            └── Snapshot  v42            ← everything the SDK needs to evaluate
```

| Thing | What it is | Scope |
| - | - | - |
| **Organization** | Your company account. Members, roles, billing, SSO. | Top level |
| **Project** | One product or codebase. Owns one flag config (TypeScript, Go, or JSON). | Organization |
| **Environment** | A deployment target such as `development`, `staging`, or `production`. At most one is marked production. | Project |
| **Flag definition** | Key, type, variants, description, tags. Written in TypeScript or Go, or directly in JSON. | Project (same in every environment) |
| **Flag state** | Enabled or not, targeting rules, fallthrough. Edited in the dashboard. | Environment |
| **Snapshot** | A JSON document with every flag's state for one environment. | Environment |
| **SDK key** | Lets an app download one environment's snapshot. | Environment |

## How a flag gets to your app

Go uses the same flow with `shipd.config.go`, read directly by the CLI. Version-1 JSON configs are also supported. See [Go definitions](/config-as-code/define-flags#go-definitions).

```text theme={null}
 shipd.config.ts          you write flag definitions
       │
       ▼
   shipd push             the CLI syncs definitions
       │
       ▼
 Control plane            stores definitions + state (dashboard edits land here too)
       │  publishes on every change
       ▼
   Snapshot               one JSON document per environment
       │
       ▼
 Edge (CDN)               serves the snapshot to SDKs, notifies them of changes
       │
       ▼
 SDK in your app          keeps the snapshot in memory
       │
       ▼
 shipd.isEnabled(…)       evaluated locally — no network call
```

1. **Define.** TypeScript or Go definitions declare which flags exist and their types; The CLI reads Go definitions directly. It's reviewed in pull requests like any other code.
2. **Sync.** `shipd push` compares the file with shipd and applies the difference. It also writes TypeScript types or Go accessors for your flags.
3. **Control.** In the dashboard you decide what each flag serves per environment: on or off, rules for specific users, percentage rollouts.
4. **Publish.** Every change produces a new snapshot version for the affected environment.
5. **Deliver.** The SDK downloads the snapshot at startup, then refreshes it every 30 seconds, or on a WebSocket notification in TypeScript streaming clients.
6. **Evaluate.** TypeScript's `isEnabled`, `getVariant`, `getNumber`, and `getJson`, and Go's `IsEnabled`, `GetVariant`, `GetNumber`, and `GetJSON`, read the in-memory snapshot and never throw. See [SDK benchmarks](/reference/benchmarks) for measured boolean evaluation latency and throughput.

## How a value is chosen

For each check, the SDK walks this list and stops at the first match:

```text theme={null}
No snapshot yet?            → your code's defaults[key]
Flag not in snapshot?       → your code's defaults[key]
Flag disabled here?         → the snapshot's default, which shipd derives from the fallthrough; rules are skipped
Rule matches the context?   → that rule's serve  (rules are checked top to bottom)
Otherwise                   → the fallthrough
```

The **fallthrough** is what an environment serves when no rule matches. `shipd push` sets the fallthrough of the environment you push to from the flag's `default` in your flag definitions, and resets it if the two differ. Other environments' fallthroughs are only changed in the dashboard.

> [!WARNING]
>
> Disabling a flag does not turn it off. It skips targeting rules and serves the fallthrough. To turn a feature off, set **Fallthrough** to `false`. See [Turn a feature off immediately](/flags/kill-switch).

The **evaluation context** is who is asking: a `userId` plus `attributes` such as `plan` or `country`. Rules match on it. Percentage rollouts hash the flag key and `userId`, so the same user always gets the same answer.

```ts TypeScript theme={null}
shipd.isEnabled("new-checkout", {
  userId: "usr_8f2k19",
  attributes: { plan: "pro", country: "US" },
});
```

```go Go theme={null}
client.IsEnabled("new-checkout", shipd.EvaluationContext{
    UserID: "usr_8f2k19", Attributes: map[string]any{"plan": "pro", "country": "US"},
})
```

## Two kinds of credentials

| You're doing… | Use | Prefix |
| - | - | - |
| Evaluating flags in an app | SDK key (server or client) | `shipd_sdk_server_…`, `shipd_sdk_client_…` |
| Running `shipd push` locally | Management API key (created by `shipd login`) | `shipd_mgmt_…` |
| Running `shipd push` in CI | Service account token | `shipd_sa_…` |

SDK keys only read snapshots. The others only change configuration. Neither works in place of the other. See [Keys and tokens](/concepts/keys).

## What this means in practice

* **Your app doesn't wait on shipd.** Flag checks are in memory. If shipd is down, the SDK keeps the last snapshot it had, or serves your `defaults`.
* **Code owns what exists; the dashboard owns what's served.** Add or change flag definitions and run `shipd push`. To archive a flag, remove its definition and run `shipd push --prune` after reviewing the plan. Turn them on, target users, and roll out in the dashboard.
* **Environments share definitions, not state.** Adding a flag adds it everywhere. Turning it on in `staging` doesn't touch `production`.
* **Always pass `defaults`.** They are what your users get before the first snapshot arrives and whenever shipd can't be reached.

## Go deeper

* [Architecture](/concepts/architecture): control plane, data plane, and realtime updates
* [Local evaluation](/concepts/local-evaluation): the hot path and failure modes
* [Environments](/concepts/environments): production protection and per-environment state
* [Snapshots](/concepts/snapshots): the document the SDK evaluates
* [Glossary](/reference/glossary): every term, defined once


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.