AlgoKit Compiler Viz

A web-based visualization tool for the Algorand Puya compiler. Compile Algorand Python smart contracts and explore the compilation pipeline stages.

Development

Prerequisites

• Node.js 22+ with pnpm
• Python 3.12+ with uv
• Git (for puya submodule)

Setup

# Clone with submodules
git clone --recursive <repo-url>
cd algokit-compiler-viz

# API setup
cd api
uv sync
uv run python scripts/setup_versions.py  # Install compiler versions

# App setup
cd ../app
pnpm install

Running Locally

# Terminal 1: API (port 8000)
cd api
uv run uvicorn compiler_viz.main:app --reload

# Terminal 2: App (port 5173)
cd app
pnpm dev

Open http://localhost:5173

Deploy

Deploy to Google Cloud Run.

Prerequisites

1. GCP Project: gcloud config set project <your-project>

2. Enable APIs:

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com

3. Create Artifact Registry:

   gcloud artifacts repositories create compiler-viz --repository-format=docker --location=us-central1

4. Create Service Account (runtime identity for the Cloud Run API service):

   gcloud iam service-accounts create compiler-viz-api --display-name="Compiler Viz API"

5. Grant permission to deploy as the service account:

   gcloud iam service-accounts add-iam-policy-binding compiler-viz-api@<your-project-id>.iam.gserviceaccount.com \
     --member="user:<your-email>" \
     --role="roles/iam.serviceAccountUser"

Deploy

./scripts/deploy.sh

Puya Version Management

The "latest" compiler version always comes from the api/puya git submodule. Older versions are baked into the Docker image at build time.

By default, scripts/resolve_puya_versions.py automatically queries the GitHub releases API and selects the latest patch release of each prior minor/major version (e.g., if the submodule is v5.7.1, it resolves v5.6.0 v5.5.0 v5.4.0).

To override automatic resolution, set PUYA_VERSIONS in your .env file:

PUYA_VERSIONS="v5.6.0 v5.5.0"  # Pin specific versions

A GitHub Actions workflow runs daily to check for new Puya releases. If a new release is detected, it opens a PR to update the submodule. Merging the PR and redeploying will automatically pick up the new version and resolve the correct older versions.

Environment Variables

Variable	Default	Description
GOOGLE_CLOUD_PROJECT	algorand	GCP project ID
GOOGLE_CLOUD_REGION	us-central1	Deployment region
PUYA_VERSIONS	Auto-resolved	Puya versions to bake into image. Leave unset for automatic resolution
SKIP_API	-	Skip API deployment
SKIP_APP	-	Skip App deployment