Local development

SAG is a repository with separate frontend and backend applications. Daily development usually runs FastAPI and Next.js in two terminals. Desktop development reuses both services through Electron.

Requirements

Python 3.11+
Node.js 20+
npm 10+
uv is recommended for managing the API environment

Start the API

cd apps/api
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
uvicorn sag_api.main:app --reload

The API runs at http://localhost:8000 by default, with OpenAPI at /docs.

Start the Web app

cd apps/web
npm install
npm run dev

The Web app runs at http://localhost:3000 by default. The browser-facing API address comes from the build-time variable NEXT_PUBLIC_API_BASE.

Common checks

cd apps/api
ruff check .

cd apps/web
npm run i18n:check
npm run typecheck
npm run build

The frontend maintains English and Chinese message files. Add every new interface string to both languages and pass the i18n check.

Debug document jobs

Ingestion failures usually cross the parser, job, and engine layers. Diagnose them in this order:

Inspect DocumentOut.status, progress, and error.
Use /api/v1/jobs/{job_id} to determine whether the job is retrying or paused.
Check API logs for parser and engine exceptions.
Verify LLM, Embedding, and MinerU independently.

Desktop development

Install dependencies for apps/web, apps/api, and apps/desktop, then run:

cd apps/desktop
npm run dev

The development script reuses services already running on ports 3000 and 8000. If it starts those services itself, exiting Electron stops them as well.

Desktop releases must be built natively on the target operating system because the PyInstaller sidecar includes platform- and CPU-specific dependencies. See apps/desktop/README.md in the repository for detailed release constraints.

Before contributing

Keep changes focused and run checks for every affected module. Architecture changes must preserve the dependency rule that the application reaches the knowledge engine only through sag_api/sag/.