Topolo Forecast

What It Is

Topolo Forecast is the finance-planning surface for cash-flow forecasting, P&L analysis, KPI tracking, and multi-scenario modeling.

Architecture

The system combines a browser app, worker/API surface, shared domain logic, and shared UI packages under a Cloudflare-oriented deployment model.

Runtime Surfaces

Use /systems/topolo-forecast for the current runtime inventory and host mapping.

API Reference

The current contract is curated in the docs platform rather than OpenAPI-backed. The main surface centers on forecasting models, scenarios, dashboard and KPI flows, and their Auth-protected runtime.

Auth and Permissions

Forecast relies on Topolo Auth for user and org access. Worker bearer requests are validated through Topolo Auth before Forecast-owned workspace authorization runs. Authenticated workspace membership no longer bypasses the Forecast service permission checks used by the worker routes, and the worker no longer ships a development-only auth escape hatch. Forecast browser callbacks delegate one-time sso_code redemption 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 page reload should return to Forecast instead of looking logged out while cookie refresh catches up. Forecast now also normalizes any missing Auth role claim to member during browser bootstrap, matching the canonical platform role ladder. The authenticated Forecast web workspace uses the shared TopoloAppShell for shell chrome, account menu, app launcher, command palette, theme toggle, sidebar collapse, and BugFix reporting. Forecast-specific workspace switching stays inside additive account-menu actions.

Data Ownership

Forecast owns financial models, scenarios, KPI calculations, and related planning data.

Workspace URLs and creation are organization-scoped. Two different organizations can use the same workspace slug, while each organization still keeps its own unique workspace URLs internally.

Deployments

Forecast deploys as a web-plus-worker application with shared packages and a Cloudflare deployment path. The current worker data bindings use forecast-db in production and forecast-db-staging in staging. The browser app keeps the shared BugFix reporter UI available while skipping the optional startup enabled-status probe.

Failure Modes

• stale Forecast metadata causes service-registration or environment drift
• web and worker deployments disagree on the active environment contract
• Auth configuration is bypassed or incorrectly stubbed

Debugging

Start with /systems/topolo-forecast, then verify the current environment contract and Auth wiring for the failing scenario flow.

Change Log / Verification

• Migrated the authenticated Forecast web workspace to the shared TopoloAppShell on 2026-04-25.
• Enabled same-tab browser session restore by default on 2026-04-23 so Forecast reloads remain signed in after successful Auth handoff or refresh.
• Corrected Forecast role normalization on 2026-04-24 so missing Auth role claims resolve to member during browser session bootstrap.
• Removed a non-critical Forecast browser startup warning on 2026-04-20 by skipping the optional BugFix enabled-status probe.
• Removed Forecast worker app-local JWT validation on 2026-04-18 so authenticated API requests depend on Topolo Auth validation before Forecast workspace authorization.
• Removed the Forecast /sso?token= browser bridge on 2026-04-18 so /auth/callback now relies on the shared Topolo browser auth client for code redemption
• Removed the remaining Forecast worker auth bypasses on 2026-04-11 so protected routes and workspace resolution always depend on Topolo Auth or API-key-backed access
• Replaced the remaining legacy Forecast D1 resource names on 2026-04-11 so the deployed worker metadata now points at forecast-db and forecast-db-staging
• Standardized Forecast worker permission enforcement on 2026-04-10 so the authenticated API no longer treats workspace membership alone as a sufficient grant
• Fixed Forecast’s shared auth callback handoff on 2026-04-07 so production /auth/callback consumes callback tokens directly again and no longer fails immediately on app-switch entry
• Restored Forecast’s shared suite app launcher on 2026-04-07 so the production app no longer opens the legacy Topolo Suite modal
• Standardized the Forecast-facing labels and frontend API defaults on 2026-04-07 so the live app routes against forecast-worker-production instead of the retired legacy host
• Added canonical Topolo Forecast coverage and retired repo-local Forecast docs on 2026-03-30