Topolo Social Studio

What It Is

Topolo Social Studio is a hybrid desktop and web production surface for planning, generating, and managing social-first creative work.

Architecture

The system combines a marketing/web shell, an authenticated API worker, a queue worker for generation orchestration, and a macOS desktop shell. Auth manages identity and Nexus now owns the external AI provider invocation path.

Studio requires the Topolo Brand service in every deployed API environment. Explicitly selected or workspace-mapped kits must resolve through Brand and store the exact immutable version used for planning and generation; an unavailable Brand service fails closed, while creating a project without selecting a kit remains an explicit product choice. Studio no longer owns a second mutable brand-kit table or mutation surface. Composition and export contracts support square, landscape, 4:5 portrait, and 9:16 portrait channel ratios.

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

The primary public surface is https://studio.topolo.app, backed by Cloudflare-hosted worker runtimes and a local desktop shell for creator workflows.

API Reference

Use /systems/topolo-social-studio for the current runtime and worker route inventory. Provider-facing AI operations are invoked through Nexus rather than documented as direct vendor contracts here.

Auth and Permissions

Studio relies on Topolo Auth for session verification and workspace access. Its web and desktop shells now use the shared Topolo browser auth client through a thin application wrapper, including login handoff, service-aware cookie refresh, single-pass callback-code redemption, and logout propagation. Workspace APIs now require the matching Social Studio service permission before workspace membership, owner, or export-policy rules can narrow access, and local workspace ownership is no longer inferred from broader Auth role names. The app owns the stable topolo-social-studio Auth slug and resolves the concrete app id at runtime, including the browser shell identity used by login and shared app chrome. Protected bootstrap preserves the raw Auth role separately, resolves the caller's Studio workspace membership when workspace state is available, and returns the local owner/member role from that membership in the shell payload. Improve Topolo stays inside the authenticated account menu rather than a standalone floating control. AI-assisted routes preserve org and user attribution when they invoke Nexus-backed provider workflows.

Data Ownership

Topolo Auth owns workspace identity and accessible-workspace listing. Studio owns workspace-scoped projects, briefs, creative plans, scenes, assets, membership policy, and generation state. Nexus owns the provider keys and platform-level usage attribution for supported AI vendors.

Mobile Experience

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

Published permissions: workspace:read, workspace:write, social-studio:projects:read, social-studio:projects:write.

• /app/projects uses /api/workspaces/:workspaceSlug/projects with the record.list template and studio.projects.list data source.
• /app/projects/:projectId/brief uses /api/workspaces/:workspaceSlug/projects/:projectId/planning with the record.detail template and studio.projects.detail data source.
• /app/projects/:projectId/review uses /api/workspaces/:workspaceSlug/projects/:projectId/sync with the activity.timeline template and studio.projects.review 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

Studio deploys as a hybrid surface with separate marketing/web, API worker, queue worker, and desktop packaging flows. The Topolo-owned staging mirror runs the web surface at studio.stg.topolo.us and the API worker at studio-api.stg.topolo.us.

Failure Modes

• auth context missing for protected workspace routes
• queue worker unavailable for generation processing
• Nexus connectivity or provider configuration missing for AI-assisted planning or generation
• Brand service binding or service identity missing, or a selected canonical kit no longer resolving

Debugging

Start with /systems/topolo-social-studio for deployment and runtime detail. If AI planning or generation fails, verify the app can reach Nexus and that the expected org/user context is being forwarded.

Use It

Open Social Studio 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-social-studio --json
topolo actions --service topolo-social-studio --json
topolo actions capabilities --service topolo-social-studio --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 Social Studio 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 staging denial behavior on 2026-07-31 against apps/TopoloSocialStudio 2536a6d3567f: protected bootstrap now returns the explicit not-found contract when no Studio workspace grant exists instead of failing with an internal error.

• Verified the native_capability mobile experience contract and its 3 published route(s) against apps/TopoloSocialStudio origin/staging a76f99cb0794 on 2026-07-27.

• Reconciled workspace verification on 2026-06-28 against apps/TopoloSocialStudio commits through ed29d3d; reviewed 324 commits since 2026-05-14, including ed29d3d chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a4b7129 Split Social Studio authenticated shell bundle; 62c45e3 Adopt canonical Topolo typography; d8cb398 Roll out ui-kit capture startup split.

• Moved Social Studio app identity to runtime slug resolution on 2026-05-13 so public web, desktop, and API surfaces no longer ship concrete app identifiers.

• Removed Social Studio's standalone floating Improve Topolo controls on 2026-05-12 so the web and desktop shells keep the report workflow in the authenticated account menu.

• Verified the isolated Topolo Staging deployment on 2026-04-30; studio.stg.topolo.us and studio-api.stg.topolo.us/health returned HTTP 200.

• Corrected the Social Studio callback effect on 2026-04-20 so successful Auth handoff no longer stalls on the callback screen after exchanging the one-time code.

• Corrected Social Studio bootstrap role scoping on 2026-04-24 so the API worker now resolves workspace membership for the authenticated org workspace, returns the local owner/member role in bootstrap, and still preserves the raw Auth role separately.

• Delegated Social Studio login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18.

• Stopped rewriting Social Studio workspace ownership from cross-app Auth role names on 2026-04-11 so the public worker contract now preserves Auth role diversity while keeping workspace owner rules local to Studio

• Standardized Social Studio workspace-route permission enforcement on 2026-04-10 so protected APIs no longer rely on workspace membership or owner checks alone

• Reconfirmed on 2026-04-07 that Social Studio is the sole live Studio-branded application at studio.topolo.app

• Standardized Social Studio browser auth on the shared Topolo auth client on 2026-03-31

• Standardized the public product label to Social Studio across the web and desktop authenticated shells and recorded the production marketing-web Worker target in CloudControl on 2026-04-04

• Added canonical system coverage and documented the Nexus-backed AI integration path on 2026-03-29