Development Setup

Run ChatWalaʻau from source for development.

Prerequisites

Tool	Version	Install
Node.js	20.19+ / 22.12+	nodejs.org
pnpm	10+	npm install -g pnpm
Python	3.12+	python.org
uv	0.9+	docs.astral.sh/uv
Azure CLI	2.x	Install Azure CLI

1. Backend

Windows (PowerShell):

cd backend
copy .env.sample .env
notepad .env          # set your Azure OpenAI endpoint
uv sync --prerelease=allow

macOS / Linux:

cd backend
cp .env.sample .env
nano .env             # set your Azure OpenAI endpoint
uv sync --prerelease=allow

Required .env:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_MODELS=gpt-4o

See Configuration -> Azure authentication for credential lanes.

2. Frontend

cd frontend
pnpm install

3. Start the dev servers

Open two terminals:

# Terminal 1 -- backend at http://localhost:8000
cd backend
uv run uvicorn app.main:app --reload --app-dir src

# Terminal 2 -- frontend at http://localhost:5173 (API proxied to the backend)
cd frontend
pnpm dev

4. Production build

cd frontend
pnpm build

cd ../backend
uv run uvicorn app.main:app --app-dir src

The backend serves both the frontend build and the API at http://localhost:8000.

Tech stack

Layer	Technology	Purpose
Frontend	React 19 + TypeScript + Vite	UI framework
Frontend	Tailwind CSS + shadcn/ui	Styling + components
Frontend	Biome	Format + lint
Backend	FastAPI + Python 3.12+	API server
Backend	Microsoft Agent Framework	Agent execution + tool control
Backend	Ruff	Format + lint
Package	uv	Python dependencies
Package	pnpm	Node.js dependencies