Quote Follow-Up — system overview

Audience: developers & AI agents · Scope: the Quote Follow-Up System as a whole — a map to its spoke docs · Last reviewed: 2026-07-24

TL;DR — Quote Follow-Up lets a field agent update a quote (status / stage / dates / comments) from a no-login email link, keeps the sales forecast current, and drives the reminders and reporting around it. It spans a web page, a machine API, cron jobs, a Pipedrive webhook, and Google Sheets. This page maps the parts; each spoke has the detail.

The parts (map)

                 emailed magic link  (a scoped grant, NOT a login)
                                │
     ┌──────────────┬──────────┴───────────┬────────────────────┐
     ▼              ▼                      ▼                    ▼
  Landing page   Nudge cadence          Stage-sync log        Link API
  agent updates  → "due for a nudge"    → a row per stage/    mints a link for
  the quote      Google Sheet (cron)     status change (→Sheet) an automation
                                │
        quotes ↔ Pipedrive deals: import stages/pipelines · push status/stage · webhook back

Spoke	Doc	What it covers
Landing page	landing-page.md	the no-login update page — states, the save/write split, the data model
Authentication	authentication.md	the magic-link grant token (a scoped capability, not a login), its validation, endpoint gating, and the machine Link API that mints links
Pipelines & stages	pipeline-stages.md	the imported Pipedrive pipelines/stages behind the picker — multi-pipeline handling, won-derivation, the read-only admin lists
Nudge cadence	nudge-cadence.md	the cron that reconciles a Google Sheet of quotes "due for a follow-up nudge" (per-stage × value-bucket cadence)
Stage-sync sheet	stage-sync.md	appends a row on every deal stage/status change (site + webhook), mirrored to a Google Sheet
Link API (n8n)	link-api-n8n.md	consumer-facing guide for the machine endpoint (documented internally in authentication.md) that hands a magic link to an external automation

End-to-end flow

An agent gets an emailed magic link → opens the landing page → sets status / stage / dates / comments. That one write (a) syncs to the quote's Pipedrive deal (status, native stage, expected close date, a note), (b) stamps "stage last moved" and appends a stage-sync row (later mirrored to a Sheet), and (c) feeds the nudge engine, which lists quotes that have sat too long in a stage so an automation can re-prompt the agent — with a fresh magic link, closing the loop.

Shared concepts

The pieces every spoke leans on — documented once, here, with the detail linked:

• The magic-link token — a grant, not a login. A signed, expiring token identifies the agent and unlocks the follow-up tool for their own quotes; it never logs anyone in. The same minting code backs the landing page, the Link API, and the nudge sheet. Detail: authentication.md.
• Imported Pipedrive pipelines & stages. The stage picker, the nudge cadence, and the stage-sync stage name/probability all read the stages imported from Pipedrive into #__configbox_external_pipedrive_stages, curated in the backend (Settings → Quote Follow-ups). Detail: pipeline-stages.md.
• The quote ↔ Pipedrive deal link. Every spoke reads or writes the quote's pipedrive_* fields; the deal is the shared external record.

Dependencies (Integration layers)

Quote Follow-Up builds on shared layers documented at the top level — not part of this System:

• The quote — ../quotes/README.md is the object this System acts on: the serial, revisions, ownership, and the pipedrive_agent_feedback_* columns this System owns live there.
• Pipedrive — ../pipedrive/README.md (deal-update flow, webhook, the foundational layer) and ../pipedrive/deal-updates.md (which website action writes which deal field).
• Google Sheets — ../google-sheets/README.md, the export layer both the nudge and stage-sync sheets use (and its consumer inventory explains why the nudge sheet clears-and-appends rather than replacing).

Cross-cutting ops & testing

• Admin / operations: ../pipedrive/admin-manual.md.
• Go-live runbook: ../pipedrive/deployment.md.
• The scheduled jobs behind this System (the nudge build, the stage-sync export) are inventoried with every other cron in ../scheduled-jobs.md; what watches them is in ../monitoring.md.
• Testing: ../pipedrive/testing.md · ../testing/guide.md. The whole chain above is exercised end to end by one golden-path spec — nudge-due → emailed magic link → landing-page update → stage-sync row + captured Pipedrive deal — tests/specs/anon/quote-follow-up-nudge-to-deal.spec.ts (catalog); the per-part specs cover each slice in depth.
• Operator how-tos (data entry / settings, plain-language): the Admin Guide at admin-guide/quote-follow-up/.