Skip to main content

active-priority

Billing Foundation Follow-up​

  • Stripe client billing foundation is now structurally in place across backend config, Connect callback handling, webhook ingestion, customer mapping, and org billing route scaffolding.
  • The first invoice/subscription operations slice is now live in the org billing workspace and client billing surfaces, including invoice draft/finalize/send/void, subscription create/update/cancel/reactivate actions, and shared catalog-backed line-item selection.
  • Commercial provenance is now live on quote, invoice, subscription, and contract detail surfaces, the client overview now exposes cross-track next actions anchored on the client account, and subscription detail now includes derived plan-history and billing-timeline views.
  • Immediate next work for billing should focus on reporting, analytics, and remaining operational polish on top of the now-live provider-backed Stripe layer, including post-send invoice lifecycle depth and any remaining catalog synchronization edge cases.
  • Keep Polar SaaS billing work separate from this org-operated Stripe client billing track.

Active Priority

Current Phase​

The client-work foundation baton has moved past basic org and portal scaffolding. The repo now has live org operations, org project delivery, and portal client-work visibility, so the phase is about finishing the remaining operational detail and cleanup work.

Core Logic Guardrails​

Before adding another product area, keep the system anchored to these rules:

  • clientAccount remains the company-level anchor for delivery, billing, drive, contracts, quotes, and portal access
  • clientContact remains the company-local human record; portal identity stays an access layer, not a second client directory
  • commercial records (invoiceRecords, quoteRecords, subscriptionRecords, contracts) must extend the client account's billing and legal/commercial context instead of forming parallel relationship models; contracts own their own workflow, content, and attachments and must not collapse back into the Drive feature
  • the portal remains a client-facing projection of org truth plus explicit shared-collaboration records; do not invent portal-only business records that bypass the org model
  • overview remains the operational snapshot and analytics becomes the reporting drill-in; do not collapse both jobs into one page

