Skip to main content

Master Roadmap

This is the ordered delivery plan from the current repo baseline to a launchable developer-facing starter.

Use this as the primary sequencing document.

How To Use This File​

  • work top to bottom
  • do not add major new surface area before the current launch-tier baseline is trustworthy
  • if a task expands, split it into a focused feature spec before implementation
  • if something is intentionally deferred, say so instead of leaving it implied

Phase 0: Reality Lock​

Goal:

  • planning and positioning match the starter that actually exists

Status:

  • in progress

Order:

  • audit the codebase against the current docs baseline
  • reset current-state.md to the actual starter reality
  • replace the stale active priority baton
  • replace the stale legacy roadmap
  • align supporting app and product docs anywhere they still imply the wrong roadmap or product shape

Phase 1: Launch-Critical Hardening​

Goal:

  • make the current starter safe to trust for real B2B2C SaaS work

Order:

  • browser-validate org bootstrap, portal access, and platform bootstrap flows end to end
  • browser-validate impersonation and portal support handoff end to end
  • browser-validate billing checkout, plan change, cancellation, reactivation, and portal-availability edge cases
  • browser-validate API credential issuance, webhook test and retry, and export request and download flows
  • finish rate-limit enforcement on the remaining sensitive callsites
  • tighten audit and abuse-protection coverage where hardening still depends on convention more than enforcement
  • confirm retention and cleanup behavior for impersonation, support sessions, and webhook history with realistic data

Phase 2: Billing And Operations Polish​

Goal:

  • remove the remaining operational weak spots that would block real starter use
  • sharpen billing depth, operational support tooling, and impersonation/support workflows

Billing Depth​

  • ship seat-count enforcement: per-plan seat caps, member-add gates, and over-seat warnings in org and platform
  • ship usage-limit enforcement: plan-tier limits for API keys, webhooks, exports, and audit-log retention with in-app feedback at threshold
  • implement downgrade behavior: seat and feature reconciliation when a plan is downgraded or cancelled, with clear in-app messaging and admin override path
  • replace legacy shared-provider-customer billing records with org-scoped billing identities or document the permanent repair path
  • ship minimum launch-tier in-app billing visibility: current plan, provider subscription status, portal availability, and explicit repair states for missing customer, missing subscription, shared customer, price mismatch, and provider-portal outages
  • document payment-method, invoice, receipt, and tax-detail management as provider-portal-only until a later billing depth phase justifies bringing them in-app
  • add platform-admin billing repair tooling: manual plan override, seat reset, billing-identity re-link, and provider-state reconciliation panel

Operational Support Polish​

  • tighten impersonation lifecycle: clear session indicators, explicit exit from impersonation state, and platform-side audit for every impersonation event
  • tighten portal support handoff: support-session start and end with member-visible access notice, session-scope limits, and expiry
  • review incident-notice resolution flow from create through dismiss through audit-log trail end to end
  • review premium-operations workflows for consistency across API access, webhooks, audit logs, and exports
  • tighten org and platform governance guidance around maintenance mode, feature flags, and incident notices

Phase 3: Starter Bootstrap And Developer Experience​

Goal:

  • make the repo easy to branch, understand, and stand up quickly

Order:

  • verify clean-start bootstrap from environment setup through first successful app run
  • tighten seed and demo flows so the repo showcases real starter value immediately
  • document required environment variables, auth bootstrap, billing setup, and deployment prerequisites clearly
  • document branding, theming, and safe extension points for downstream apps
  • verify that first-run org, portal, and platform states are coherent without manual repair work

Phase 4: Productization And Honest Market Surface​

Goal:

  • make the starter marketable without exaggeration

Order:

  • publish a clear "what you get today" breakdown grounded in shipped functionality
  • document what is intentionally not in the current tier: enterprise SSO, SCIM, broader API platform, and other later-tier work
  • prepare demo content, screenshots, and walkthrough paths that map to real flows already in the repo
  • define launch-tier vs future premium or enterprise boundaries
  • make sure docs, app copy, and marketing claims use the same feature language

Phase 5: API Productization And Extensibility​

Goal:

  • make the external API surface credible and the internal extension points reliable enough for downstream apps

API Productization​

  • define the full external API surface: resource shape, authentication, error envelope, and pagination contract
  • add key scopes: scope each API credential to a specific resource+verb set, enforce at the callsite, and surface scope selection in org settings
  • add API usage logs: per-key request counts, last-used timestamps, error rates, and quota headroom visible in org settings and platform admin
  • add a versioning story: choose a versioning mechanism (header or path), document the deprecation policy, and apply it to the existing endpoint
  • publish external API docs: auto-generated or hand-authored, grounded in real response shapes, and linked from org settings

Extensibility​

  • formalize the webhook event catalog: named event types with stable schemas, documented payload shapes, and changelog
  • add background job patterns: at least one documented, repeatable pattern for scheduled jobs, async work queues, and job-status visibility
  • tighten feature flag ergonomics: org-level and platform-level flag resolution with clear precedence, audit trail, and consistent in-app behavior
  • define notification and event pipeline shape: what triggers a notification, what data is carried, how downstream apps hook into or extend the pipeline
  • document safe extension points for downstream forks: which hooks, events, and background patterns are stable vs internal

Phase 6: Enterprise Readiness​

Goal:

  • only pursue enterprise-tier work if the starter shows real adoption or a clear sales motion justifies it

Identity And Provisioning​

  • evaluate enterprise SSO demand: determine whether OIDC or SAML is the right first implementation target given actual customer requests
  • implement enterprise SSO: org-level OIDC provider configuration, JIT provisioning on login, and SSO-enforced session policy
  • evaluate SAML if OIDC alone does not satisfy the target enterprise buyer segment
  • evaluate SCIM provisioning: automated user add/remove/suspend against org membership, priority-gated behind SSO adoption
  • define whether enterprise identity lives alongside or replaces the existing Convex Auth org-member flow

Compliance And Procurement​

  • evaluate broader compliance requirements: SOC 2 evidence, data-residency flags, retention controls relevant to enterprise buyers
  • define separate packaging and pricing if enterprise work becomes a distinct commercial tier

What Not To Do Early​

Do not jump to these before the earlier phases are real:

  • generic CMS expansion for its own sake
  • enterprise auth work before real SSO demand exists
  • a large public API surface built just to claim coverage rather than driven by downstream app needs
  • SCIM provisioning before SSO adoption is confirmed
  • plugin systems or automation abstractions without proven downstream needs
  • more dashboard breadth that makes the starter look bigger while trust-critical flows remain under-validated