Development

Development setup

You need: uv, Node.js 20+, Rust, the Tauri CLI (cargo install tauri-cli --version "^2" --locked) and, on Linux, Tauri's system packages.

git clone https://github.com/docboxai/docbox-app.git && cd docbox-app
uv sync --extra paddle           # base + PaddleOCR; --all-extras adds EasyOCR/PyTorch
npm --prefix frontend install
cargo tauri dev                  # from the repository root, not src-tauri/

A plain uv sync removes extras you didn't pass, so always pass the ones you want.

Running parts on their own

• Backend: uv run python -m docbox.backend.main --port 8756, with Swagger UI at http://127.0.0.1:8756/docs.
• Frontend: npm --prefix frontend run dev (port 1420). Vite passes /api through to the backend above.
• Website: cd website && bun install && bun run dev.

Checks

CI runs these on every pull request, on Windows, macOS and Linux:

uv run pytest
uv run ruff check src/docbox tests
npm --prefix frontend run build
cargo check --manifest-path src-tauri/Cargo.toml

Test on Windows when you touch files, paths or line endings: most users are on Windows, and those bugs don't show up on macOS or Linux.

Where things are

Folder	What
src/docbox/backend/	FastAPI backend: routes, model registry, engines, runtime and prerequisite managers
src-tauri/	Rust shell: first-run setup, starting and stopping the backend
frontend/	React + TypeScript + Tailwind UI
website/	Landing page (Next.js, deployed on Vercel)
tests/backend/	pytest suite

CLAUDE.md in the repository explains the architecture in depth, including how to add a new engine or model.

Branches

• main can always be released; every change goes in through a pull request.
• New features are built on feature/… branches. See the Roadmap for what's planned.