Provides architecture overview, local Docker setup, and contribution guide for PolicyEngine API v2 Python monorepo microservices with Supabase and OpenAPI. Useful for developers contributing to active development.
From essentialnpx claudepluginhub policyengine/policyengine-claude --plugin data-scienceThis skill uses the workspace's default tool permissions.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Details PluginEval's skill quality evaluation: 3 layers (static, LLM judge), 10 dimensions, rubrics, formulas, anti-patterns, badges. Use to interpret scores, improve triggering, calibrate thresholds.
The next-generation PolicyEngine API is a monorepo containing multiple microservices built with modern Python tooling.
API v2 is the next generation of the PolicyEngine API, currently in active development. When complete, it will replace the current Flask API with a more scalable, maintainable microservices architecture.
Status: 🚧 Active development (not yet in production)
Key improvements over v1:
Currently, analysts should continue using the v1 API at https://api.policyengine.org.
API v2 is not yet ready for production use. Check the repository README for the latest status.
Location: PolicyEngine/policyengine-api-v2
Clone:
git clone https://github.com/PolicyEngine/policyengine-api-v2
cd policyengine-api-v2
API v2 is a monorepo containing multiple microservices:
To see current structure:
tree -L 2 .
# Expected structure:
# ├── api-full/ - Main API (port 8081)
# ├── api-simulation/ - Economic simulation (port 8082)
# ├── api-tagger/ - Deployment management (port 8083)
# ├── docker-compose.yml
# └── shared/ - Shared utilities
1. api-full (port 8081)
2. api-simulation (port 8082)
3. api-tagger (port 8083)
To see current dependencies:
# Check pyproject.toml in each service
cat api-full/pyproject.toml
cat api-simulation/pyproject.toml
cat api-tagger/pyproject.toml
Key technologies:
To start all services locally:
# See current docker-compose setup
cat docker-compose.yml
# Start services
docker-compose up
# Services should be available at:
# - http://localhost:8081 (api-full)
# - http://localhost:8082 (api-simulation)
# - http://localhost:8083 (api-tagger)
Alternative: Run individual service:
cd api-full
uv pip install -e .
python main.py # or whatever the entry point is
API v2 uses uv instead of pip for faster dependency management:
To see current uv usage:
# Check if uv is used
cat pyproject.toml | grep -A 5 "tool.uv"
# Or check for uv.lock files
find . -name "uv.lock"
Common uv commands:
# Install dependencies
uv pip install -e .
# Add a dependency
uv add package-name
# Sync dependencies
uv sync
To see current Supabase setup:
# Check for Supabase configuration
cat .env.example | grep SUPABASE
grep -r "supabase" . --include="*.py" | head -10
# Supabase client initialization
grep -r "create_client" . --include="*.py"
Common patterns:
# Example (check actual implementation)
from supabase import create_client
supabase = create_client(supabase_url, supabase_key)
# Query
result = supabase.table('policies').select('*').execute()
# Insert
supabase.table('policies').insert({'data': policy}).execute()
API v2 may integrate with design tokens from policyengine-app-v2:
To check design token usage:
# Look for design token imports
grep -r "design.*token\|designTokens" . --include="*.py"
grep -r "@policyengine/design" package.json
# Check if tokens are in dependencies
cat package.json | grep -A 5 "dependencies"
If using npm design tokens:
# Design tokens from app-v2
bun install @policyengine/design-tokens
To see current API spec generation:
# Look for OpenAPI/Swagger setup
grep -r "openapi\|swagger" . --include="*.py"
# Check for spec files
find . -name "openapi*.json" -o -name "openapi*.yaml"
# If using FastAPI, specs auto-generated at /docs
To see current test setup:
ls -la tests/
cat pytest.ini # or pyproject.toml for pytest config
Run tests:
# All services
pytest
# Specific service
cd api-full && pytest
# With docker-compose
docker-compose run api-full pytest
Key architectural differences:
| Aspect | v1 (Flask monolith) | v2 (Microservices) |
|---|---|---|
| Structure | Single Flask app | Multiple services |
| Database | Redis + Cloud SQL | Supabase (PostgreSQL) |
| Deployment | Google App Engine | Docker containers |
| Package manager | pip | uv |
| Python version | 3.9+ | 3.13+ |
To understand migration patterns:
# Compare endpoint implementations
# v1: policyengine-api/policyengine_api/endpoints/
# v2: api-full/endpoints/ (or similar)
# See what's been ported
git log --grep="migrate\|port" --oneline
Task 1: Add New Endpoint to api-full
Find current endpoint pattern:
# Look at existing endpoints
ls api-full/endpoints/ # or api-full/routes/
cat api-full/endpoints/example.py
Follow the pattern (likely FastAPI or Flask)
Update OpenAPI spec (may be auto-generated)
Add tests:
cat tests/test_endpoints.py
Task 2: Work with Supabase
# See current database schema
cat supabase/migrations/*.sql # if using migrations
# Test database locally
docker-compose up supabase # if in docker-compose
Task 3: Use Design Tokens
# Check if design tokens are integrated
grep -r "design.*token" .
# If using from app-v2, import them:
# (Actual implementation depends on current setup)
To see required environment variables:
cat .env.example
# Common variables:
# - SUPABASE_URL
# - SUPABASE_KEY
# - DATABASE_URL
# - API_PORT (8081, 8082, 8083)
To see current monorepo structure:
# List all services
ls -d */
# Check for shared code
ls shared/ common/ lib/ # (if exists)
# See inter-service dependencies
grep -r "../api-" pyproject.toml
Pattern:
shared/ or similarRepository: https://github.com/PolicyEngine/policyengine-api-v2
Related:
⚠️ Important: API v2 is in active development. Always check the repository README for:
To see current status:
cat README.md
git log -10 --oneline