Local Development

This project uses FastAPI for the backend and a React SPA for the frontend. Below are the shortest paths to get running.

Prerequisites

• Python 3.11+
• Node.js 18+ (for the SPA)
• Docker (optional, for compose flows)
• gcloud CLI (for GCP deploys)

Backend

1. Create a virtualenv and install deps:
   • python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
2. Copy envs and adjust:
   • cp env.example .env (or use .env.local)
3. Run the API:
   • .venv/bin/uvicorn src.api.main:app --reload
4. Run tests:
   • .venv/bin/python -m pytest tests/

Frontend

1. Install and run dev server:
   • cd frontend && npm install && npm run dev
2. For Cloud Run proxy dev, see Makefile targets frontend-cloudrun and frontend-cloudrun-env.

Docker & Makefile

• make dev – run API dev server
• make test – run pytest
• make run – build + run container
• make deploy – push image + deploy Cloud Run

Docs (MkDocs)

• make docs:serve – live preview at http://127.0.0.1:8000
• make docs:build – static site output in site/
• make docs:deploy – build and upload to GCS docs bucket

Next Steps

• Review Architecture for data flow and components.
• See Terraform Guide for provisioning Cloud Run and related infra.