Topolo Roadmapper

Documentation Map

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

What It Is

Roadmap and project management application in the Topolo portfolio with AI onboarding, scoped project-chat planning sessions, hierarchy-wide guest sharing and guest edit auditability, and narrative presentation delivery.

Canonical documentation for Roadmapper lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Product flows, AI onboarding behavior, notification delivery boundaries, deployment guidance, and operational details are canonical in the docs application rather than in repo-local markdown.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloRoadmapper/package.json

Source exists in repo: yes

Current contract coverage is curated rather than OpenAPI-backed, and the browser launcher lane now reads Auth-owned catalog data through same-origin /api/auth/* on the Roadmapper host using the current Auth organization and active context. The browser login handoff, embedded password-login surface, and Auth SSO one-time sso_code callback redemption delegate to the shared Topolo auth client, direct bearer-token callback URLs or /sso?token= bridge routes are not supported, Roadmapper keeps same-tab sessionStorage access-token restore enabled by default after login and refresh so normal reloads do not appear logged out before cookie refresh completes, Roadmapper's vendored @topolo/ui-kit snapshot must stay synchronized with the canonical platform package, the API worker now exposes authenticated `GET /api/widget` for TopoloOne live workspace, and protected API routes now require Topolo Auth validation plus a validated organization context with no Roadmapper-local JWT secret handoff or vendored local HS256 verifier.

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

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, projects:read, projects:write, reports:read, reports:write, roadmaps:read, roadmaps:write, settings:read, settings:write

Data Ownership

Deployments

Deployment environments: dev, staging

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloRoadmapper/apps/api/wrangler.toml -> topolo-production-roadmapper
• PlatformApplications/TopoloRoadmapper/apps/web/wrangler.toml -> roadmapper

Build and deploy commands

• build — PlatformApplications/TopoloRoadmapper/package.json :: pnpm -r run build
• deploy:api — PlatformApplications/TopoloRoadmapper/package.json :: pnpm -C apps/api run deploy
• deploy:api:staging — PlatformApplications/TopoloRoadmapper/package.json :: pnpm -C apps/api run deploy:staging
• deploy:web — PlatformApplications/TopoloRoadmapper/package.json :: pnpm -C apps/web run build && pnpm -C apps/web run deploy
• deploy:staging — PlatformApplications/TopoloRoadmapper/package.json :: pnpm run deploy:api:staging
• deploy — PlatformApplications/TopoloRoadmapper/apps/api/package.json :: wrangler deploy
• deploy:staging — PlatformApplications/TopoloRoadmapper/apps/api/package.json :: env -u CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler deploy --env staging
• deploy:dry-run — PlatformApplications/TopoloRoadmapper/apps/api/package.json :: wrangler deploy --dry-run --config wrangler.toml
• build — PlatformApplications/TopoloRoadmapper/apps/api/package.json :: tsc --noEmit
• prebuild — PlatformApplications/TopoloRoadmapper/apps/web/package.json :: pnpm -C ../../../packages/topolo-ui-kit install --frozen-lockfile=false && pnpm -C ../../../packages/topolo-ui-kit run build && pnpm -C ../../packages/ui install --frozen-lockfile=false && pnpm -C ../../packages/ui run build
• build — PlatformApplications/TopoloRoadmapper/apps/web/package.json :: vite build
• deploy — PlatformApplications/TopoloRoadmapper/apps/web/package.json :: pnpm run build && npx wrangler pages deploy dist --project-name roadmapper
• preview — PlatformApplications/TopoloRoadmapper/apps/web/package.json :: vite preview
• build — PlatformApplications/TopoloRoadmapper/packages/domain/package.json :: pnpm exec tsc --project tsconfig.json
• build — PlatformApplications/TopoloRoadmapper/packages/infra/package.json :: npx tsc --project tsconfig.json

Failure Modes

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

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloRoadmapper/apps/api/wrangler.toml
• PlatformApplications/TopoloRoadmapper/apps/web/wrangler.toml
• PlatformApplications/TopoloRoadmapper/package.json
• PlatformApplications/TopoloRoadmapper/README.md
• PlatformApplications/TopoloRoadmapper/apps/api/package.json
• PlatformApplications/TopoloRoadmapper/apps/web/package.json
• PlatformApplications/TopoloRoadmapper/packages/domain/package.json
• PlatformApplications/TopoloRoadmapper/packages/infra/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-28

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