Topolo Roadmapper | Topolo Docs

What It Is

Topolo Roadmapper is the project and roadmap planning application in the Topolo portfolio. It organizes work as projects, roadmaps, and nested roadmap items.

Architecture

Roadmapper combines a web application for project planning with a worker-backed API that owns project, roadmap, and roadmap-item persistence.

Runtime Surfaces

Roadmapper web application
Roadmapper API worker
Topolo Auth for identity and tenant scoping

AI Onboarding

Roadmapper now supports an AI-first project creation path on /projects/new.

Users can keep multiple AI roadmap chats in progress before any project is created.
Each chat keeps its own conversation transcript, editable roadmap draft, and stage until a team decides to finalize it.
Draft and ready chats can be deleted if the team wants to discard a creation attempt before it becomes a project, and the app offers a short in-app undo window before the delete is finalized.
The AI creation screen is chat-first: the conversation fills the main workspace and the hierarchy preview or editor lives on a separate draft tab instead of a pinned side panel.
The generated draft is directly editable before approval so teams can refine names, dates, status, ownership, and nested structure without leaving the flow.
Finalizing one chat creates the project, its roadmaps, and the nested roadmap items in one step.

Planning Sessions

Roadmapper now exposes persisted planning-session endpoints for existing projects. Those sessions are now surfaced directly on each project page as scoped project chats. Teams can open one thread for the full project, one roadmap, or one roadmap-item branch, keep changes isolated inside that scope, and only apply them after confirmation.

API Surface

The AI onboarding flow now includes persisted chat-session endpoints plus the legacy direct draft endpoints:

GET /projects/ai/status returns whether AI onboarding is enabled in the current environment.
GET /projects/ai/sessions lists saved pre-project AI roadmap chats.
POST /projects/ai/sessions creates a new AI roadmap chat.
GET /projects/ai/sessions/:id loads one saved AI roadmap chat.
PATCH /projects/ai/sessions/:id persists direct edits to the current draft.
DELETE /projects/ai/sessions/:id removes one draft or ready AI roadmap chat.
POST /projects/ai/sessions/:id/turns continues one AI roadmap chat, updates its draft, and tolerates common provider field aliases or fenced JSON wrappers before surfacing a generation failure.
POST /projects/ai/sessions/:id/apply finalizes one AI roadmap chat into a real project.
POST /projects/ai/draft accepts conversation turns plus the current draft and returns { assistantMessage, draft }.
POST /projects/ai/apply accepts the approved draft and creates the full hierarchy.

Roadmapper also adds planning-session and presentation endpoints:

GET /projects/:id/planning/sessions
POST /projects/:id/planning/sessions
GET /planning/sessions/:id
DELETE /planning/sessions/:id
POST /planning/sessions/:id/turns
GET /planning/sessions/:id/revisions
POST /planning/sessions/:id/scenarios
POST /planning/sessions/:id/apply
POST /projects/:id/presentations/generate
POST /roadmaps/:id/presentations/generate
POST /items/:id/presentations/generate
GET /presentations/:id
PATCH /presentations/:id
POST /presentations/:id/export

Manual project creation through POST /projects remains available and now persists the submitted project status.

Planning sessions now carry explicit scope metadata:

project sessions can revise and apply the full hierarchy
roadmap sessions can update only the selected roadmap or the roadmap plus its descendants
item sessions can update only the selected item or that item plus its descendants

When a roadmap-scoped or item-scoped chat is applied, siblings outside the selected scope are preserved.

API Reference

Roadmapper currently uses curated application documentation plus the system registry entry for route and deployment coverage. The AI onboarding routes live under the /projects API surface.

Structured Draft Contract

The AI draft uses one shared structure across generation, preview, and apply:

project with name and optional description
roadmaps[] with name, optional description and dates, plus nested items
items[] with optional status, priority, dates, assignee, and recursive children

The apply path rejects drafts with invalid date ordering, duplicate roadmap names, more than 10 roadmaps, or more than 250 total items.

Auth and Permissions

