# Speed App Development

What a Speed app looks like as code, and where the conventions for writing one
are. This is the page to read when writing or editing the app itself, in your own
editor or with your own coding agent. Running the app on your machine and getting
the result onto the platform — uploading, previewing, deploying — is covered in
[Bring Your Own Agent](./Bring-Your-Own-Agent.md).

## What a Speed app is

A Speed app is a React frontend built by rsbuild, a Hono backend on port 3000,
and a SQLite database managed with Drizzle. The platform builds it with its own
Dockerfile, which relies on a few things staying in place:

- Keep the `build` and `db:apply` scripts in `package.json`, and keep
  `speed-framework` as its `file:` dependency. Deployment runs `pnpm run build`,
  and database migrations run `pnpm run db:apply`.
- Keep the database schema in `db/schema.ts`.
- The server listens on port 3000.
- Persistent files live in `.data/`. Everything else in the project directory is
  rebuilt or replaced on each upload.

Every app starts from the same project template, the startkit. Its
`api/_framework.d.ts` and `src/speed-env.d.ts` describe the Speed SDK surface and
must not be modified. `speed-framework` itself is not part of the source tree: the
startkit image provides it at `/tmp/framework`, which is where the `file:`
dependency points once the app runs in the container.

## Conventions for the agent

The image ships the coding conventions that the Speed agent itself follows,
adapted for an agent working from outside the platform:

- `/tmp/AGENTS.md` — project layout, frontend, backend, database and auth
  conventions. Read this first.
- `/tmp/skills/*.md` — one file per platform feature: `auth`, `llm`,
  `llm-server`, `upload`, `image-generation`, `in-app-purchases`, `analytics`.
  `AGENTS.md` says which one to read when.
- `/tmp/examples/` — reference implementations that the conventions point to.

They live inside the container, not in the app directory, so read them through
the running container (started as described in
[Bring Your Own Agent](./Bring-Your-Own-Agent.md#running-locally)):

```bash
docker exec speed-dev cat /tmp/AGENTS.md
docker exec speed-dev cat /tmp/skills/llm.md
docker exec speed-dev ls /tmp/examples/src
```

If you want them on disk, `docker cp speed-dev:/tmp/examples ./examples` copies
the examples next to your app; keep them out of the upload tarball.

Commands that the conventions tell you to run — `pnpm add`, `pnpm run check`,
`pnpm run db:apply` — run inside the container as well:
`docker exec speed-dev pnpm run check`. Dev server output, including backend
errors, is `docker logs speed-dev`.