What Is Complete In This Phase​

  • the first client-work schema and seed data are in the backend
  • org client accounts are live through the clients route
  • org client detail is live through clients/[clientId]
  • org project detail is live through projects/[projectId]
  • org detail-route IA now uses real subpaths for clients/[clientId]/* and projects/[projectId]/* instead of query-param tabs
  • org time and commercial queues now use real page paths for job switches: time vs time/timer and invoices vs subscriptions
  • org sidebar billing navigation now lands on explicit Invoices and Subscriptions entries instead of a single Billing collection entry
  • org time now treats Entries as the sidebar workspace and keeps Timer as a utility route and shell action instead of a second sidebar destination
  • org invoices now use the secondary bar for fixed status queues while keeping search and client filters local to the billing collection toolbar
  • org entries now use the secondary bar for approval queues while keeping search local to the entries collection toolbar
  • org entries now use a dense table plus inline approval dropdowns instead of drag-and-drop approval lanes
  • org clients now use a true hybrid split: list mode is the default dense table with assigned-member summaries and local status filtering, while organize mode is the search-driven drag-and-drop board without a conflicting status filter
  • org portals now use their own queue-switched operational workspace, separate from clients, for per-client portal access and workspace management
  • org shell search now uses a deliberate split: the launchpad remains the quick command surface, and the topbar Spotlight modal now handles paged operational search with type filters and broader entity coverage
  • client create/edit now seeds the primary person's portal access from the canonical client-account record when portal access is enabled
  • client People now acts as the canonical company people list, with per-person portal access state and role shown directly in the org workspace
  • the org portals workspace now derives live/unlinked/attention state from the unified portal-access summary on each client account instead of a separate primary-contact heuristic
  • the org collection taxonomy is now explicit in docs/app/development/org-workspace-collection-ux.md: queue-switched record lists, hybrid list/organize collections, and pure record lists each have different secondary-bar, toolbar, and drag-and-drop rules
  • the client drive source-of-truth is now explicit in docs/app/product/client-drive-spec.md and docs/app/development/client-drive-implementation-plan.md
  • first-class client-contact create/edit workflows are live in the client detail workspace
  • org project updates now support draft and published states in the app
  • scoped client visibility is live through clientAccessAssignments
  • org projects, time, billing, and the current drive-finder route are live
  • org time-to-billing rollups now derive client billing state from tracked work, invoices, and subscriptions
  • the org overview route is now a real operations dashboard backed by the workspace summary surface
  • the org collection-shell baseline is now in place across the rebuilt record-heavy workspace routes
  • org time-entry detail is live through time/[timeEntryId]
  • org billing detail is live through the client billing tab plus invoices/[invoiceRecordId], subscriptions/[subscriptionRecordId], and quotes/[quoteRecordId]
  • Stripe-backed invoice and subscription write flows are now live from the org billing workspace, client billing tab entry points, and detail routes
  • commercial provenance blocks are now live across quote, invoice, subscription, and contract detail so cross-record follow-through is explicit without inventing fake ownership
  • quote and contract surfaces now exist as client-account-scoped commercial artifacts and should remain attached to the same commercial/legal spine
  • client records now own rich billing identity/defaults, including Stripe customer sync inputs and invoice rendering template defaults
  • the client overview now acts as a real operating hub with state-based next actions across access, commercial, delivery, and collaboration
  • the portal has real authenticated client-work routes for overview, projects, billing, files, activity, settings, and support
  • portal project drill-in is live through projects/[projectId]
  • the backend drive migration is now cut over to driveItems, fileAssets, and richDocuments; the legacy documents table is no longer part of the live collaboration model
  • portal session and workspace runtime are now grant-aware through portalAccessGrants, so one portal identity can hold multiple client-company grants inside the same agency organization

What Is Still Missing In This Phase​

  • remaining collaboration closeout decisions on top of the now-landed portal request inbox, response submission flow, acknowledgment step, and richer destination metadata
  • richer time reporting and manager workflow polish on top of the now-landed approval and lock baseline
  • smaller operational polish and residue cleanup after package-wide validation was restored

Immediate Goal​

Finish the language, IA, and cross-feature coherence pass inside the existing org and portal client-work slice without reopening the rest of the product model.

The next work should keep the client-first model intact, build on the now-landed portal self-service people and time-lock slices, and deepen collaboration metadata plus reporting polish without reopening the corrected commercial and collaboration model.

The Stripe authoring baseline is now present, so the next billing work should stay on time-to-billing workflow depth and customer-surface coherence instead of reopening the provider foundation.

Use docs/app/development/agency-owner-smart-workflows.md as the source of truth for anticipatory UX and cross-track follow-through during this polish pass.

The client and portal model is now explicit and should remain the source of truth:

  • clientAccount is the company-level client record
  • clientContact is a human inside that company
  • portal access is a capability and lifecycle state on that person, not a second parallel identity model in org UI
  • portalUser is the org-scoped portal identity for that person
  • portalAccessGrant is the company-specific grant that links that identity to one client company and one company-local person record
  • the org People tab is the canonical company-level person management surface
  • the org Portals workspace is the cross-client operational view over that same underlying access model

Use org-workspace-completion-milestone.md as the move-on gate for this baton.

Fundamental Logic Hardening Pass​

Before any broader product expansion, run this pass in order and treat each slice as a completion gate.

  1. Access and permissions coherence. Done means org-side visibility, role policy, and billing visibility rules read as one system instead of scattered feature-by-feature exceptions. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  2. Portal grant-model coherence. Done means portal and org people/access flows use portalAccessGrants as the only company-access mental model and stop depending on older single-company assumptions. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  3. Stripe truth versus app truth discipline. Done means billing flows, analytics, exports, and UI copy keep Stripe as finance truth while app-side billing records stay operational projections with client-account context. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  4. Collaboration closure rules. Done means the request lifecycle has an explicit lightweight definition of review, acknowledgment, and close without reopening heavy approval workflow design. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  5. Cross-feature ownership audit. Done means each major surface still points back to client account as the anchor and no track starts pretending to own another track's records. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

Rule for this pass: do not add a new product area while one of these five slices is still logically unresolved.

Current Baton​

  1. Land the next anticipatory UX slice from docs/app/development/agency-owner-smart-workflows.md, starting with actionable spotlight rows and timer-stop follow-through where it still sharpens cross-track handoff.
  2. Close the remaining collaboration lifecycle polish on top of the request inbox, response submission, acknowledgment, destination metadata, and the now-landed scoped external upload-link baseline across both org and portal creation surfaces.
  3. Deepen time reporting on top of the now-landed approval and lock workflow without making the entries workspace heavier.
  4. Keep trimming remaining legacy-presentation and registered-surface naming carryover only where it reduces future ownership drift without reopening the model.

Sequencing Rule​

Do not start a second wave of new tables before the current first-wave tables are actually used in the app.

Specifically:

  • use clientContacts before inventing another contact model
  • use projectUpdates before inventing a second project activity model
  • use the current billing records before adding parallel digest tables for convenience
  • do not add a second parallel file model beside the planned drive tables

Out Of Scope Until This Baton Clears​

  • a second wave of time workspace complexity beyond the current approval-plus-lock baseline
  • complex drive approval workflows beyond the lightweight request layer
  • general public browsing of client drive folders
  • the post-baton operator layer for shell-level Notes and the sidebar Today workspace defined in docs/app/product/notes-and-today-spec.md
  • platform multi-agency operations