Topolo Venue Survey Handbook

What It Is

Topolo Venue Survey is an internal venue-intake application with a worker-backed API, a Pages web shell, venue asset storage, and operator login flows.

Architecture

The system is split between:

• a Cloudflare Worker API in InternalApplications/topolo-venue-survey/apps/api
• a Cloudflare Pages web app in InternalApplications/topolo-venue-survey/apps/web
• shared packages for survey-domain logic

Runtime Surfaces

• Pages frontend at https://survey.topolo.app
• Worker API at https://topolo-venue-survey-api.topolo.workers.dev
• D1 survey database
• R2 asset bucket

API Reference

The current contract is curated in the worker routes under InternalApplications/topolo-venue-survey/apps/api and centers on operator login, venue survey capture, asset upload, and survey workflow reads/writes.

Auth and Permissions

Venue Survey uses magic-link style operator access and should remain aligned with the broader Topolo auth and identity model rather than introducing app-local credential storage.

Data Ownership

Venue Survey owns venue survey records, uploaded venue assets, and survey workflow state.

Deployments

Venue Survey now follows the platform-standard ci.yml and deploy.yml GitHub Actions contract. The Worker deploy uses the repo-declared Wrangler config under apps/api, and the Pages deploy uses the repo-declared Pages config under apps/web. Production promotion is explicit from a successful CI artifact rather than automatic on main.

The repo is now published at Topolo-io/topolo-venue-survey, and CloudControl should resolve the deployment surface from that standalone GitHub identity.

The hardened CI contract now declares explicit ci_targets for packages/shared, apps/api, and apps/web, with the API surface also requiring worker dry-run validation before promotion.

Failure Modes

• the Pages web shell deploys without the current API origin or headers
• the Worker and Pages surfaces drift to different environments
• D1 or R2 bindings point at the wrong Cloudflare account or resource

Debugging

• inspect topolo.cloudcontrol.json first for the declared deploy targets
• verify apps/api/wrangler.toml and apps/web/wrangler.toml match the intended production surface
• confirm the worker and Pages deploys came from the same GitHub Actions run context

Change Log / Verification

• Added canonical internal coverage and deployment guidance for Topolo Venue Survey on 2026-03-31
• Corrected the manifest to treat Venue Survey as an unpublished local repo root rather than a fake GitHub remote on 2026-03-31
• Published Venue Survey to Topolo-io/topolo-venue-survey and restored the canonical manifest repo identity on 2026-03-31
• Added explicit CI target coverage and worker dry-run validation to the Venue Survey deployment contract on 2026-03-31