Topolo Forecast

Public overview of the forecasting product for cash-flow, P&L, KPI, and multi-scenario planning workflows.

publicverified 2026-07-29forecastingfinanceplanning

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.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

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.

Workspace reads come from the shared Topolo workspace service rather than a Forecast-specific workspaces.get action. Forecast retains only its finance-specific workspace operations, including active-scenario selection and guarded archive behavior.

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 resolves the concrete environment-specific app id from the topolo-forecast service slug at runtime. The Worker uses Auth /api/services/by-slug/topolo-forecast before service-scoped Auth validation, widget responses, API-key management, and seed validation; the browser uses the same slug lookup before service-scoped Auth handoff and API headers. Forecast browser callbacks delegate one-time sso_code redemption to the shared @topolo-io/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 account-menu BugFix reporting. Forecast-specific workspace switching stays inside additive account-menu actions, and public landing, login, callback, and shared-workspace pages do not mount standalone BugFix controls.

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.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /dashboard/workspace, its offline policy is read_through_cache, and it requires organization context.

Published permissions: settings:read, settings:write, forecasts:read, forecasts:write, workspace:read, workspace:write, workspace:delete.

  • /dashboard/workspace uses /api/widget with the record.detail template and forecast.widget.get data source.
  • /chart-of-accounts uses /api/v1/:workspace/coa with the record.list template and coa.get data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

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 from the authenticated account menu 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.

Use It

Open Topolo Forecast for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-forecast --json
topolo actions --service topolo-forecast --json
topolo actions capabilities --service topolo-forecast --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Forecast and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Reconciled the reachable public-share route and platform-owned workspace boundary through apps/TopoloForecast origin/staging a91d74ee55b6 on 2026-07-29. The unused /v1/shared/:token/info route is no longer part of the runtime contract.

  • Reconciled the platform-owned workspace read boundary and removed the retired Forecast workspaces.get declaration on 2026-07-28.

  • Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloForecast origin/staging 233dfcde7985 on 2026-07-27.

  • Reconciled this page against apps/TopoloForecast origin/staging 853d715584c7 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloForecast commits through ae7551c; reviewed 98 commits since 2026-06-18, including ae7551c chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); ddb7f84 Split Forecast startup auth bundle; cc8e31f Adopt canonical Topolo typography; 4a55ce9 Split Forecast shell startup bundle.

  • Removed Forecast's standalone public-route BugFix control on 2026-05-12 so Improve Topolo remains an authenticated account-menu action.

  • Removed hardcoded concrete app ids from Forecast web and worker runtime paths on 2026-05-13 so app identity is resolved through Auth by slug per environment.

  • 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