Skip to main content

Agency Manager Starterkit Integration Map

Purpose​

This document explains how the agency manager product should connect into the current starterkit.

It is the bridge between product planning and eventual construction.

Starterkit Truths Already Present​

The current starter already gives the product several important foundations:

  • separate org, portal, and platform surfaces
  • tenant-aware organizations
  • separate auth realms, including portal-aware user state in the schema
  • org and portal route groups already in place
  • notifications, email, security, and organization scaffolding already present
  • org-level SaaS billing scaffolding already wired around Polar

Critical Separation: Two Different Billing Problems​

This repo already has one billing concern implemented in the starter:

  • organization -> app subscription billing

That is the SaaS billing for agencies paying for this product itself.

You want to add a second billing concern:

  • agency -> client billing

That is client-facing business billing inside the product, and you want Stripe here.

These are not the same thing and should not share a domain model just because both are called billing.

What The Existing Starter Billing Likely Means​

Right now the starter treats billing as an org/platform concern, including:

  • organization subscription tier
  • provider customer/subscription ids
  • billing portal access for the agency's own SaaS subscription
  • webhook handling for the starter's billing provider

That should continue to represent:

  • the agency paying for the app

It should not become the home for:

  • the agency invoicing its own clients
  • the agency creating client subscriptions
  • client-facing invoice history

Keep existing starter billing for product SaaS billing​

Owns:

  • app plan/tier for the agency tenant
  • agency's subscription to this software
  • platform/operator billing concerns

Likely surfaces:

  • org/settings/billing
  • later platform/billing

Add a separate client-billing domain for agency operations​

Owns:

  • agency Stripe connection state
  • Stripe customers for client accounts
  • invoices for those client accounts
  • subscriptions/retainers for those client accounts
  • client-facing billing summaries in the portal

Likely surfaces:

  • org/(dashboard)/billing
  • org/(dashboard)/customers/[clientId]/billing
  • portal/(dashboard)/billing

Route Anchors Already Present In The Starter​

The current route helpers and route tree already suggest the right placement model.

Org anchors already present​

  • overview
  • customers
  • settings
  • organizations
  • onboarding

Implication:

  • customers should become the client-account anchor
  • overview should become the agency operations dashboard anchor
  • settings/billing should stay reserved for the agency's own SaaS subscription/admin billing
  • agency-to-client billing should not be shoved into settings/billing by default

Portal anchors already present​

  • overview
  • activity
  • support
  • settings

Implication:

  • overview should become the client home/dashboard
  • activity is a natural home for client-visible updates and timeline
  • support is already the right place for contact handoff
  • new portal routes for billing, files, docs, and projects should extend this dashboard surface rather than introducing a separate portal app model

Schema Truths Already Present​

The current schema already supports important identity boundaries:

  • organizations exist as first-class tenant records
  • users can carry auth realm information
  • portal users already have organization-scoped fields
  • organization records already carry SaaS-billing fields

Implication:

  • do not fight the existing auth/tenant model
  • build client accounts as agency-owned business records under organizations
  • keep portal access tied to those business relationships, not to global app assumptions

Client accounts​

Connect to starter via:

  • organizations as the agency tenant owner
  • org/customers as the route anchor
  • portal membership patterns as the access model for client contacts

Projects​

Connect to starter via:

  • org dashboard surface for authoring
  • portal dashboard surface for projections
  • notifications and activity mechanisms for visible updates

Time tracking​

Connect to starter via:

  • org dashboard only in the first wave
  • existing org membership/authz patterns

Avoid pushing time-tracking concerns into portal state unless the product later proves the need.

Client billing with Stripe​

Connect to starter via:

  • a new client-billing domain namespace
  • portal-safe billing projections
  • existing notification/email infrastructure

Avoid reusing starter SaaS billing tables as the source of truth for client invoices.

Planning recommendation:

  • agencies should connect their own Stripe account to the app
  • the app should then operate on behalf of that connected Stripe account for customer, invoice, subscription, and billing portal workflows
  • the agency should still retain direct Stripe dashboard access for full finance administration

Why this fits the product:

  • it matches the user's expectation that the app is an extension of Stripe for agency billing
  • it avoids storing Stripe secret keys as a casual per-agency config pattern
  • it keeps Stripe-native billing objects as the underlying truth while letting the app add client-account context

What The App Should Likely Do On Top Of Stripe​

  • map each client account to a Stripe customer inside the agency's connected Stripe account
  • create and manage invoices from app workflows
  • create and manage recurring subscriptions/retainers from app workflows
  • launch Stripe-hosted customer billing portal flows where appropriate
  • mirror invoice and subscription state into app records for org and portal UX

What Should Stay Stripe-Native​

  • invoice object truth
  • subscription object truth
  • payment collection and payment method storage
  • hosted payment flows and billing portal flows where Stripe already solves the hard parts well

Practical Product Consequence​

The app should feel like a domain-aware billing workspace sitting on top of Stripe, not a disconnected finance clone.

Files and docs​

Connect to starter via:

  • Convex file storage and document metadata tables
  • portal-safe visibility rules
  • org dashboard authoring flows

Notifications​

Connect to starter via:

  • existing notifications infrastructure
  • org and portal surfaces already represented in the repo

Use domain events to trigger notices. Do not let notifications become the source business model.

Construction Guidance​

When implementation starts, prefer this order of fit:

  1. reuse existing tenant/auth/surface boundaries
  2. add new domain modules for agency business state
  3. project domain state into portal-safe read models
  4. keep app SaaS billing separate from agency client billing

Design Warning​

The biggest likely architecture mistake would be this:

  • treating the starter's existing org billing model as if it were the same thing as client billing

That would confuse:

  • who is paying whom
  • which surface owns the workflow
  • which provider is the source of truth
  • which records belong to platform/product ops versus agency business ops

Keep those concerns separate from day one.