Development Guide

Prerequisites

Quick Start (Full Stack)

Clone and configure

git clone https://github.com/anyaself/new_project.git
cd new_project
cp .env.example .env

The default .env uses inmemory backends and simulated runners — no cloud credentials needed.

Start the backend stack

docker compose up --build -d

This builds and starts all 8 backend services. First build takes ~3-5min.

Verify services

docker compose ps
# Or run the smoke check:
bash ./scripts/smoke_compose.sh

Start the frontend (optional)

cd apps/client-web
npm install
npm run dev

The frontend dev server starts at http://localhost:5173 and proxies API calls to the gateway at :8080.

Running Individual Services

Each service can run standalone. Useful for rapid iteration on a single service:

cd services/orchestrator
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn src.main:app --reload --port 8003

[!NOTE] When running a service standalone, inter-service calls will fail unless the dependent services are also running. Use docker compose for full integration.

Service Ports

Running Tests

All services use pytest with hermetically mocked external dependencies (Vertex AI, Firestore, Hyperbeam, etc).

Single Service

cd services/api-gateway
pytest -q

All Services

bash scripts/run_backend_tests.sh

Frontend Tests

cd apps/client-web
npm test

CI/CD Pipeline

The project uses a GitHub Actions workflow (.github/workflows/backend-ci.yml) that runs on every push and pull request:

1. Test matrix — Runs pytest -q for each of the 8 services independently using Python 3.12
2. Docker build — Builds Docker images for all 8 services to catch Dockerfile issues

Tests run in parallel via a matrix strategy with fail-fast: false, so a failure in one service won't block test results from others.

Code Conventions

• Framework: All backend services use FastAPI with Pydantic for request/response validation
• Architecture: Hexagonal pattern — see Architecture Overview
• Persistence: Dual-backend pattern (firestore / inmemory), selected via PERSISTENCE_BACKEND env var
• Auth: JWT-based with shared secret in dev, OIDC/JWKS in production
• Python style: Standard library typing, dataclasses for internal state, pydantic.BaseModel for API contracts
• Frontend: React 18 + TypeScript + Vite, no CSS framework (vanilla CSS)

Useful Scripts