Development Workflows

The repo supports a few distinct loops. Picking the right one avoids unnecessary Docker rebuilds and keeps debugging targeted.

Mode Comparison

Mode	Command	Use it for	Primary env file
Local development	make dev-all	Fast backend/frontend iteration with Docker-backed infra	.env
Infra only	make infra	Running backend or frontend by hand against Postgres/Redis/MinIO	.env
Full stack	make stack-build	Container parity across backend, sandbox server, tool server, worker, and frontend	docker/.stack.env
Docs only	make docs-dev	Editing the Docusaurus site without touching the product stack	docs/docusaurus/*

Recommended Daily Loop

1. Run make setup once per checkout.
2. Populate .env and model config.
3. Use make dev-all for most code changes.
4. Use targeted backend/frontend commands when isolating one layer.
5. Switch to make stack-build when validating the complete containerized topology.

Key Commands

Bootstrap

make setup

Creates .env and frontend/.env if missing, then installs backend and frontend dependencies.

Start local development

make dev-all

This starts Postgres, Redis, and MinIO in Docker, then runs:

• backend on http://localhost:8000
• frontend on http://localhost:1420
• MinIO console on http://localhost:9001

Bring up the full stack

make stack-build

This uses scripts/run_stack.sh and docker/.stack.env to start:

• postgres
• redis
• tool-server
• sandbox-server
• backend
• celery
• frontend

Docs loop

make docs-install
make docs-dev
make docs-build

Environment File Boundaries

• .env drives host-native development.
• frontend/.env drives the Vite dev server.
• docker/.stack.env drives the full Docker stack.
• docs/docusaurus has its own package.json and build output.

Do not assume one env file applies to every workflow.

Verification Checklist

Local development

curl http://localhost:8000/health

Docker stack

curl http://localhost:8000/health
curl http://localhost:1236/health
curl http://localhost:8100/health

Docs build

cd docs/docusaurus
npm run build

When To Use Which Flow

• Use make dev-all when changing Python or frontend app code.
• Use make stack-build when validating service-to-service env wiring.
• Use make docs-dev when editing this site.
• Use make infra when you want the lightest local dependency footprint.