Skip to main content

Admin Operations Flow

This is the north star operating model for the IED admin app.

Use this as the source of truth for:

  • how a lead moves from intake to installer delivery
  • what counts as captured vs delivered
  • when billing is created
  • how recommended vs compare-quotes allocation works
  • how installer capacity affects routing
  • which admin surfaces matter most
  • which failure scenarios operators need to see immediately

This document should drive admin dashboard IA, lead detail design, installer detail design, and billing visibility.

Detailed page and IA follow-up:

  • docs/product/admin-ia-and-operations-model.md

Core Product Idea​

IED is not primarily a CRM.

It is an operations system for:

  1. capturing inbound leads
  2. automatically assigning those leads to the right installer(s)
  3. automatically delivering those leads to installer(s)
  4. tracking whether delivery actually happened
  5. charging installers for successfully delivered leads
  6. enforcing installer capacity so routing stays commercially sane

If the admin app does not make those six things obvious, it is not serving the core product.

North Star Questions​

At any moment, the app should make it easy to answer:

  • Did a new lead come in?
  • Which installer or installers captured it?
  • Was the lead actually delivered to them?
  • If not, why not?
  • Does the installer still have capacity?
  • Should the lead be rerouted?
  • Is this lead now billable?
  • How much should this installer owe?

The single most important first question for a new lead is:

  • was this lead assigned to installer(s)
  • and were those installer emails actually sent

Canonical Flow​

The operational flow is:

  1. A lead is created from assessment intake.
  2. The system determines the lead path:
    • recommended_installer
    • compare_quotes
  3. The system auto-selects installer(s) using:
    • region ownership
    • installer status
    • regional tier
    • capacity limits
  4. The system creates per-installer assignment records.
  5. The system attempts installer delivery for each assignment.
  6. If delivery succeeds, the assignment becomes sent.
  7. A delivered assignment creates the commercial delivery event used for billing.
  8. Delivery and billing continue from that delivered state.

This means the real operational split is:

  • assignment created = captured
  • assignment sent = delivered
  • delivery event created = billable

Those are not the same thing and the UI should stop blurring them together.

Locked Product Decisions​

These are the current working product decisions for V1.

Brand new lead priority​

For a brand new lead, the first thing the admin should know is:

  • whether installer assignment happened
  • whether the lead email was successfully sent to those installer(s)

recommended_installer means exactly one installer should receive the lead.

If more than one eligible recommended installer exists in a region, the system should not send to all of them.

The preferred V1 allocation rule is:

  • use one installer only
  • allocate in FIFO order across eligible installers in that region
  • treat active-capacity limits and billing-cycle lead caps as hard eligibility gates, not fairness weights
  • when an installer receives a lead, they move to the back of the queue
  • still respect capacity, status, and region eligibility

Compare quotes mode​

compare_quotes means the lead should go to three installers only.

V1 target:

  • send to exactly 3 installers whenever 3 eligible installers exist
  • if fewer than 3 eligible installers exist, send to fewer and surface that clearly

The product model is still “get three quotes,” not “send to unlimited installers.”

Billable event​

V1 billing is based on delivery, not acceptance.

For now, a lead becomes commercially billable when:

  • the system successfully sends the lead to the installer via email

This means:

  • assignment created is not billable
  • installer intent is not part of the billing contract
  • delivery success is the billable event

Cycle-cap usage​

Cycle-cap usage is related to delivery, but it is not the same thing as invoice truth.

Default V1 behavior:

  • a successful delivery event is billable by default
  • the same delivery event counts against the installer's cycle cap by default

Operator override behavior:

  • admins may release a delivered event from cycle-cap usage without changing the finance ledger
  • lead-linked credits for objective invalid-lead faults may also auto-release cycle-cap usage
  • invoice adjustments remain the finance correction path when the correction is finance-only
  • cap release should always capture an explicit reason code

Failure visibility​

If installer delivery fails:

  • the app should show that failure clearly
  • the lead should still show who captured it
  • the app may auto-retry in the background
  • the failure badge and reason should stay visible until delivery succeeds

No eligible installer​

If no installer can receive a lead, that should surface in both places:

  • dashboard attention queue
  • lead detail summary

Language​

The app should de-emphasize technical routing language.

Preferred operator language:

  • installer delivery
  • lead distribution
  • captured by
  • delivered to
  • failed delivery
  • retry delivery

Use “routing” only where the underlying rule engine genuinely matters.

Data Truths​

Lead​

The lead is the customer-level record.

It answers:

  • who the customer is
  • what they asked for
  • what path they are on
  • whether the lead has reached installer distribution

Assignment​

