Skip to main content

Agency Manager Backend Module Map

Purpose​

This is the current backend ownership map for the shipped agency client-work slice.

Use it to answer:

  • which Convex modules already exist
  • which tables they currently own or read
  • which parts of the client-work model are surfaced versus still schema-only

Grounding Constraint​

The current repo does not expose this slice through standalone top-level clients, projects, time, billing, or documents namespaces.

Right now, the client-work implementation is grouped under packages/backend/convex/org/*.

Document that reality first. Do not describe extracted namespaces as if they already exist.

Current Ownership Map​

organizations​

Owns:

  • organization records
  • org memberships in orgUsers
  • membership resolution helpers
  • org selection and preference helpers

Primary files:

  • organizations/*
  • organizations/memberships.ts

viewer​

Owns:

  • current viewer/session resolution used across surfaces
  • cross-surface identity helpers

This is still infrastructure, not client-work business state.

org/access​

Owns the currently implemented org RBAC system.

Owns:

  • org role resolution
  • org capability resolution for existing admin, billing, portal, and settings actions
  • org role policy loading from orgRolePolicies
  • per-membership capabilityMode and capabilityOverrides

Important limit:

The current capability system does not yet model the full planned client-work permission grammar. It is real for org admin and billing controls, but the new client-work routes still rely partly on coarse role checks.

org/clientScope.ts​

Owns the current client-visibility rule for the org client-work slice.

Owns:

  • global client visibility for owners
  • scoped client visibility for non-owners through clientAccessAssignments
  • shared helpers used by the org client-work modules to filter visible client accounts

This file is the current source of truth for org client scope.

org/clientAccounts.ts​

Owns the live org client-accounts surface.

Owns:

  • listing visible client accounts
  • creating and editing client accounts
  • listing assignable org members
  • reading and updating clientAccessAssignments

Touches:

  • clientAccounts
  • clientAccessAssignments
  • orgUsers

Not yet surfaced here:

  • clientContacts
  • a dedicated client detail read model

org/documents.ts​

Owns the current transitional org drive surface.

Owns:

  • drive-finder listing inside visible client scope on top of the legacy documents table

  • storage-backed upload URL generation

  • uploaded-file registration during the pre-drive migration phase Touches:

  • projects

  • clientAccounts

Not yet surfaced here:

Owns the live org time list/create surface.

Owns:

  • listing recent time entries inside visible client scope
  • logging draft time entries

Touches:

  • timeEntries
  • projects
  • clientAccounts

Not yet surfaced here:

  • approval or locking workflows
  • team-vs-own split behavior

org/clientBilling.ts​

Owns the current org client billing workspace.

Owns:

  • billing-profile listing and upsert
  • invoice-record listing
  • subscription-record listing
  • billing access checks layered on the existing org capability model

Touches:

  • clientBillingProfiles
  • invoiceRecords
  • subscriptionRecords
  • clientAccounts

Important limit:

This is a read-heavy operational billing surface today. It is not yet a full Stripe-native invoice or subscription write surface.

org/documents.ts​

Owns the live org documents workspace.

Owns:

  • document listing inside visible client scope
  • storage-backed upload URL generation
  • document registration after upload

Touches:

  • documents
  • _storage
  • projects
  • clientAccounts

Important limit:

Request flows, richer metadata edits, and review workflows are not yet surfaced.

portal/*​

Current portal ownership is narrower than the older product docs implied.

Live portal areas include:

  • portal/account
  • portal/activity
  • portal support and account settings flows

The portal is not yet reading the new client-work tables through dedicated projects, files, or billing pages.

dev/seed/clientWork.ts​

Owns the demo dataset for the org client-work slice.

This file is important product documentation by implementation because it shows the current seeded shape for:

  • client accounts
  • contacts
  • projects
  • project updates
  • time entries
  • billing records
  • documents
  • client-access assignments

Schema-Only Or Seed-Only Parts Of The Slice​

These parts of the model exist, but are not yet first-class app surfaces:

  • clientContacts
  • projectUpdates

Those should be treated as the next surface work, not as missing schema.

Current Boundary Rule​

For the shipped slice, keep using the current org/* family ownership until the detail workflows force a clearer extraction.

Do not create new top-level namespaces only because the product docs once recommended them. The current implementation is coherent enough to finish the first detail layer in place.

  • clientAccounts
  • clientContacts
  • clientAccessAssignments
  • orgRolePolicies
  • orgPermissionOverrides
  • projects
  • projectUpdates
  • timeEntries
  • clientBillingProfiles
  • invoiceRecords
  • subscriptionRecords
  • documents

Existing organization, membership, auth, and notification tables remain where they already belong.

Route Ownership Map​

UI ownership should follow this backend map:

  • apps/app/src/app/[locale]/org/** create and manage client accounts, projects, time, billing visibility, and document sharing
  • apps/app/src/app/[locale]/portal/** consume client-safe summaries for projects, billing, and documents
  • apps/app/src/app/[locale]/platform/** later operate agencies, plans, support tooling, and cross-tenant concerns

Validation Scenarios​

This module map should support these scenarios cleanly:

  • agency creates a client account without touching billing or project modules
  • agency connects Stripe without touching app SaaS billing state
  • agency adds a project and later exposes updates to the portal
  • staff logs time against a project without mutating the client account record itself
  • Stripe invoice state can sync into billing views without changing project or document records
  • Stripe subscription state can sync into billing views without changing project or document records
  • a shared document can be attached to a client account or project with explicit portal visibility
  • the portal dashboard can load a safe account summary through portal-facing projections without bypassing access boundaries