Franchise Hierarchy

CleanEstimate Pro now has the Phase 1 through Phase 4 franchise beta workflow for parent-child organization management.

This is still a beta workflow. The current build now supports:

• parent and child organizations
• franchisor, operator, location, HQ, and branch org types
• scoped multi-org memberships
• active workspace switching
• a sidebar workspace switcher for eligible multi-org users
• a dedicated Franchise admin area for viewing and managing descendant orgs
• 15-minute franchise summary refreshes for beta rollups
• franchise audit logging for org switching and cross-org franchise access

The workflow is still intentionally constrained for beta rollout, but parent-org admins no longer need to rely only on raw APIs or internal setup tools.

What Exists Today

The current build includes:

• hierarchy metadata on organizations
• relationship records between parent and child orgs
• descendant and ancestor traversal helpers in the database
• scoped membership access for org-only, org-and-children, and assigned-children access
• active org switching through the authenticated admin API
• franchise admin APIs for overview, child-org management, child-org user listing, and child-org invites
• continued parent-org visibility into inactive descendant workspaces so beta admins can review and reactivate child orgs without losing the hierarchy tree
• a normal admin-sidebar entry at Admin --> Franchise for eligible parent workspaces
• a workspace switcher in the admin shell when a user can access more than one readable org
• franchise overview, workspace roster, child-workspace detail, child-workspace users, reports, and settings pages
• a materialized franchise summary snapshot (mv_org_summary) refreshed every 15 minutes for beta reports and workspace-level rollups
• franchise audit logs for org switching and franchise page/API access
• descendant-read RLS helper coverage on the core org-scoped workflow tables used in the beta
• descendant-read RLS intentionally excludes inactive child-workspace data on authenticated paths, while the franchise admin APIs still keep inactive workspaces visible for management via service-role reads

The current build still does not include public franchise APIs or full cross-org analytics beyond the operational rollups in the beta admin area.

Supported Org Types

The hierarchy model supports these org types:

• standalone
• franchisor
• operator
• location
• hq
• branch

Current parent-child expectations:

• franchisor can manage operator and location descendants
• operator can manage location descendants
• hq can manage branch descendants

Access Model

Phase 2 keeps access explicit. A user can only switch into an org when their membership or membership scope allows it.

Supported membership scopes:

• own_org
• org_and_children
• assigned_children

This is intentional. CE Pro does not silently grant sibling-org or unrelated-org access just because a user belongs to a parent company.

Workspace Switching

The active workspace is now stored in the authenticated user metadata and resolved on future admin requests.

That means:

• you can keep a single login
• the active workspace can change without logging out
• org context, permissions, and feature flags now resolve from the active org instead of always defaulting to the first membership
• successful workspace switch responses now tell the admin client to refresh session metadata immediately so the next request resolves against the new active org
• the switcher only appears when the current user can access more than one readable workspace
• inactive workspaces stay visible to parent admins for management, but cannot be selected as the active workspace

If a stored active org becomes stale or inaccessible, CE Pro falls back safely to the earliest active membership.

Permissions

Two new admin permissions were added for the franchise beta:

• franchise.view
• franchise.manage

By default:

• Owners get both
• Managers get both
• Other roles do not get them unless role permissions are customized

The franchise sidebar area appears only when all of these are true:

• the active org has the franchise hierarchy feature enabled
• the active org type is a parent-capable type (franchisor, operator, or hq)
• the active org plan is franchise-eligible (commercial, base_plus_lights_commercial, base_plus_lights_commercial_sms, or enterprise)
• the current role includes franchise.view

Write actions like creating child workspaces, changing workspace metadata, deactivating workspaces, and sending child-org invites require franchise.manage.

Franchise Admin Workspace

Eligible parent-org admins now get these pages inside the normal admin UI:

• Admin --> Franchise — hierarchy overview and direct-child summary
• Admin --> Franchise --> Organizations — full descendant workspace roster with child-org creation
• Admin --> Franchise --> Organizations --> [Workspace] — child workspace details and activation state
• Admin --> Franchise --> Organizations --> [Workspace] --> Users — child workspace roster and invite flow
• Admin --> Franchise --> Reports — operational rollups for workspace counts, plans, and staffing
• Admin --> Settings --> Franchise — hierarchy policy, permissions, and rollout guidance

The root parent org is intentionally read-only inside the child-workspace detail page. Continue using the standard CE Pro settings flow to edit the active parent workspace itself.

Reporting and Refresh Cadence

Franchise reports now read from a precomputed summary snapshot instead of running live cross-org aggregate queries on every page load.

That snapshot currently includes:

• direct child counts
• active team membership counts
• 30-day estimate counts
• 30-day job counts
• 30-day paid invoice revenue

For beta, the summary is refreshed every 15 minutes through the internal cron route:

• POST /api/cron/refresh-franchise-summary

This route uses the same CRON_SECRET bearer-header protection as the other internal cron endpoints.

These rollups only count live application data. Sandbox or test-environment records are excluded from the franchise summary so beta reporting matches production-facing numbers.

Audit Logging

Franchise beta now records audit events for:

• successful org switches
• franchise overview access
• descendant org roster access
• child workspace detail access
• child workspace user access
• child workspace creation, updates, deactivation, and invites

This hardening step gives the beta rollout a durable trail for cross-org activity before live franchise onboarding.

Beta Setup Checklist

Before onboarding a real franchise network:

1. Put the parent org on a franchise-eligible plan.
2. Enable the franchise hierarchy feature flag for the parent org and its child workspaces.
3. Confirm the parent org type is one of franchisor, operator, or hq.
4. Create the child org tree from Admin --> Franchise --> Organizations.
5. Grant franchise.view and franchise.manage only to the admins who should manage the hierarchy.
6. Verify org switching works for the intended parent and child users.
7. Confirm the summary refresh cron is scheduled and healthy before relying on beta reports.

Rollout Notes

This phase is intentionally beta-scoped rather than fully self-serve for all customers.

Use it when you need to:

• prepare franchise beta org trees
• invite managers into child orgs
• validate parent-child access rules
• test active workspace switching in the real admin shell
• confirm the 15-minute summary refresh is running
• confirm cross-org audit logs are being recorded
• manage inactive child workspaces without losing visibility into the hierarchy

If you are a normal standalone org, this release should not change your day-to-day workflow.