An assignment is an installer-level routing record.

It answers:

  • which installer captured the lead
  • whether the lead was delivered to that installer
  • how that installer progressed the opportunity

Delivery​

Delivery is the moment the installer was actually sent the lead.

It answers:

  • whether the lead is commercially deliverable
  • whether billing should count it

Billing Event​

A billing event should only exist for delivered assignments.

Billing should not be based on:

  • lead creation
  • assignment creation
  • recommendation generation

Billing should be based on successful installer delivery.

Status Meaning​

Lead status​

Lead status is the customer journey.

See:

  • docs/product/lead-lifecycle.md

Assignment status​

Assignment status is installer-specific routing progress.

See:

  • docs/product/routing-assignment-states.md

Operational interpretation​

For dashboard and admin UX purposes:

  • pending assignment exists, but installer delivery is not confirmed yet
  • sent installer delivery succeeded and billing can proceed
  • contacted follow-up work has recorded real customer outreach after delivery
  • rerouted assignment was replaced by another installer path

Do not treat installer quote acceptance or refusal as part of the live admin assignment workflow. This app distributes leads; it does not model installer sales pipeline stages.

Routing Rules​

Routing should apply these gates in order:

  1. lead postcode belongs to an active region
  2. installer is linked to that region
  3. installer status is active
  4. installer tier is valid for this route
  5. installer is not at capacity

If any of those fail, the installer should not receive the lead.

Path-specific allocation rules​

The system should:

  • choose one eligible installer only
  • prefer region-linked recommended installers
  • if multiple recommended installers are eligible, use FIFO order within the region queue
  • if an installer is paused, inactive, or capped, skip them until they become eligible again
  • skip any installer who is paused, inactive, or at capacity
  • fall back to the next eligible installer rather than over-assigning the same installer forever

compare_quotes​

The system should:

  • choose up to three eligible installers
  • stop at three even if more are available
  • prefer preferred-tier installers before backup-tier installers
  • within each tier, use the same FIFO queue order and skip installers who are currently ineligible

Capacity Rules​

Installer capacity is not a reporting nice-to-have. It is core routing behavior.

The app should support:

  • per-installer active lead cap
  • visible current active load
  • clear “at capacity” state
  • automatic fallback to the next eligible installer

Capacity should be based on active assignments, not all historical assignments.

Practical default:

  • count pending, sent, and contacted as active load
  • do not count rerouted as active load

This supports the intended business behavior:

  • once an installer has enough live leads in hand, new leads should flow elsewhere
  • capacity is part of delivery allocation, not just reporting

If the team wants a different commercial rule later, that should be explicit and documented, not hidden inside the UI.

Primary Scenarios​

  1. Lead enters intake.
  2. System selects one eligible recommended installer.
  3. Assignment is created.
  4. Installer email/send succeeds.
  5. Assignment becomes sent.
  6. Billing event is created.
  7. Lead detail clearly shows:
    • captured by installer X
    • delivered successfully
    • billable

Scenario 2: Compare quotes happy path​

  1. Lead enters intake.
  2. System selects three eligible installers.
  3. Three assignments are created.
  4. Some or all are delivered.
  5. Billing events are created only for delivered assignments.
  6. Lead detail clearly shows:
    • captured by installers A, B, C
    • delivered to A and B
    • failed for C
    • total billable deliveries: 2

Scenario 3: Delivery failed​

  1. Assignment is created.
  2. Installer delivery fails.
  3. Assignment stays pending.
  4. No billing event is created.
  5. Admin sees:
    • captured installer
    • delivery failed
    • failure reason
    • retry action

This scenario must be obvious, not buried in audit trivia.

Scenario 4: Installer at capacity​

  1. Preferred installer is eligible by region and tier.
  2. Installer is already at active lead cap.
  3. System skips that installer.
  4. Lead routes to the next eligible installer.

The UI should make it easy to see:

  • why installer A did not get the lead
  • how many active leads installer A already has
  • which installer got the lead instead

Scenario 5: No eligible installer​

  1. Lead enters intake.
  2. No active, linked, in-capacity installer is available.
  3. Lead is not delivered.
  4. Operations sees an exception state immediately.

This should appear as an actionable queue, not a hidden system edge case.

Scenario 5a: Fewer than three eligible installers for compare quotes​

  1. Lead enters intake using compare_quotes.
  2. Fewer than three eligible installers exist.
  3. The system sends to the eligible installers it does have.
  4. The app makes it obvious that the lead did not reach the normal three-installer target.

This should not look like a silent success.

