Local Development

Run the backend and frontend locally.

You typically run the backend and frontend in two separate terminal windows. The frontend dev server proxies all /api requests to the backend on port 8080.

Backend

From the backend/ directory:

1. Create and activate a virtual environment

   python3.13 -m venv .venv
   source .venv/bin/activate
   
2. Install the package in editable mode

   pip install -e '.[dev]'
   
3. Start the dev server

   ../scripts/dev.sh
   

   The script sets up a throwaway SQLite database (halite-dev.db), runs alembic upgrade head, and starts uvicorn with --reload on http://127.0.0.1:8080. Default credentials are admin / changeme.

The dev server restarts automatically when you change Python source files.

Frontend

From the frontend/ directory:

1. Install dependencies

   npm install
   
2. Start the dev server

   npm run dev
   

   Vite starts on http://localhost:5173 and proxies all /api requests to the backend on :8080.

The dev server supports hot module replacement — most changes appear instantly without a full reload.

Regenerating API types

After changing any backend Pydantic schema or route, regenerate the frontend’s TypeScript types from the root of the repository:

./scripts/gen-types.sh

This requires the backend’s .venv to already exist. See API Spec for details.

Related pages

• Testing — running the test suite
• API Spec — regenerating the OpenAPI spec and TypeScript types