---
title: "Development"
description: "Local build, test and lint commands, repository layout, migrations, and the release pipeline."
---

> Documentation Index
> Fetch the complete documentation index at: https://sumidoku.github.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

## Local build

The web UI is embedded into the binary at compile time, so it must be built
first:

```sh
cd webui && npm ci && npm run build && cd ..
cargo build --release -p sumidoku-server
```

During development, `cd webui && npm run dev` starts the Vite dev server,
proxying API calls to the server on :3000.

## Tests and lint

Server (Rust):

```sh
cargo nextest run --workspace
cargo clippy --workspace --all-targets -- -D warnings
```

Web UI:

```sh
cd webui && npm ci && npm run check && npm run build
```

:::note
A change only under `webui/` skips the Rust tests, clippy and the release
build. When a change touches both, build `webui/` first and then run
`cargo build --release -p sumidoku-server`: rust-embed only bundles
`webui/build` into a release binary.
:::

## Repository layout

- `crates/server` — axum HTTP server: REST `/api/v1` and embedded web UI
- `crates/wasm` — Aidoku WASM source runtime (wasmi)
- `vendor/aidoku` — vendored upstream crate; it tracks upstream, do not
  restyle or "fix" it locally
- `webui` — Vite + React SPA, built to `webui/build`
- `data/` — local dev database, cover cache and sources; untracked, never
  commit it

## Database migrations

- Schema changes are new numbered files only; do not edit an applied
  migration.
- No SQL triggers or views without a special case: what a write must also
  do belongs in the store that makes the write, and sync payloads belong in
  `sync/journal.rs`. `db.rs:migrated_schema_has_no_triggers_or_views`
  enforces it.
- Keep migration comments in English and files in LF. `.gitattributes` and
  `db.rs:shipped_migrations_use_ascii_comments_and_lf` enforce the
  encoding.
- `db.rs:shipped_migrations_are_immutable` pins canonical checksums. The
  explicitly listed historical Chinese/English LF/CRLF checksums are a
  closed compatibility set, not permission for further edits or derived
  aliases.

## Release pipeline

- The version lives in the workspace `Cargo.toml`. A push to `main` that
  touches it runs the release pipeline: five platform archives, Docker Hub
  (`sumidoku/sumidoku`) and ghcr.io (`ghcr.io/sumidoku/sumidoku`) tags
  `latest`/`X.Y.Z`/`<major>.x` (e.g. `0.x`), and the GitHub release.
- Never push a tag or create a release by hand; CI does both.
- A release counts only when the run is green, the release shows its 5
  assets, and the 3 tags moved on both registries. Verify before
  announcing; the checklist is in
  [docs/code-standards.md](https://github.com/Sumidoku/Sumidoku/blob/main/docs/code-standards.md#releases).

## Further reading

The binding development rules — tests, commits and merges, PR review — are
in
[docs/code-standards.md](https://github.com/Sumidoku/Sumidoku/blob/main/docs/code-standards.md),
and [AGENTS.md](https://github.com/Sumidoku/Sumidoku/blob/main/AGENTS.md)
is the entry point for how the project's agent sessions work. See
[Contributing](https://sumidoku.github.io/docs/contributing) for how community PRs are handled.

Source: https://sumidoku.github.io/docs/development/index.mdx