Roadmapper relies on Topolo Auth for identity and org scoping. AI onboarding endpoints are protected and operate within the caller’s tenant context. Roadmapper browser login handoff and one-time sso_code callback redemption delegate to the shared @topolo/auth-client package. Direct bearer-token callback URLs and /sso?token= bridge routes are not supported. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should return to the Roadmapper workspace rather than appearing signed out while cookie refresh catches up. Roadmapper now also normalizes any missing Auth role claim to member, and its vendored middleware limits platform-wide bypass to platform_super_admin and platform_admin users in the Auth admin org. Roadmapper API authorization fails closed when Auth validation is unavailable; local JWT claim fallback is not part of the supported production contract. The API worker now requires Topolo Auth validation without a Roadmapper-local JWT secret handoff or vendored local HS256 verifier.

Data Ownership

Roadmapper owns persisted pre-project AI roadmap chats, project records, roadmap records, and roadmap-item records, including the hierarchy created when an approved AI draft is applied. It now also owns planning sessions, revisions, scenarios, and presentation decks generated from project state.

Presentation Delivery

Roadmapper can now generate stakeholder-ready presentations from live planning state. Each deck is available as a responsive web presentation and can also be exported to PPTX from the same slide specification. Decks include summary copy, metrics, roadmap timeline content, risks, and next actions and remain editable after generation.

Presentation generation is available from:

the full project
an individual roadmap
a roadmap-item branch and its descendants

Roadmapper now supports project, roadmap, and roadmap-item guest links. Links can be time-limited or non-expiring and now support two access modes:

view for read-only review
edit for authenticated guest item edits inside the shared scope

Editable guest links require sign-in so Roadmapper can attribute every item change to a guest identity for logging and audit.

Project and roadmap guest links can optionally allow branch drill-down into child roadmap items. Item guest links always open a dedicated shared branch surface rooted at the selected roadmap item and its descendants.

Invite delivery now uses the Roadmapper API instead of mailto: links. Email invites are sent server-side through Nexus using the Resend provider, and WhatsApp invite composition remains available when the deployment is configured for it.

Project guest links open a dedicated project guest surface where viewers can step from the full project into a roadmap and then into a child branch when navigation permission is enabled. Roadmap and roadmap-item guest views now expose full item titles and descriptions in-page through a guest inspector instead of relying on truncation.

Feature Enablement

AI draft generation now routes through Nexus instead of calling OpenAI directly from the Roadmapper worker.

The AI path is considered enabled when the Roadmapper API can reach Nexus and the current request has auth context that Nexus can verify. If Nexus is unavailable for the current environment, the web app falls back to the manual project creation path. The Roadmapper API now treats https://nexus.topolo.app as the Nexus dashboard origin and https://topolo-nexus-gateway.topolo.workers.dev as the default Nexus gateway origin when no explicit NEXUS_GATEWAY_URL override is configured. Plain-text or HTML upstream failures still surface as provider errors instead of a JSON parse exception in the browser.

Deployments

Roadmapper deploys as a web app plus API worker surface. AI draft generation and notification email delivery now depend on Nexus gateway connectivity instead of app-local provider keys. The web app now waits for an explicit refresh before a new service worker takes control so deploys do not strand users between old and new hashed asset bundles. The production web build must identify itself to Topolo Auth with the canonical Roadmapper service id srv_I0z_mOMxdFVa. If the browser bundle is built with a stale service id, standard tenant users can be sent back to /login even while super-admin accounts continue to work. The browser auth client also lets cookie-backed Auth refresh calls finish instead of client-aborting them mid-flight. Auth rotates the refresh cookie on success, so aborting that request can leave the next page reload with a stale refresh token.

Failure Modes

missing or unreachable Nexus connectivity leaves AI onboarding disabled or unavailable
interrupted browser Auth refresh calls can invalidate the current refresh cookie for the next reload
saved AI roadmap chats can remain in progress across multiple draft stages before one is finalized
invalid model output causes a server-side repair retry and then a typed failure
apply validation blocks malformed or oversized drafts before any writes
if apply fails after project creation starts, the worker deletes the new project so partially created roadmaps and items are not left behind
planning-session apply can fail if the generated document has no roadmaps or items
presentation export depends on the generated deck and the browser-side PPTX export path being available

Debugging

