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

# The EdgeSpark declarative workflow

> How EdgeSpark agents should work with declarative repo-owned defs, generated SDK types, pulled system schema, and migrations.

EdgeSpark uses a declarative workflow for app tables, storage buckets, runtime keys, and auth config. The source of truth is your repo, not a dashboard editor. Agents should edit repo-authored defs, generate migrations, apply declarative config, pull generated SDK types when needed, and never hand-write platform types.

## Files to read before writing code

Every EdgeSpark project has two important categories of files:

| File                                         | Purpose                            | Edit it? |
| -------------------------------------------- | ---------------------------------- | -------- |
| `server/src/defs/db_schema.ts`               | App table definitions              | Yes      |
| `server/src/defs/db_relations.ts`            | App relations                      | Yes      |
| `server/src/defs/storage_schema.ts`          | Bucket declarations                | Yes      |
| `server/src/defs/runtime.ts`                 | Allowed var and secret keys        | Yes      |
| `server/src/__generated__/sys_schema.ts`     | Pulled system-managed tables       | No       |
| `server/src/__generated__/sys_relations.ts`  | Pulled system-managed relations    | No       |
| `server/src/__generated__/edgespark.d.ts`    | Generated imports from `edgespark` | No       |
| `server/src/__generated__/server-types.d.ts` | Generated runtime SDK types        | No       |

<Warning>
  Never edit files in `server/src/__generated__/`. They are overwritten by pull commands.
</Warning>

## Commands you should use

```bash theme={null}
# App schema workflow
edgespark db generate
edgespark db migrate
edgespark db check

# Generated platform files
edgespark pull schema
edgespark pull types
edgespark pull types --check

# Bucket and auth config sync
edgespark storage apply
edgespark auth apply
```

## Recommended workflow

<Steps>
  <Step title="Read repo-authored defs">
    Start with `server/src/defs/db_schema.ts`, `server/src/defs/storage_schema.ts`, and `server/src/defs/runtime.ts`. These files tell you what the app intends to own.
  </Step>

  <Step title="Read generated runtime types">
    Open `server/src/__generated__/edgespark.d.ts` and `server/src/__generated__/server-types.d.ts` before using runtime SDK imports. Do not guess import names or method signatures.
  </Step>

  <Step title="Update schema or buckets in code">
    Add tables in `db_schema.ts`, relations in `db_relations.ts`, buckets in `storage_schema.ts`, and runtime key names in `runtime.ts`.
  </Step>

  <Step title="Run the matching sync command">
    ```bash theme={null}
    edgespark db generate
    edgespark db migrate
    edgespark storage apply
    edgespark pull types
    ```
  </Step>

  <Step title="Write handlers against typed imports">
    ```typescript server/src/index.ts theme={null}
    import { db } from "edgespark";
    import { Hono } from "hono";
    import { posts } from "@defs";

    const app = new Hono().get("/api/posts", async (c) => {
      return c.json(await db.select().from(posts));
    });

    export default app;
    ```
  </Step>

  <Step title="Type check before deploy">
    ```bash theme={null}
    cd server && npx tsc --noEmit
    ```
  </Step>
</Steps>

## When to pull

Use `edgespark pull schema` when you need the latest platform-managed tables or system metadata in `server/src/__generated__/`.

Use `edgespark pull types` when runtime SDK types may be stale. In automation or CI, use:

```bash theme={null}
edgespark pull types --check
```

## See also

<Columns cols={2}>
  <Card title="Use the database" icon="database" href="/guides/database">
    How to define schema, generate migrations, and query D1 in the current scaffold.
  </Card>

  <Card title="Handling errors" icon="triangle-exclamation" href="/agents/handling-errors">
    How to fix stale types, migration issues, and deploy failures.
  </Card>
</Columns>