Scenario 6: Replace before delivery​

  1. Lead is pending with installer A.
  2. Installer A becomes unsuitable or fails operationally.
  3. Ops replaces the pending assignment with installer B before delivery succeeds.
  4. Original assignment becomes rerouted.
  5. New assignment is created and delivered if possible.

The UI should show the replacement chain clearly.

Scenario 7: Delivered path needs commercial correction​

If an assignment was already delivered and needs correction:

  • the original assignment should remain visible
  • the original billable event should remain visible
  • the UI should make clear whether the original assignment was already delivered

Commercially, this needs a separate rule:

  • if the original assignment was already delivered, it may already be billable
  • do not hide that state behind a routine reroute action

V1 should not hide this edge case behind generic installer replacement UI.

Admin IA Priorities​

Dashboard​

The dashboard should be an operations board, not a generic reporting wall.

Top-level sections should answer:

  • new leads waiting for review
  • leads captured today
  • leads still awaiting delivery
  • delivery failures needing retry
  • installers at or near capacity
  • billable deliveries today / this cycle
  • unpaid billing by installer

Lead detail​

Lead detail is the most important page in the app.

It should lead with:

  • lead status
  • selected path
  • captured installer(s)
  • delivery status per installer
  • failure reason if not delivered
  • billable delivery count

For V1, the lead detail page should assume the operator needs these questions answered without scrolling:

  • who captured this lead
  • did delivery succeed
  • does this need action right now

The lead detail page should make it obvious whether this lead:

  • has been captured
  • has been delivered
  • is billable
  • needs reroute or retry

Installer detail​

Installer detail should be treated as a live commercial operations view.

It should prioritize:

  • active status
  • regional tier links
  • active lead load
  • capacity cap
  • current billable deliveries
  • unpaid billing amount
  • recent delivery failures

Installer detail should help answer:

  • how many live leads this installer already has
  • whether they should receive the next lead
  • how much they currently owe

Billing​

Billing should be installer-centric.

For each installer, admin should be able to see:

  • delivered leads in the billing period
  • cap-used count
  • billable count
  • unit price or billing rule
  • amount due
  • paid vs unpaid
  • invoice/reconciliation status

V1 billing should be configurable enough to support likely real contracts:

  • billing cycle length in days
  • payment terms in days
  • maximum leads allowed in a billing period
  • different price for recommended vs compare-quotes lead types
  • tax rate

This should be installer-configurable or contract-configurable, not hardcoded into app logic forever.

Commercial Configuration​

The product should expect business-level configuration for each installer or installer contract.

At minimum, the commercial model will likely need:

  • billing cycle length example: 30, 60, or 7 days
  • payment terms in days
  • maximum leads per cycle
  • recommended-installer lead price
  • compare-quotes lead price
  • tax rate
  • current balance / receivables state

That gives the admin system enough information to:

  • auto-calculate what is owed
  • respect volume agreements
  • keep billing aligned with how the lead business actually operates

UI Principles​

Show capture first​

If the product auto-assigns leads, the first question is who captured the lead.

That should be front and center.

Show delivery second​

Assignment creation is not the same as delivery.

The app should make that difference painfully obvious.

Show billing consequence third​

If delivery happened, the commercial consequence should be visible immediately.

Prefer plain language​

Use operator language such as:

  • captured by
  • delivered to
  • failed to send
  • billable
  • at capacity
  • rerouted to

Avoid burying the core truth behind abstract routing jargon.

The app should be organized around these surfaces:

  • Dashboard operational overview
  • Leads lead queue and lead detail
  • Installers capacity, performance, billing, regional setup
  • Regions ownership and fallback coverage
  • Billing cap usage, billable deliveries, and money owed
  • Settings notification and operational rules

Anything else should support those surfaces, not compete with them.

What To De-emphasize​

The app should stop centering:

  • overly abstract routing mechanics
  • internal implementation history that hides the actual outcome
  • status complexity that does not help operators decide what to do next

The app should center:

  • did we capture it
  • did we deliver it
  • who owns it now
  • what needs action
  • what is billable

Immediate Dashboard Redesign Implications​

The next redesign pass should aim for:

  1. Dashboard widgets based on capture, delivery, capacity, and billing.
  2. Lead detail page as the main operating surface for a single lead.
  3. Installer detail page as the main surface for load and receivables.
  4. Billing screens built around delivered assignments, not generic financial placeholders.
  5. Routing UI simplified into outcome-first language.
  • docs/apps/admin-app-spec.md
  • docs/product/lead-lifecycle.md
  • docs/product/routing-assignment-states.md
  • docs/product/installer-tier-status-rules.md
  • docs/product/region-postcode-ownership-rules.md