{"id":29989799,"url":"https://github.com/policyengine/policyengine-api-v2","last_synced_at":"2026-01-20T16:37:16.497Z","repository":{"id":274710254,"uuid":"923819823","full_name":"PolicyEngine/policyengine-api-v2","owner":"PolicyEngine","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-31T11:06:00.000Z","size":1631,"stargazers_count":0,"open_issues_count":44,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-31T11:07:04.575Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolicyEngine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-28T21:54:30.000Z","updated_at":"2025-07-30T22:05:46.000Z","dependencies_parsed_at":"2025-02-13T20:24:46.160Z","dependency_job_id":"2ce49f67-8618-4dd7-80c0-f453a4554997","html_url":"https://github.com/PolicyEngine/policyengine-api-v2","commit_stats":null,"previous_names":["policyengine/policyengine-api-prototype","policyengine/policyengine-api-v2"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PolicyEngine/policyengine-api-v2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-api-v2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-api-v2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-api-v2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-api-v2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolicyEngine","download_url":"https://codeload.github.com/PolicyEngine/policyengine-api-v2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-api-v2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268802449,"owners_count":24309657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-04T23:26:58.451Z","updated_at":"2025-10-24T08:19:59.767Z","avatar_url":"https://github.com/PolicyEngine.png","language":"Python","readme":"# PolicyEngine API v2\n\nMonorepo for PolicyEngine's API infrastructure, containing all services, libraries, and deployment configuration. \n\n## Quick start\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Python 3.13+\n- [uv](https://docs.astral.sh/uv/) package manager\n- gcloud CLI (for deployment)\n- Terraform 1.5+ (for deployment)\n\n### Local development\n\nStart all services:\n```bash\nmake up        # Start services on ports 8081-8083\nmake logs      # View logs\nmake down      # Stop services\n```\n\nRun the test suite:\n```bash\nmake test                          # Unit tests only\nmake test-integration-with-services # Full integration tests (manages services automatically)\nmake test-complete                 # Everything: unit + integration tests\n```\n\n## Architecture\n\nThe repository contains three main API services:\n\n- **api-full** (port 8081): Main PolicyEngine API with household calculations\n- **api-simulation** (port 8082): Economic simulation engine  \n- **api-tagger** (port 8083): Cloud Run revision management\n\nEach service generates OpenAPI specs and Python client libraries for integration testing.\n\n## Development workflow\n\n### Making changes\n\n1. Edit code locally - services hot-reload automatically when running via `make up`\n2. Run tests: `make test-complete`\n3. Commit changes to a feature branch\n4. Open a PR - GitHub Actions will run tests automatically\n\n### Testing\n\nUnit tests run in isolated containers:\n```bash\nmake test                    # All services\nmake test-service service=api-full  # Single service\n```\n\nIntegration tests use generated client libraries:\n```bash\nmake generate-clients        # Generate OpenAPI clients (done automatically by test commands)\nmake test-integration        # Run integration tests (requires services running)\n```\n\n### Project structure\n\n```\n/\n├── projects/               # Service applications\n│   ├── policyengine-api-full/\n│   ├── policyengine-api-simulation/\n│   ├── policyengine-api-tagger/\n│   └── policyengine-apis-integ/    # Integration tests\n├── libs/                   # Shared libraries\n│   └── policyengine-fastapi/       # Common FastAPI utilities\n├── deployment/             # Deployment configuration\n│   ├── docker-compose.yml          # Local development\n│   ├── docker-compose.prod.yml     # Production builds\n│   └── terraform/                  # Infrastructure as code\n├── scripts/                # Utility scripts\n└── .github/workflows/      # CI/CD pipelines\n```\n\n## Deployment\n\n### Setting up a new GCP project\n\n**Important**: Most development should be done locally. Cloud deployment is slow and harder to debug.\n\n1. Configure environment:\n```bash\ncp deployment/.env.example deployment/.env\n# Edit deployment/.env with your GCP project details\n```\n\n2. Deploy infrastructure:\n```bash\nmake deploy  # Builds images, pushes to registry, runs terraform\n```\n\nFor existing GCP projects with resources:\n```bash\nmake terraform-import  # Import existing resources\n./deployment/terraform/handle-existing-workflows.sh $PROJECT_ID --delete  # Handle workflows\n```\n\nSee [deployment guide](deployment/DEPLOYMENT_GUIDE.md) for detailed instructions.\n\n### GitHub Actions deployment\n\nThe repository includes automated deployment pipelines:\n\n1. **Pull requests**: Runs tests and builds\n2. **Merge to main**: \n   - Deploys to beta environment\n   - Runs integration tests\n   - Deploys to production\n   - Publishes API client packages to PyPI\n\nConfigure GitHub environments with these variables:\n- `PROJECT_ID`: GCP project ID\n- `REGION`: GCP region (usually us-central1)\n- `_GITHUB_IDENTITY_POOL_PROVIDER_NAME`: Workload identity provider\n\n### Important notes from experience\n\n- **Wait after bootstrap**: GCP permission propagation can take up to an hour\n- **Workflows can't be imported**: Use the provided script to handle existing workflows\n- **Always test locally first**: Cloud debugging is painful\n- **Check terraform state**: If deployments fail, check if resources already exist\n\n## Commands reference\n\n### Development\n- `make up` - Start services locally\n- `make down` - Stop services\n- `make logs` - View service logs\n- `make build` - Build Docker images\n\n### Testing\n- `make test` - Run unit tests\n- `make test-integration` - Run integration tests\n- `make test-complete` - Run all tests with service management\n- `make generate-clients` - Generate API client libraries\n\n### Deployment\n- `make deploy` - Full deployment to GCP\n- `make terraform-plan` - Preview infrastructure changes\n- `make terraform-import` - Import existing resources\n- `make terraform-destroy` - Remove all infrastructure\n- `make publish-clients` - Publish API clients to PyPI (requires PYPI_TOKEN)\n\n## Troubleshooting\n\n### Services won't start\n- Check Docker is running\n- Ensure ports 8081-8083 are free\n- Run `make build` to rebuild images\n\n### Integration tests fail\n- Regenerate clients: `make generate-clients`\n- Check services are healthy: `make logs`\n- Verify port configuration matches docker-compose.yml\n\n### Deployment issues\n- Check deployment/.env configuration\n- Verify GCP authentication: `gcloud auth list`\n- For \"already exists\" errors: `make terraform-import`\n- For workflow errors: `./deployment/terraform/handle-existing-workflows.sh`\n\n## Contributing\n\n1. Create a feature branch\n2. Make changes and test locally\n3. Ensure `make test-complete` passes\n4. Open a PR with a clear description\n5. Wait for CI checks to pass","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine-api-v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolicyengine%2Fpolicyengine-api-v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine-api-v2/lists"}