Skip to main content

Agency Manager Logic Rules

Purpose​

These are the non-negotiable business rules for the product.

They exist so future implementation work stays grounded in reality instead of drifting into generic software patterns.

1. Client Account Is The Operational Anchor​

  • projects belong to a client account
  • billing context belongs to a client account
  • documents belong to a client account, optionally scoped to a project
  • portal access grants belong to a client account

Portal identity is a separate layer:

  • one portal identity belongs to one agency organization
  • one portal identity may hold multiple company grants inside that same organization

Do not scatter relationship truth across unrelated entities.

1A. Agency Staff Access Should Be Scoped At The Client Account Level​

  • the agency owner should always have full visibility across all client accounts by default
  • agency owners or admins should be able to give a staff user access to all clients or to specific assigned clients only
  • for non-owner staff, client access should be chosen in the invite or access-edit flow rather than as a separate hidden setup step
  • client-account access should drive default org-side visibility for that client's projects, documents, and updates
  • financial visibility may require both client-account access and a billing-specific role or capability
  • if a staff user does not have billing permission, billing should be hidden rather than partially summarized
  • this model should stay simple enough for a 1-to-10 person agency to reason about quickly

Do not assume every agency staff member should automatically see every client just because the team is small.

1B. Role Names Are Starting Templates, Not The Final Permission Truth​

  • the first common role templates can be owner, admin, account manager, and staff
  • the agency owner should be able to choose which capabilities those non-owner roles actually have inside that agency
  • the product may allow specific user-level privilege exceptions when a real operational need exists

Recommended model:

  • default role templates give agencies a fast starting point
  • owner-managed capability toggles adapt those templates to how the agency actually runs
  • per-user overrides exist as an exception layer, not the default way to manage everyone

Hard guardrail:

  • the agency owner remains the top-level authority and should not be downgraded into a normal editable staff role

2. Portal Identity Is Separate From Agency Identity​

  • portal users are tenant-scoped client identities
  • org users are agency staff identities
  • the same email may exist in multiple client realms and also in an org realm without implying the same principal
  • inside one agency organization, the same portal identity may also hold multiple company grants without becoming multiple separate portal logins

Do not collapse portal and org auth into one shared identity assumption.

3. Stripe Is The Billing Truth​

  • invoices should mirror Stripe invoice state
  • subscriptions should mirror Stripe subscription state
  • payment outcomes should reflect Stripe outcomes
  • the app may add client-account context, labels, and workflow helpers

Do not build a second finance truth inside the app unless a proven requirement forces it.

3A. Agencies Should Connect Their Own Stripe Account​

  • the agency's client billing should run through the agency's Stripe account
  • the app should operate on top of that Stripe account rather than pretending to replace Stripe entirely
  • the agency should retain direct Stripe dashboard access

Planning stance:

Prefer a Connect-style integration so the app can act on behalf of connected agency accounts while keeping Stripe as the underlying billing system.

  • invoices answer: what is due, paid, overdue, or failed
  • subscriptions answer: what recurring service is active, paused, past due, or canceled

Do not compress both into one generic billing status field.

5. "Send Invoices From Here" Means Operate Billing From The App Surface​

For the first real product phase, this should mean:

  • agency staff can open a client account billing area
  • initiate or manage invoice flows through Stripe-backed actions
  • monitor invoice state from the app
  • provide a clean portal experience for clients to review and pay

It does not require replacing Stripe's invoice generation engine immediately.

6. "Create Subscriptions From Here" Means The App Owns The Service Context​

The app should know:

  • which client account the subscription belongs to
  • what service or retainer it represents
  • what the current status is
  • which actions are available

Stripe should still own recurring billing mechanics.

6A. Client Account, Not Project, Is The Default Subscription Anchor​

  • recurring subscriptions should attach to the client account first
  • projects or engagements may be linked when useful for reporting or clarity
  • creating a subscription should not require the user to create or choose a project first

