Topolo Survey

Public overview of Topolo Survey, the Topolo survey builder and public response collection application.

publicverified 2026-07-27surveyapplication

What It Is

Topolo Survey is the Topolo application for building surveys, publishing public collector links, and reviewing responses from an authenticated workspace.

Architecture

The application uses the shared Topolo shell and Topolo Auth for authenticated operator workflows. A Cloudflare Worker serves the workspace, public collector routes, and API surface, backed by an app-owned D1 database.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

  • Shared landing page at https://survey.topolo.app/
  • Shared login page at https://survey.topolo.app/login
  • Shared auth callback at https://survey.topolo.app/auth/callback
  • Authenticated workspace at https://survey.topolo.app/ once signed in
  • Public collector routes under https://survey.topolo.app/public/:slug
  • Authenticated admin APIs under /api/surveys/*
  • Public collector APIs under /api/public/surveys/:slug*

API Reference

The current production v1 exposes:

  • GET /api/health
  • GET /api/bootstrap
  • GET/POST /api/surveys
  • GET/PATCH/DELETE /api/surveys/:id
  • GET /api/surveys/:id/responses
  • GET /api/surveys/:id/summary
  • GET /api/public/surveys/:slug
  • POST /api/public/surveys/:slug/responses

Auth and Permissions

Authenticated browser and API requests use Topolo Auth through app id app_RCOi7CJkwf7R, supplied to the Worker as APP_ID rather than resolved through a runtime Auth slug lookup. Signed-out operators land on the shared Topolo landing and login screens before entering the workspace. Public collector routes do not require authentication and only expose published survey definitions plus response submission.

Data Ownership

Topolo Survey stores organization-scoped survey definitions and responses in its own D1 database. Public submission routes write into the owning organization only for the published survey slug being collected.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /surveys, its offline policy is read_through_cache, and it requires organization context.

Published permissions: workspace:read, workspace:write.

  • /surveys uses /api/surveys with the record.list template and survey.surveys.list data source.
  • /surveys/:id uses /api/surveys/:id with the record.detail template and survey.surveys.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Survey is deployed on Cloudflare Workers with Workers Static Assets at https://survey.topolo.app, with shared landing, login, and callback pages on the browser surface plus the authenticated survey workspace after sign-in.

Failure Modes

  • a collector slug is published incorrectly or collides with another survey slug
  • public collector routes expose draft definitions instead of published survey data
  • response submission accepts malformed answers or writes outside the owning organization

Debugging

  • use the internal handbook for operational detail
  • verify the system registry entry before deployment or service-registration changes
  • smoke the published collector GET and POST routes after deploy when survey collection behavior changes

Use It

Open Topolo Survey for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-survey --json
topolo actions --service topolo-survey --json
topolo actions capabilities --service topolo-survey --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Survey and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloSurvey origin/staging 79a83af4e047 on 2026-07-27.

  • Reconciled this page against apps/TopoloSurvey origin/staging 93c41b6d7818 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloSurvey commits through 90eaab6; reviewed 383 commits since 2026-05-14, including 90eaab6 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 78df723 Stop blocking startup on i18n readiness; 92b6e48 Adopt canonical Topolo typography; 28e9fa0 Lazy load Survey shell.

  • Implemented the first production v1 with D1-backed surveys, public collectors, response capture, and response summary on 2026-04-23.

  • npm run typecheck

  • npm test

  • npm run build

  • npm run validate in TopoloDocs