Skip to main content

Agency Manager Surface Map

Purpose​

This document maps the current shipped surface ownership in the repo.

It is no longer a speculative IA sketch. Use it to distinguish:

  • what is already live
  • what is partially live
  • what still belongs to the next build step

URL Grounding​

The public URL rules remain unchanged:

  • org routes live on the app host without /org in the public URL
  • portal routes live on the tenant host without /portal in the public URL
  • platform routes remain under /platform

Use appRoutes as the canonical route contract.

Org Surface​

Purpose​

The org surface is now the live agency workspace for client accounts, delivery, billing operations, commercial records, and the shared drive.

Hard product rule:

  • clients/[clientId] is the simple consolidated home for a single client's world
  • top-level sidebar workspaces are advanced operational views across the same client-owned records
  • those sidebar workspaces do not create separate ownership domains

Current live areas​

overview​

Status: live.

What it is today:

  • org operations dashboard summary
  • organization/subscription summary
  • settings and portal quick links

What it is not yet:

  • the longer-horizon reporting drill-in surface for trends, finance, and operational exceptions

analytics​

Status: next route to add.

What it should do:

  • sit in the org sidebar as a dedicated reporting workspace
  • give agency managers graphs, trend lines, and attention views for delivery, utilization, revenue, receivables, and billing health
  • complement overview instead of turning overview into a giant reporting dump

clients​

Status: live.

What it does today:

  • lists visible client accounts
  • creates client accounts
  • edits core client-account fields inline
  • shows assigned staff for each client account
  • lets owners update clientAccessAssignments

What also exists now:

  • client detail workspace through clients/[clientId]
  • client-local sections for people, projects, time, drive, contracts, billing, and activity

Architectural rule:

The client detail workspace is the plain-language home for one client's complete operating context.

Users should not need to leave it just to understand what exists for that client.

Important naming note:

The route folder is now clients, which matches the shipped client-account model.

projects​

Status: live, list-first.

What it does today:

  • lists projects across visible client accounts
  • creates projects
  • shows status, visibility, summary, and target date

What also exists now:

  • project detail workspace through projects/[projectId]
  • draft and published project update workflow

Important behavior rule:

If a file belongs to a project, users should be able to upload or retrieve it from the project workspace without detouring through the global Drive workspace.

What is still missing:

  • only the next layer of workflow depth after the current consistency pass

time​

Status: live, list-first.

What it does today:

  • lists recent time entries across visible client scope
  • logs draft time entries
  • links entries to client accounts and optional projects

What is still missing:

  • team-vs-own workflow split
  • approval and lock workflow depth

billing​

Status: live, access-gated.

What it does today:

  • lists invoice records
  • lists subscription records
  • launches Stripe-backed invoice and subscription authoring
  • supports invoice and subscription detail routes
  • includes the backend Stripe foundation for agency connection state, webhook sync, and hosted billing portal entry points

What is still missing:

  • richer invoice and subscription operational visibility and reporting

Important behavior rule:

Billing attachments belong to billing surfaces first. The global Drive workspace may index or retrieve them later, but it should not be the required entrypoint for billing-specific file work.

quotes​

Status: live, billing-adjacent.

What it does today:

  • lists client-account-scoped quote records
  • creates draft quotes through Stripe-backed flows
  • finalizes and cancels quotes from the org surface

What is still missing:

  • deeper commercial workflow polish and clearer follow-through from quote acceptance into longer-lived client-account context

contracts​

Status: live, first-class commercial/legal workspace.

What it does today:

  • lists contract records tied to client accounts and optional projects
  • supports contract detail routes with contract-owned authored content
  • keeps contracts as a first-class operational queue and legal workflow instead of treating them as just another collaboration artifact inside Drive

What is still missing:

  • deeper contract lifecycle polish and tighter coordination with quotes, approvals, signatures, and client acknowledgments

Important behavior rule:

Contract attachments belong to contract flows first. The global Drive workspace may help retrieve them later, but contracts remain the owning operational context.

drive​

Status: live.

What it does today:

  • acts as a global drive finder across visible clients
  • supports folder, upload, and doc creation in the drive model
  • owns the shared file and authored-doc collaboration surface instead of deferring to the legacy documents table
  • is the place for exchange, requests, uploads, and collaboration artifacts rather than the source-of-truth workflow for contracts or billing

