Topolo Forms

Public overview of Topolo Forms, the Topolo general forms and public submission application.

publicverified 2026-07-31formsapplication

What It Is

Topolo Forms is the Topolo application for intake, waitlist, request, and structured form submission workflows. Operators manage form definitions in the authenticated workspace and can publish public submission links when needed.

Architecture

The application uses the shared Topolo shell and Topolo Auth for authenticated workspace access. A Cloudflare Worker serves the workspace, public published form 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://forms.topolo.app/
  • Shared login page at https://forms.topolo.app/login
  • Shared auth callback at https://forms.topolo.app/auth/callback
  • Authenticated workspace at https://forms.topolo.app/ once signed in
  • Public collector routes under https://forms.topolo.app/public/:slug, with visible form-loading content during direct-route startup
  • Authenticated admin APIs under /api/forms/*
  • Public submission APIs under /api/public/forms/:slug*

API Reference

The current production v1 exposes:

  • GET /api/health
  • GET /api/bootstrap
  • GET/POST /api/forms
  • GET/PATCH/DELETE /api/forms/:id
  • GET /api/forms/:id/submissions
  • POST /api/forms/:id/crm-sync
  • GET /api/forms/:id/summary
  • GET /api/public/forms/:slug
  • POST /api/public/forms/:slug/submissions

Auth and Permissions

Authenticated browser and API requests use Topolo Auth after resolving the topolo-forms service identity dynamically from its canonical slug. Signed-out operators land on the shared Topolo landing and login screens before entering the workspace. Public form routes do not require authentication and expose only published form definitions plus submission acceptance. Operators can manually sync a form's submissions into TopoloCRM after Forms dynamically resolves the topolo-crm service identity; CRM still enforces contact-write access for that operator.

Data Ownership

Topolo Forms stores organization-scoped form definitions and submissions in its own D1 database. Public submission routes write only into the owning organization for the published form slug being collected. CRM sync is explicit and manual; public submission does not automatically create CRM contacts, and submissions without a valid email are reported as skipped rather than sent to CRM.

Mobile Experience

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

Published permissions: workspace:read, workspace:write.

  • /forms uses /api/forms with the record.list template and forms.forms.list data source.
  • /forms/:id uses /api/forms/:id with the record.detail template and forms.forms.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 Forms is deployed on Cloudflare Workers with Workers Static Assets at https://forms.topolo.app, with shared landing, login, and callback pages on the browser surface plus the authenticated forms workspace after sign-in. Staging mirrors it at https://forms.stg.topolo.us with staging Auth, Notify, and public-base bindings.

Failure Modes

  • a published slug points operators or respondents to the wrong intake workflow
  • public submission routes expose draft form definitions or private workspace metadata
  • manual CRM sync is run by an operator without CRM contact-write access or against submissions without valid email addresses
  • general form collection drifts into a different product boundary before the core intake and waitlist flows are solid

Debugging

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

Use It

Open Topolo Forms 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-forms --json
topolo actions --service topolo-forms --json
topolo actions capabilities --service topolo-forms --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 Forms 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 apps/TopoloForms origin/staging b1704efe8709 on 2026-07-31: direct public and embedded collector routes render visible form-loading content while their lazy route loads. Reconciled this page with the canonical dynamic topolo-forms and topolo-crm service-slug identity resolution.

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

  • Reconciled this page against apps/TopoloForms origin/staging 22631b545d7e 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/TopoloForms commits through 6ee941e; reviewed 432 commits since 2026-05-14, including 6ee941e chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 870cacd Stop blocking startup on i18n readiness; 75cd70c Adopt canonical Topolo typography; a241e5a Roll out ui-kit capture startup split.

  • Verified Forms staging origin and Notify binding isolation on 2026-04-30.

  • Updated the public Forms overview on 2026-05-13 for runtime Auth app identity resolution from slugs topolo-forms and topolo-crm.

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

  • npm run typecheck

  • npm test

  • npm run build

  • npm run validate in TopoloDocs