Documentation

Development

Build CroCode locally and run the Rust and web validation checks.

On this page

Project layout

Path	Purpose
`crates/core`	Pure review logic: config, diff parsing, finding validation, and prompts. No I/O.
`crates/server`	Axum API, GitHub client, Postgres queue, worker, and sandbox runner.
`web`	Next.js dashboard and documentation. Bun is the package manager and test runner.
`migrations`	SQLx migrations applied by crocode migrate before runtime startup.
`docker/sandbox`	Read-only agent image.

Rust checks

Use Rust 1.89 or newer. Run from the repository root:

cargo fmt --all --check\ncargo clippy --all-targets -- -D warnings\ncargo test --all

Plain tests skip database tests. To include them, set a reachable Postgres URL for a user that can create databases:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:55432/postgres \
  cargo test --all -- --include-ignored

Port 55432 belongs to the development host’s test database. Compose does not publish its database port. Use your own reachable URL on other hosts.

Web checks

Use Bun 1.3.14. Run from web/:

bun install --frozen-lockfile\nbun run lint\nbun run typecheck\nbun test\nbun run build\nbun run scripts/smoke.ts

The smoke script starts the built standalone server and a mock API. It checks sign-in, permissions, settings, review pages, and error states without real GitHub or model calls.

Container checks

sudo docker build -t crocode:latest .\nsudo docker build -t crocode-sandbox:latest docker/sandbox\nsudo docker compose config --quiet\nsudo docker compose --profile dashboard config --quiet

Use native AMD64 and ARM64 runners to verify both image architectures. Read the Docker guide before changing CLI versions or sandbox flags.

Edit the documentation

Docs navigation and page metadata live in web/lib/docs-nav.ts. Article sections live in web/lib/docs-content.tsx. The layout derives each page outline from those sections.

Keep web guides aligned with README.md, docs/, and docker/README.md. Keep REST API examples aligned with docs/api.md and crates/server/src/api.rs.

The articles use React components so the dashboard needs no Markdown runtime dependency. Add a Markdown pipeline only when the number of contributors or articles makes this format hard to maintain.

Run bun run build:docs from web/ to export the GitHub Pages site to web/site/out. Run bun run scripts/check-docs-export.ts to check the exported links and assets. The static app in web/site excludes dashboard and authentication routes.