Important positioning rule:

Drive is the advanced file-centric operational view across one or many clients.

It is not the universal place users must visit every time a feature involves a file.

What is still missing:

  • nested folders, richer metadata, and request-driven collaboration depth

portals​

Status: live.

What it does today:

  • gives agency staff a cross-client operational view of portal readiness and access state
  • exposes queue-switched portal management instead of burying portal state inside the client list

What is still missing:

  • portal-side self-service people management on top of the multi-company grant model

settings​

Status: live from the earlier org-access/settings work.

This area remains the home for org admin, access, and configuration. It is not the center of the new client-work slice.

Org areas not yet live​

  • analytics
  • deeper invoice and subscription operational polish

Portal Surface​

Purpose​

The portal is live as a client-facing workspace, but it is still intentionally narrower than the org workspace.

Current live areas​

overview​

Status: live.

Current focus:

  • portal session and access state
  • recent activity snapshot
  • billing and account status summaries
  • quick visibility into current delivery and shared files

projects​

Status: live.

Current focus:

  • client-visible project list
  • project status, published updates, approved billable time, and shared file counts

projects/[projectId]​

Status: live.

Current focus:

  • project drill-in with published updates, shared files, and recent activity

billing​

Status: live.

Current focus:

  • current client billing snapshot
  • invoice and subscription visibility
  • portal-safe billing actions layered on Stripe-backed state

files​

Status: live.

Current focus:

  • shared client-visible document library

activity​

Status: live.

Current focus:

  • portal-safe recent activity feed
  • account/profile/settings activity filters

settings​

Status: live.

Current focus:

  • account and support configuration flows

support​

Status: live.

Current focus:

  • support request workspace

Portal areas not yet live​

  • richer client response loops for requests, approvals, and acknowledgments
  • deeper billing self-service beyond the current Stripe-backed visibility and actions

Platform Surface​

Purpose​

Future multi-agency operator workspace.

This surface has not changed materially as part of the org client-work slice.

Placement Rules​

Client accounts​

  • authored and managed in org
  • not yet projected into a dedicated portal client-work IA

Projects​

  • authored in org
  • surfaced in portal project list and project drill-in routes

Time​

  • owned by org
  • no dedicated portal time surface planned in the current phase

Billing​

  • operated in org
  • projected into a live portal billing workspace with Stripe-backed summaries and actions

Drive and shared artifacts​

  • authored in org
  • surfaced through the live portal files route
  • should stay the shared collaboration layer for general files, docs, ad hoc collection, and request-driven exchanges
  • should not take ownership away from contracts, billing, projects, or other feature-specific artifact flows
  • should remain the cross-client and cross-context file-operations surface rather than the universal upload choke point

Current Route Direction​

Org​

  • org/(dashboard)/overview live org operations dashboard summary route
  • org/(dashboard)/analytics planned org reporting workspace for agency performance, finance, and billing attention
  • org/(dashboard)/clients live client-accounts surface
  • org/(dashboard)/portals live cross-client portal operations workspace
  • org/(dashboard)/projects live projects surface
  • org/(dashboard)/time live time surface
  • org/(dashboard)/quotes live quotes workspace
  • org/(dashboard)/billing live billing workspace
  • org/(dashboard)/contracts live contracts workspace
  • org/(dashboard)/drive live drive finder and collaboration workspace
  • org/(dashboard)/settings/* org admin and configuration

Portal​

  • portal/(dashboard)/overview live client account home
  • portal/(dashboard)/projects live client-visible projects surface
  • portal/(dashboard)/projects/[projectId] live client project drill-in
  • portal/(dashboard)/billing live client billing workspace
  • portal/(dashboard)/files live shared files workspace
  • portal/(dashboard)/activity live recent activity surface
  • portal/(dashboard)/settings live account/settings surface
  • portal/(dashboard)/support live support workspace

IA Rule​

Do not document future portal client-work routes as if they already exist. The next phase should extend the current portal shell, not pretend that parity is already shipped.

The org surface is for management.

The portal surface is for clarity.