Skip to main content

Admin IA And Operations Model

This document translates the product rules in docs/product/admin-operations-flow.md into page responsibilities and operator-facing language.

Use this as the source of truth for:

  • how the admin app should be organized
  • what each major page is responsible for
  • which language the app should use
  • which actions should be easy vs rare
  • which complexity should be hidden from normal operators

Product Framing​

The admin app should feel like an operating console for a lead distribution business.

It should not feel like:

  • a technical workflow debugger
  • a generic CRM
  • a database admin panel

The information architecture should always reinforce:

  1. capture the lead
  2. deliver the lead
  3. track who owns it
  4. track what is billable
  5. manage installer load and capacity

Primary Operator Questions​

Dashboard​

The dashboard should answer:

  • what needs action right now
  • which leads failed delivery
  • which installers are at or near capacity
  • what is billable this cycle

Lead detail​

The lead detail page should answer:

  • who captured this lead
  • was it delivered
  • what failed
  • what should happen next

Installer detail​

The installer page should answer:

  • should this installer receive more leads
  • how many active leads do they already have
  • how much cycle cap they have already used
  • how many delivered leads remain billable
  • how much do they owe

Billing​

The billing page should answer:

  • what each installer owes this cycle
  • what has already been paid
  • what is overdue or unresolved

Language Model​

The app should prefer operator language over technical language.

Preferred language​

Use:

  • lead delivery
  • lead distribution
  • captured by
  • delivered to
  • failed delivery
  • retry delivery
  • change installer
  • installer load
  • cap used this cycle
  • billable deliveries

Language to de-emphasize​

Avoid centering:

  • routing
  • auto-routing run
  • rollback
  • assignment mechanics as a primary UX concept

Those concepts may still exist in the data model, but they should not dominate the UI.

Page Responsibilities​

1. Dashboard​

Purpose​

The dashboard is an attention board.

Its job is to tell operators what needs intervention now.

Must-show sections​

  • New leads needing review
  • Leads captured but not yet delivered
  • Failed deliveries needing retry
  • Leads with no eligible installer
  • Installers at or near capacity
  • Billable deliveries in the current cycle
  • Outstanding installer balances

Should not dominate the page​

  • abstract charts with no action attached
  • deep lifecycle breakdowns that belong on list/detail views
  • technical delivery logs

Core actions from dashboard​

  • open lead needing action
  • retry delivery
  • review unassigned / undeliverable leads
  • inspect overloaded installers

2. Leads List​

Purpose​

The leads list is the operating queue.

It should help an operator find:

  • undelivered leads
  • delivered leads
  • leads needing reroute
  • leads by installer, region, or status

Best filters​

  • lead status
  • delivery state
  • selected path
  • captured installer
  • region
  • created date
  • billable status

Best columns​

  • customer name
  • postcode / region
  • selected path
  • captured installer count
  • delivery state summary
  • billable state
  • created / submitted time

3. Lead Detail​

Purpose​

This is the core page in the whole app.

If an operator opens one lead, they should immediately understand:

  • what happened
  • who has it
  • whether it was delivered
  • whether billing can happen

Above-the-fold priorities​

The first view should show:

  • lead status
  • selected path
  • captured installer(s)
  • delivery result for each captured installer
  • whether the lead needs attention

Sections that should exist​

Summary​

Should focus on:

  • customer basics
  • path
  • capture and delivery outcome
  • billable state

Installer delivery​

This is the current “routing” concept reframed into plain language.

Should show:

  • installer name
  • captured time
  • delivery status
  • delivery reason if failed or skipped
  • retry delivery action
  • change installer action

Notes and activity​

Useful, but secondary to delivery truth.

Recommendation and intake details​

Important context, but not the first thing ops needs after a lead arrives.

Reroute / change installer UX​

This should not sit as a confusing always-open block on the page.

Preferred V1 pattern:

  • make “Change installer” a focused dialog or drawer
  • explain exactly what will happen:
    • original installer remains in history
    • new installer will be captured
    • delivery may create another billable event and another default cap event depending on business rule

The UI should force that consequence to be explicit.

4. Installer List​

Purpose​

The installer list is a workload and commercial health view.

Best columns​

  • installer name
  • status
  • regions / tier
  • active lead load
  • capacity cap
  • cap used this cycle
  • cycle lead cap
  • amount due

Best filters​

  • status
  • region
  • tier
  • at capacity
  • unpaid balance

5. Installer Detail​

Purpose​

This page should explain whether this installer is operationally healthy.

Above-the-fold priorities​

  • active status
  • region tier links
  • active lead load
  • capacity cap
  • current cycle cap used
  • current amount due

Sections that should exist​

Operational summary​

  • active lead count
  • current cap
  • delivery failures
  • recent lead intake

Commercial summary​

  • billing cycle
  • payment terms
  • cap used this cycle
  • billable count
  • recommended lead price
  • compare-quotes lead price
  • tax rate
  • current balance
  • payment status

Region and tier setup​

  • preferred / backup by region
  • eligibility notes

6. Billing​

Purpose​

Billing is not a generic finance page.

It is the place where operators reconcile delivery truth, cap usage, and money owed.

Billing should be installer-centric first.

Each installer view should show:

  • billing period start / end
  • maximum leads in cycle
  • cap-used lead count
  • billable lead count
  • recommended lead count
  • compare-quotes lead count
  • rate by lead type
  • subtotal
  • balance due
  • paid / unpaid status

The billing page should start from installers and current cycles, not arbitrary date ranges.

Operators should see one installer per row with:

  • current cycle window
  • cap used in cycle
  • current amount due
  • bill status
  • unpaid balance
  • next action

Arbitrary period filtering should be a secondary review tool, not the main mental model.

Billing data should come from​

  • delivered lead events
  • cap status on delivery events
  • commercial configuration
  • payment records / invoices

Not from generic lead counts.

7. Hidden Complexity​

The app can keep internal complexity in the backend, but should not expose it unnecessarily.

Fine to keep in code / data model​

  • auto-run records
  • scheduler retries
  • audit tables
  • internal event keys

Should not dominate the normal UX​

  • rollback state jargon
  • internal mutation/action distinctions
  • raw technical delivery logs

8. Failure Handling Model​

Delivery failure​

If installer delivery fails:

  • show it on lead detail
  • show it on dashboard attention queue
  • allow manual retry
  • allow background retry policy

No eligible installer​

If no installer is available:

  • show exception in dashboard
  • show clear undeliverable state on lead detail
  • explain whether the blocker is:
    • no region
    • no active installer
    • no in-capacity installer

Installer changed after capture​

If an operator changes installer after capture:

  • preserve old assignment history
  • show whether old assignment was delivered
  • show whether replacement assignment was delivered
  • surface billing implications instead of hiding them

Do not redesign everything at once.

Use this order:

  1. Lock product rules and IA
  2. Redesign lead detail
  3. Redesign installer detail
  4. Redesign dashboard
  5. Refine billing screens

Reason:

  • lead detail defines the core truth
  • installer detail defines allocation and capacity
  • dashboard should summarize those truths, not invent them

10. V1 UI Success Criteria​

The admin app is working when a non-technical operator can quickly answer:

  • Did this lead go out?
  • To who?
  • Did it fail?
  • What do I do next?
  • Is this installer full?
  • How much does this installer owe us?

If those answers are not obvious, the UI is still too complex.

  • docs/product/admin-operations-flow.md
  • docs/apps/admin-app-spec.md
  • docs/product/lead-lifecycle.md
  • docs/product/routing-assignment-states.md
  • docs/product/installer-tier-status-rules.md