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

# Building on Graviton

> Developer documentation for engineers writing code in a Stardeck app — the runtime, the SDKs, the constraints, and what differs from a plain Next.js project.

**Graviton is the architecture every Stardeck app runs on.** Your app is a
Next.js 16 App Router project that deploys as a Cloudflare Worker, talks to the
platform through installed SDKs, and is carried forward by a versioned upgrade
rail.

These pages are for the person writing the code. If you are looking for how to
*use* the product — agents, dashboards, publishing — start at the
[documentation home](/).

## Start here

<CardGroup cols={3}>
  <Card title="Constraints" icon="triangle-exclamation" href="/graviton/constraints">
    What the runtime refuses, and which files the platform owns. Read this first.
  </Card>

  <Card title="Compared to plain Next.js" icon="right-left" href="/graviton/vs-nextjs">
    Same framework, different boundaries. What you do differently here.
  </Card>

  <Card title="The SDKs" icon="box" href="/graviton/sdks">
    The packages installed in every app, and where each one's full API lives.
  </Card>
</CardGroup>

## The shape of an app

```mermaid theme={null}
flowchart TB
    B["Browser or installed PWA"] --> D["Stardeck dispatch worker<br/>host routing · edge auth · visibility gate"]
    D --> W["Your app: one Worker<br/>Next.js 16 App Router"]
    W --> S["Stardeck SDKs<br/>HMAC-signed calls"]
    S --> P["Platform services<br/>Data Stores · storage · email · payments · integrations"]
```

Two things in that diagram are easy to miss, and they shape everything else:

* **Your code is not the first hop.** Hostname classification, tenant lookup,
  signed-in user resolution and public/internal visibility are decided in the
  shared dispatch worker before your app runs.
* **Your app owns no infrastructure.** There is no database you provision, no
  queue you run, no bucket you name. Capabilities arrive as SDKs, and the
  platform holds the credentials.

## Working on an app

| You want to                              | Go to                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Get repository access                    | [Managing GitHub repository access](/github-access)                                               |
| Run the app on your machine              | [Run your app locally](/local-claude-code/running-locally)                                        |
| Give your editor platform tools          | [Connect Claude Code](/local-claude-code/connect) · [what the tools do](/local-claude-code/tools) |
| Understand app layout, Surfaces, Modules | [Structuring your app](/app-structure/overview)                                                   |
| Write and run tests                      | [Testing](/testing) · [Test-driven development](/test-driven-development)                         |
| Know which environment you are touching  | [Environments](/environments)                                                                     |
| Configure environment variables          | [Environment variables](/environment-variables)                                                   |

<Note>
  Your local checkout is not what the preview serves. The hosted sandbox builds from the project's
  `main` branch on the platform, so your edits appear in the dashboard preview only after they are
  pushed.
</Note>

## Operations that are not code

Some things a Stardeck app depends on are configured through the platform rather
than committed to the repository — database schema, permission keys, role grants,
Module installs. You reach them from the dashboard, or from your editor once
[Claude Code is connected](/local-claude-code/tools). The
[constraints page](/graviton/constraints#operations-that-do-not-live-in-code) maps each
one to the place you actually do it.