Local development

Prerequisites

• uv and Python 3.13
• buf for protobuf edits
• Application Default Credentials with access to:
  • Cloud Spanner
  • Secret Manager secret STATSIG_SERVER_KEY (or the configured override)

Minimum local environment

export GCP_PROJECT_ID="nest-dev-473721"
export STATSIG_ENVIRONMENT="development"

# If you use file-based ADC:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

If you do not use a service-account file locally, authenticate with:

gcloud auth application-default login

Install and regenerate

Run these commands from the repo root:

# First-time workspace setup
uv sync --all-packages

# Targeted package sync
uv sync --package events

# Only when the proto changed
buf generate

Run the service

uv run --package events granian --interface asgi services.events.main:app --host 0.0.0.0 --port 8080 --workers 1

Startup will fail fast until all of these succeed:

• GCP project id resolution
• Spanner pool warmup
• Secret Manager lookup for the Statsig server key
• Statsig client initialization

Tests

uv run --package events pytest -q services/events/tests

When you change the contract

1. Edit proto/events/v1/events.proto.
2. Run buf generate.
3. Update services/events/tests/.
4. Update the repo docs and this docs section so the behavioral contract stays explicit.