TopoloSpaces

What It Is

TopoloSpaces gives a Topolo organization a private spatial asset library. Teams can import existing .sog, .ply, and .zip splat exports, track processing state, view ready SOG scenes, annotate spaces, and publish optional unlisted links.

Architecture

The app is Cloudflare-first: Worker APIs, D1 metadata, R2 asset storage, Queues for import processing, Workflow orchestration, and CloudControl container-processing metadata. PlayCanvas renders optimized SOG assets in the browser.

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

Production host: https://spaces.topolo.app.

Staging host: https://spaces.stg.topolo.us.

API Reference

Authenticated users work through the app UI and service-owned /api/* routes. Public routes only expose explicitly enabled unlisted links.

Auth and Permissions

Topolo Auth controls access through the stable topolo-spaces service slug. Spaces are private by default and scoped to the authenticated organization.

Data Ownership

TopoloSpaces owns spatial metadata, assets, processing records, annotations, public-link state, and events. V1 does not capture raw photos or videos and does not train new splats from source media.

Mobile Experience

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

Published permissions: workspace:read, workspace:write.

• /spaces uses /api/spaces with the record.list template and spaces.spaces.list data source.
• /spaces/:id uses /api/spaces/:id with the record.detail template and spaces.spaces.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

Production uses Worker topolo-spaces. Staging uses Worker topolo-spaces-staging.

Failure Modes

• Imported PLY/ZIP files wait for the processor lane before they are viewable.
• Unlisted public links work only after a ready runtime SOG exists.
• Disabling publishing returns the space to private-only access.

Debugging

Use the internal TopoloSpaces handbook for operator checks, D1/R2 inspection, CloudControl target resolution, and staging QA persona verification.

Use It

Open TopoloSpaces 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-spaces --json
topolo actions --service topolo-spaces --json
topolo actions capabilities --service topolo-spaces --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 TopoloSpaces 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/TopoloSpaces origin/staging e2021b370f0d on 2026-07-27.

• Reconciled this page against apps/TopoloSpaces origin/staging 77add00b796c 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/TopoloSpaces commits through 7dbee1b; reviewed 323 commits since 2026-05-14, including 7dbee1b chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a600b90 Stop blocking startup on i18n readiness; 4f5f6a4 Adopt canonical Topolo typography; 5c22238 Split Spaces shell startup bundle.

• 2026-05-12: TopoloSpaces v1 documented as an import-first private business app.