Bytes

Documentation Map

• Application hub
• Application API surface
• Machine system JSON
• Machine application JSON
• applications/bytes

What It Is

Media and asset management surface for uploads, organization, review, and sharing.

Canonical documentation for Topolo Bytes lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Local product and operational docs have been retired in favor of the docs application.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/bytes.mdx

Source exists in repo: yes

Canonical Bytes coverage now lives in the docs application, the browser launcher lane now reads Auth-owned catalog data through same-origin /api/auth/* on the Bytes host, the browser callback delegates one-time `sso_code` exchange to the shared Auth client without exposing a legacy `/sso?token=` route or app-local `/sso/exchange` parser, accepts a compact exchanged-token payload, and SPA-navigates after auth update events so the memory-only token survives protected-route hydration. First-party embedded password login also completes through Bytes-owned router navigation after shared Auth token persistence. Closed lazy panels and modals are deferred until opened so `/browse` startup is not held behind hidden Suspense loaders. The worker now requires Topolo Auth validation for all operator bearer tokens with no Bytes-local JWT secret path. Bytes route permission checks evaluate unscoped route requirements against the `svc_r2_media_manager` service id so Auth-scoped grants match correctly. Bytes exposes `GET /api/widget` with the shared `@topolo/sdk` widget response contract for TopoloOne live workspace.

App API page: /reference/apps/topolo-bytes

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

API key scopes

Service permissions

api_keys:write, files:delete, files:read, files:write, folders:read, folders:write, sharing:read, sharing:write, storage:read

Data Ownership

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloBytes/apps/web/wrangler.toml -> bytes
• PlatformApplications/TopoloBytes/apps/worker/wrangler.toml -> r2-media-manager-worker

Build and deploy commands

• build — PlatformApplications/TopoloBytes/apps/desktop/package.json :: tsc -b && vite build
• build — PlatformApplications/TopoloBytes/apps/web/package.json :: VITE_API_BASE=https://r2-media-manager-worker.topolo.workers.dev tsc -b && vite build
• preview — PlatformApplications/TopoloBytes/apps/web/package.json :: vite preview
• deploy — PlatformApplications/TopoloBytes/apps/worker/package.json :: wrangler deploy
• deploy:dry-run — PlatformApplications/TopoloBytes/apps/worker/package.json :: wrangler deploy --dry-run --config wrangler.toml
• build — PlatformApplications/TopoloBytes/apps/worker/package.json :: tsc --noEmit
• build — PlatformApplications/TopoloBytes/package.json :: cd apps/web && pnpm run build
• build:desktop — PlatformApplications/TopoloBytes/package.json :: pnpm --filter desktop build
• build:all — PlatformApplications/TopoloBytes/package.json :: pnpm run --filter worker build && pnpm run --filter web build
• deploy:worker — PlatformApplications/TopoloBytes/package.json :: wrangler deploy --config apps/worker/wrangler.toml
• deploy:web — PlatformApplications/TopoloBytes/package.json :: cd apps/web && pnpm build && cp -r functions dist/ && npx wrangler pages deploy dist --project-name=bytes --branch=main
• deploy — PlatformApplications/TopoloBytes/package.json :: pnpm deploy:worker && pnpm deploy:web

Failure Modes

No default failure-mode heuristics are currently flagged for this system.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloBytes/apps/web/wrangler.toml
• PlatformApplications/TopoloBytes/apps/worker/wrangler.toml
• PlatformApplications/TopoloDocs/src/content/public/applications/bytes.mdx
• PlatformApplications/TopoloBytes/README.md
• PlatformApplications/TopoloBytes/apps/desktop/package.json
• PlatformApplications/TopoloBytes/apps/web/package.json
• PlatformApplications/TopoloBytes/apps/worker/package.json
• PlatformApplications/TopoloBytes/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-25

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.