Run locally¶

The recommended development setup uses FastAPI on port 8000, Flutter Web on 8001, and MkDocs on 8002.

Run both app processes from Git Bash¶

./start.sh

The script:

1. validates both ports;
2. finds backend/.venv or backend/.venv311;
3. creates backend/.env from the example when missing;
4. reuses an already healthy backend on the configured port;
5. starts FastAPI with reload;
6. waits for /api/v1/health;
7. installs Flutter packages when needed; and
8. starts Flutter Web with the correct API URL.

Press Ctrl+C once to stop the processes started by the script.

Change ports¶

BACKEND_PORT=9000 FRONTEND_PORT=9001 ./start.sh

Use another Flutter device¶

FLUTTER_DEVICE=windows ./start.sh

Run the services separately¶

Backend:

cd backend
.venv/Scripts/python.exe -m uvicorn app.main:app \
  --host 127.0.0.1 \
  --port 8000 \
  --reload

Frontend:

cd frontend
flutter run -d chrome \
  --web-port 8001 \
  --dart-define=API_BASE_URL=http://localhost:8000/api/v1

Documentation:

.venv-docs/Scripts/python.exe -m mkdocs serve \
  --dev-addr 127.0.0.1:8002

Useful local URLs¶

Port already in use¶

On Windows:

Get-NetTCPConnection -LocalPort 8000,8001,8002 -ErrorAction SilentlyContinue |
  Select-Object LocalPort, State, OwningProcess

Stop only the process you recognize, or choose different ports. Do not terminate a process solely because it appears in this list.