confirm GET /projects/ai/status returns enabled: true
verify the Roadmapper API can reach https://topolo-nexus-gateway.topolo.workers.dev or the configured NEXUS_GATEWAY_URL with the caller’s auth context
verify the Roadmapper web app and API are pointed at the same environment
verify the production browser bundle is using the canonical Auth service id srv_I0z_mOMxdFVa, not a stale srv_roadmapper_web value
if sign-in appears to succeed and then returns to /login, inspect the /auth/callback handoff before treating the issue as a missing tenant entitlement
if AI generation fails with an OpenAI response_format schema error, verify the Roadmapper structured-output schema is using required nullable fields for values that are optional in the stored draft model
if AI generation fails after the provider returns JSON, inspect whether the model emitted a tree-shaped draft instead of the canonical project and roadmaps structure
inspect the approved draft payload if apply validation rejects the hierarchy

Change Log / Verification

Enabled same-tab browser session restore by default on 2026-04-23 so Roadmapper reloads remain signed in after successful Auth handoff or refresh.
Corrected Roadmapper role normalization on 2026-04-24 so missing Auth role claims resolve to member, while platform-wide bypass in the vendored middleware now follows the canonical platform_* roles in the Auth admin org.
Removed the Roadmapper /sso?token= browser bridge and app-local login URL construction on 2026-04-18 so login handoff and /auth/callback code redemption now rely on the shared Topolo browser auth client
Hardened Roadmapper API authorization on 2026-04-18 so protected routes require Auth validation and no longer trust local JWT claims as an outage fallback; commit 2f8a834 deployed worker version a9282e78-e572-48c0-81d5-1bfda6134e95
Removed the remaining Roadmapper API local JWT secret handoff on 2026-04-18
Corrected the Roadmapper production web service id on 2026-04-12 so standard tenant users are no longer evaluated against the stale srv_roadmapper_web Auth catalog entry during /refresh and API requests
Corrected the Roadmapper browser callback flow on 2026-04-12 so login completion no longer depends on an immediate Auth /refresh, avoiding callback-to-login loops when the refresh cookie is not yet usable
Corrected the Roadmapper Nexus fallback host on 2026-04-12 so AI turns now default to the Nexus gateway worker rather than the Nexus dashboard origin, and upstream edge failures still surface as typed provider errors instead of JSON parse errors in the browser
Moved Roadmapper AI onboarding to the working Nexus xAI model on 2026-04-12 after the configured OpenAI path began failing production requests with unsupported_country_region_territory
Corrected the Roadmapper structured-output schema on 2026-04-12 so AI onboarding turns use required nullable fields where the stored draft model treats values as optional
Hardened Roadmapper AI-response normalization on 2026-04-12 so tree-shaped provider output is coerced into the stored draft hierarchy before final validation
Surfaced scoped project chats on 2026-04-12 so each project page now exposes persistent project, roadmap, and item planning threads with scope-preserving apply behavior
Added deletion for non-finalized AI onboarding chats on 2026-04-12 so discarded pre-project conversations can be removed from the creation surface
Tightened the Roadmapper web update path on 2026-04-12 so service-worker updates no longer switch clients immediately during hashed-asset deploys
Added persisted multi-chat AI onboarding on 2026-04-12 so teams can keep multiple roadmap chats in progress and finalize only the selected one into a real project
Expanded guest sharing on 2026-04-08 with item-level links, view or edit access modes, authenticated guest edits with audit logging, server-side Resend invites, and guest item inspector surfaces for full title and description visibility
Tightened the Roadmapper in-app command palette shortcut on 2026-04-08 so Cmd/Ctrl+K no longer intercepts the shared Cmd/Ctrl+Shift+K app-switcher shortcut
Added project guest sharing and scoped project, roadmap, or branch presentation generation on 2026-04-07
Refreshed the main project, roadmap, item, share, and presentation surfaces on 2026-04-07 to replace the heavy flat card treatment with lighter gradient panels
Expanded roadmap guest sharing on 2026-04-07 with non-expiring links, optional child-branch navigation, and invite actions in the share modal
Stabilized dependency-overlay registration on 2026-04-07 so timeline/detail views no longer hit a React nested-update loop while rendering dependency bars
Verified editable AI draft review, persisted planning sessions, shared timeline rendering, and responsive presentation/PPTX delivery on 2026-04-07
Verified against the current AI onboarding, apply semantics, and project-create flow on 2026-03-29