Do not make everyday billing depend on project-management structure.

7. Projects Are Client-Visible Delivery Objects, Not Internal Task Buckets​

  • projects should be simple enough for agency operations and client visibility
  • task sprawl should not define the product
  • client-visible updates matter more than internal agile constructs

Do not force every project into a ticketing framework.

8. Time Entries Are Source Records​

  • a time entry is a real atomic work record
  • summaries and totals derive from time entries
  • raw entries remain internal by default

Do not store only summary totals if the agency expects auditability or billing support later.

8B. Time Can Inform Billing Without Hard-Locking It​

  • time entries should be able to recommend billable invoice line items
  • agencies should be able to edit, remove, combine, or override those recommendations before sending an invoice

The product should support time-informed billing, not force mechanical time-to-invoice conversion.

8A. Mirrored Billing Records Are Operational Projections​

  • invoice records in the app are mirrors and summaries for product workflows
  • subscription records in the app are mirrors and summaries for product workflows
  • the app can add client-account links, service labels, and status rollups

Do not let mirrored records become a competing source of finance truth.

  • files are storage-backed assets such as PDFs, images, zips, and deliverables
  • docs are structured client-readable content such as briefs, SOWs, summaries, or notes

Do not treat every client-readable artifact as just a file upload.

10. Client Drive Must Be Organized Around Retrieval, Not Uploading Alone​

The core question is not “can the agency upload a file?”

It is “can the client find the right file later without asking for it?”

That means the drive needs:

  • account context
  • project context where relevant
  • categories
  • clear naming and visibility

10A. File Exchange Must Be Bidirectional Early​

  • agencies need to share files with clients
  • clients need to return files, assets, approvals, or requested materials back to the agency
  • uploader/source context should always stay visible

Do not design the portal as a one-way file showcase if the goal is a real working client workspace.

10B. Shared Drive First, Requests Second​

  • every active client workspace should have a default shared drive model
  • clients should be able to upload without the agency creating a formal request every time
  • file requests should add structure for specific needs, not become the only upload path

Do not mistake a request workflow for a real collaborative file workspace.

10C. Agency Visibility Should Follow Client Access By Default​

  • if an agency user already has access to the client account, they should normally be able to see that client's uploaded files
  • the first model should keep visibility simple and understandable
  • file-level internal exceptions can exist later if a real need appears

Do not start with per-file internal visibility rules that make everyday collaboration harder to reason about.

11. Internal Notes Must Never Be The Same Surface As Client Docs​

  • internal notes belong to agency workflows
  • client docs belong to the portal/shared relationship surface

Never rely on a boolean buried in one general-purpose notes table if it makes accidental leakage easier.

12. Portal Home Must Be Comprehension-First​

The portal home should quickly answer:

  • what is active
  • what changed
  • what is owed
  • what needs attention

It should not feel like a settings area or an admin dashboard.

13. Billing And Delivery Problems Must Surface Separately​

  • delivery issues belong to projects, updates, and account health
  • billing issues belong to invoices, subscriptions, and payment state

Do not use one umbrella status to hide different classes of problems.

14. Notifications Reflect Domain Events; They Do Not Own Them​

  • invoice overdue is a billing event first
  • project updated is a project event first
  • file shared is a document event first

Notifications should project those events to users. They should not become the primary business record.

14A. Webhooks Should Drive Billing Sync​

  • billing state changes should sync from Stripe events
  • app-side polling can exist as a fallback or repair tool, not the primary truth pipeline

If billing status in the app matters, webhook-driven synchronization should be treated as a first-class part of the model.

15. V1 Should Solve The Agency's Real Weekly Workflow​

The first useful version should let an agency do this in one product:

  • onboard a client
  • run active projects
  • log time
  • manage invoices/subscriptions through Stripe-backed flows
  • share files/docs in both directions
  • let clients self-serve account visibility

If a feature does not strengthen that loop, it should probably wait.