public active Last verified 2026-07-02

Topolo Chat

Public overview of the collaboration surface for channels, direct messages, meetings, guests, and remote-assist workflows.

Owners: collaboration
Source Repos: PlatformApplications/TopoloChat, system-apps/TopoloDocs
Systems: Topolo Auth, Chat
Tags: chat, meetings, collaboration

What It Is

Topolo Chat is the collaboration application for channels, direct messages, meetings, guest access, transcripts, future remote-assist workflows, and the shared cross-app Chat widget used by eligible Topolo apps.

Architecture

Chat combines a Cloudflare-native backend, a web client, realtime and meeting bindings, and optional desktop and mobile shells.

Runtime Surfaces

The primary public surface is https://chat.topolo.app; staging mirrors it at https://chat.stg.topolo.us with a staging-specific browser build so Auth and app-origin calls stay inside the staging installation. Assigned users can also access Chat through the shared @topolo-io/app-shell bottom-right widget, which mounts only after Auth confirms the topolo-chat service is assigned. The widget preserves lightweight UI continuity across first-party app switches while message data remains owned by Chat.

API Reference

The current contract is curated in the docs platform and centers on channels, DMs, uploads, meetings, guests, notifications, notes, audit events, remote-assist transport, and compact widget endpoints under /api/widget/chat.

Auth and Permissions

Topolo Chat uses Topolo Auth for organization-scoped workspace access. Protected workspace bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser login handoff, SSO callback-code redemption, and returning-user cookie hydration delegate to the shared Topolo Auth client after Chat resolves the Auth-owned topolo-chat service slug at runtime, while guest meeting entry remains intentionally separate from normal workspace membership. Workspace-admin paths such as API key management now require explicit Chat service permissions instead of relying on local role-name heuristics. For first-party Topolo users, /login renders Chat’s branded shared LoginPage directly in the Chat shell. Hosted Auth login pages are reserved for third-party/provider handoff, not the default credential form.

Data Ownership

Chat owns organization-scoped workspace, membership, channel, DM, message, upload, meeting, guest, transcript, audit, remote-assist session state, and the runtime projection of Agent personas used by the cross-app widget. Its bootstrap API returns organization, organizationPolicies, and organizationMembers as the canonical tenant payload keys.

Deployments

Chat deploys as a Cloudflare-backed collaboration app with optional desktop and mobile client shells.

Failure Modes

meeting join token flow drifts from guest or mobile launch flows
realtime or Durable Object bindings are unavailable
guest entry is mistakenly treated as normal workspace auth

Debugging

Start with /systems/topolo-chat, then separate workspace-auth issues from guest and meeting-launch issues before debugging deeper.

Change Log / Verification

Reconciled workspace verification on 2026-06-28 against apps/TopoloChat commits through d487fd0; reviewed 58 commits since 2026-06-25, including d487fd0 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 910917a chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b577a36 Stop blocking startup on i18n readiness; 8ddd18d Remove meeting join scaffold overlay.
Persisted lightweight cross-app Chat widget UI state through Auth preferences on 2026-07-02 while keeping message content in Chat.
Added cross-app Chat widget ownership and widget API coverage on 2026-06-18.
Renamed Chat’s local tenant-scoping API and D1 columns from workspace to organization on 2026-05-10.
Removed hard-coded Chat Auth app IDs on 2026-05-13 so login, callback preboot, worker auth validation, notification events, widget output, API-key management, and seed intake use slug-resolved app identity.
Verified Chat staging origin isolation on 2026-04-30.
Removed Chat’s hosted Auth redirect from /login on 2026-04-20 so first-party users sign in through the branded embedded shared LoginPage.
Removed the Chat worker’s residual local TOPOLO_JWT_SECRET handoff on 2026-04-18 so protected workspace bearer-token requests validate through Auth.
Delegated Chat web login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18.
Added service-scoped Auth cookie hydration to Chat startup on 2026-04-18 so returning users can enter without a full hosted login redirect.
Standardized Chat admin permission checks on 2026-04-10 so API key management now follows the shared Auth permission model instead of local role checks
Standardized the public product label to Chat across the web shell, workspace bootstrap text, and meeting handoff flows on 2026-04-04
Added canonical Topolo Chat coverage and retired repo-local collaboration docs on 2026-03-30