Topolo Developers Handbook

What It Is

Topolo Developers is the authenticated developer portal at developers.topolo.app. It owns signed-in developer profile management, app submissions, and authenticated request intake.

Architecture

The application is a standalone React/Vite Pages surface in PlatformApplications/TopoloDevelopers. It does not own a separate backend. Instead, it uses the shared Topolo browser auth client and the Auth-owned developer-platform route family for all profile, submission, and request state.

TopoloOne owns the public overview/acquisition layer, but its primary developer CTA now hands users straight to developers.topolo.app/signup. Once a user is signed in, that flow continues into the root Topolo Developers portal.

Runtime Surfaces

• developer portal: developers.topolo.app
• public signup entrypoint: developers.topolo.app/signup
• upstream dependency: Topolo Auth
• operator review dependency: Topolo Admin

API Reference

Topolo Developers does not own a separate backend contract. The live route families are the Auth-owned developer-platform APIs:

• GET/PUT /api/developer-portal/profile
• GET/POST /api/developer-portal/app-submissions
• GET/POST /api/developer-portal/build-requests

Auth and Permissions

Topolo Developers uses the shared Topolo browser auth client and Auth session/refresh behavior. It should not introduce local account storage, local permission catalogs, or app-owned auth flows.

Data Ownership

Topolo Developers owns portal composition and authenticated submission UX. Topolo Auth owns developer records, app-submission persistence, and request persistence. Topolo Admin owns the operator review queues and status transitions.

Deployments

Topolo Developers deploys as the Cloudflare Pages project topolo-developers on developers.topolo.app.

The application must remain a first-class top-level app in PlatformApplications/TopoloDevelopers. It should not be re-nested under TopoloOne.

Failure Modes

• developers.topolo.app points at the wrong Pages project or stale bundle
• callback/deep-link routes fail because the SPA fallback is missing
• the portal drifts back into TopoloOne ownership instead of remaining a separate application
• authenticated requests fail because Auth route families or cookie-refresh behavior drift

Debugging

• verify the served Pages deployment first
• validate Auth session state and callback handling
• inspect the Auth developer-platform routes before changing portal UI assumptions

Change Log / Verification

• Added the dedicated public signup entrypoint at developers.topolo.app/signup on 2026-04-10 so TopoloOne marketing CTAs can hand off into the standalone portal without routing through multiple public developer-form pages
• Split Topolo Developers into its own first-class application on 2026-04-10 so developers.topolo.app is no longer treated as a nested TopoloOne app and now maps directly to PlatformApplications/TopoloDevelopers