Agency onboarding platform + client scorecard

1. Stage 01

   Access & tenancy

   The host router, token kinds and auth that keep two products safely inside one deployment.

   • Host-based router · Guard · Astro middleware — A pure, I/O-free decision function maps the request host to admin, portal, or nothing — and an unrecognised host resolves to null, which 404s every path. → Agency admin host (admin host), Client portal host (portal host), Three token kinds (unknown host → 404)
   • Agency admin host · Source · Astro (SSR) — The agency’s internal surface — pipelines board, onboarding tracker, metrics — with every client-portal path explicitly 404’d on this host. → Admin & client auth
   • Client portal host · Source · Astro (SSR) — The client-facing surface — start, welcome, the tokenized intake wizard, the tracker and corrections — with admin paths and admin APIs 404’d and a noindex header applied. → Admin & client auth, Intake wizard (public intake path)
   • Three token kinds · Guard · JWT (HS256, one secret) — Session (admin, 7 days), client (portal, 30 days) and intake (URL-borne, 14 days) tokens share a signing secret but carry distinct kind claims, alongside a short-lived magic-link kind. → Admin & client auth, Tokenized intake link (distinct kind claim)
   • Admin & client auth · Guard · Astro API + argon2id — Two gates: the agency signs in by a constant-time, non-short-circuiting password compare or an email magic link whose allowlist is re-checked at redemption, and the studio owner signs in with argon2id hashing, a five-failures-per-fifteen-minutes lockout and single-use expiring reset tokens. → Admin onboarding tracker (agency session), Pipelines board (agency session), Client tracker & corrections (client session, own studio only), Nine-point score (the agency grades by hand)

2. Stage 02

   Sales capture & pipeline

   Lead capture, booking, and the orchestrator that owns every stage move.

   • Landing-page opt-in · Capture · Astro API endpoint — The public lead-capture endpoint — origin-restricted CORS plus a honeypot — upserts the contact into the CRM, tags the lead, stamps its source, and opens an opportunity on a two-stage pre-booking pipeline holding leads who have not yet booked. → Book strategy call, Eight-stage sales pipeline (call booked)
   • Book strategy call · Calendar · Astro API + CRM calendar — Free calendar slots are fetched server-side and proxied to the page so the integration token never reaches the browser; booking creates the appointment and, best-effort, advances the pre-booking opportunity to its booked stage. → CRM webhook receiver (appointment event)
   • Stateless orchestrator · Workflow · TypeScript over the CRM API — A single module owning every stage move, tag, field write, task and campaign enrolment; it keeps no state of its own — every contact’s state lives in CRM custom fields. → Resolve-by-name, Eight-stage sales pipeline, 20 lifecycle emails (exclusive enrolment)
   • Resolve-by-name · API / service · CRM API + in-process cache — Pipelines, stages, workflows and contact custom fields are looked up by their human name at runtime and cached for five minutes; no raw CRM id lives in the code. If a named workflow does not exist yet, enrolment returns false and logs which one to build while the stage move and tags still apply. → Eight-stage sales pipeline (stage + tags apply either way)
   • Eight-stage sales pipeline · CRM record · GoHighLevel pipeline — Call booked, no-show, done or pending next call, next call scheduled, its no-show, deciding, won, long-term nurture — each transition driven by an appointment or pipeline event, and a second no-show creating a task for the agency principal to phone the prospect personally. → Daily stage sweep (stage ages out), Won → client (won — client)

3. Stage 03

   Signed → onboarding

   The moment a won deal becomes a studio record, a milestone set and a tokenized intake link.

   • Won → client · Workflow · Orchestrator — One routine moves the deal to won, tags the contact as a client, removes every sales campaign, stamps the signed date, creates the onboarding record, enrols the onboarding campaign and opens a fulfilment task. → Create studio record
   • Create studio record · Data store · PostgreSQL + Drizzle — Creates the studio row and all seven milestone rows in one transaction, mints a unique studio key, generates the intake token, writes the intake URL back to the CRM contact and seeds an empty scorecard — idempotent on the CRM contact id and wrapped so any failure returns null rather than breaking the sales stage move. → Studios & milestones, Tokenized intake link, Score storage & mirror (seed an empty score)
   • Tokenized intake link · Guard · JWT (14-day) — The intake link is a signed 14-day token carrying the studio key and its own kind claim; expired or malformed tokens land on a dedicated expiry page rather than an error. → Intake wizard

4. Stage 04

   Provisioning & reconcile

   Two routes to a live CRM sub-account, and the reconciliation that makes them converge on one.

   • Self-serve checkout · Source · CRM hosted checkout — For self-serve signups the CRM’s own checkout creates the sub-account, loads the snapshot, enrols the plan and enables rebilling; the platform only ever reacts to that. → Signup webhook, Reconcile sub-account (welcome-page poll)
   • Reconcile sub-account · Scheduled job · TypeScript + Postgres — Verifies the location is genuinely activated on the right plan, enriches its name and email by paging the account list, then links or creates exactly one studio. → One studio per account, Send-once gate
   • One studio per account · Data store · Postgres partial unique index — A partial unique index on the CRM location id, only where non-null, makes duplicate creation a constraint violation — which the code detects by walking the error’s cause chain and then re-reads the winning row. → Create studio record (winner re-read)
   • Send-once gate · Guard · Postgres timestamp — The CRM handoff — link the contact, write the intake URL, enrol the onboarding campaign — happens once and is gated on a sent-at timestamp; if the contact does not exist in the CRM yet it no-ops and the cron retries. → Tokenized intake link (intake URL written), 20 lifecycle emails (a CRM workflow sends the welcome), Reconcile backstop cron (contact not in CRM yet — retry)
   • Agency-API provisioning · API / service · CRM agency API — A direct sub-account creation call built from the latest intake submission, with a business-address-to-tax-address fallback and an early return if the studio is already linked — deliberately no longer wired into the intake path and reachable only from an admin retry button. → Reconcile sub-account

5. Stage 05

   Client intake portal

   The wizard the studio owner fills in, and everything that protects it.

   • Intake wizard · Capture · Astro page (token-scoped) — The multi-step intake form the studio owner opens straight from the tokenized link with no login, autosaved server-side against the token rather than in the browser. → Validated upload, Submit intake
   • Validated upload · API / service · Astro API endpoint — Logo and document uploads are size-capped, MIME-allowlisted, and then actually decoded to check their magic bytes — a container claiming to be an image but isn’t is rejected outright. → Submit intake (magic bytes valid)
   • Submit intake · Workflow · Astro API + Postgres — Validates server-side, writes the submission to Postgres first, advances the intake milestone, and only then syncs to the CRM and provisions the client login — CRM failures become warnings on the response, never lost data. → Submissions & corrections (Postgres first), Messaging-compliance branch, Provision client login, Advance milestone (intake milestone auto-done)
   • Provision client login · Workflow · argon2 + CRM workflow — On first submit the app mints a readable temporary password with ambiguous glyphs removed, stores only its hash, writes the plaintext to a CRM contact field, and lets a dedicated CRM workflow deliver it and then clear the field — returning null if a password already exists. → Admin & client auth (credentials delivered by a CRM workflow), Studio live
   • Messaging-compliance branch · Decision · Intake step + CRM field — The intake asks whether the studio has a federal tax id and branches into a standard registration, a sole-proprietor fallback, or a pending state — with a monotonic guard so a live registration can never regress to pending on a correction resubmit. → Advance milestone

6. Stage 06

   Data layer

   The Postgres tables that are the system of record for onboarding.

   • Studios & milestones · Data store · PostgreSQL — One row per studio — key, name, legal and address fields, timezone, brand JSON, domain, lifecycle stage, CRM location and contact ids, registration type, intake-link sent-at — and seven milestone rows beneath it: welcome, intake, account setup, messaging compliance, branding, build, go-live, each with a status, an owner, an entered-at stamp and an ETA, cascade-deleted with the studio. → Admin onboarding tracker (board status derived), Client tracker & corrections
   • Submissions & corrections · Data store · PostgreSQL (jsonb) — The autosaved draft keyed by token, the immutable submitted payload keyed by studio with a submitted-at stamp, and a corrections table recording each correction’s scope, target, reason category, message, who raised it, status and resolved-at stamp.

7. Stage 07

   Milestones & corrections

   The seven-step tracker, the correction loop, the go-live flip and the boards.

   • Advance milestone · Workflow · Astro API + Postgres — The admin sets a milestone’s status, owner and ETA; the intake milestone completes itself automatically on submit. → Studios & milestones, Go-live flip (milestone 7 done)
   • Flag a correction · Workflow · Astro API + Postgres + email — Raising a correction inserts the row, forces the field reference to null for milestone-scope corrections, flips the milestone to "needs you" with the client as owner, resolves the owner’s email and notifies them. → Submissions & corrections, Client tracker & corrections (ownership moves to the client)
   • Client tracker & corrections · Human · Astro pages (client-gated) — The studio’s own view of its seven milestones and percentage progress, plus the list of what needs amending and the resubmit path out of it — all gated on a client session that only ever resolves its own studio. → Submit intake (resubmit)
   • Go-live flip · Outcome · PostgreSQL — Completing the seventh milestone flips the studio’s lifecycle stage to live — a pure database operation with no CRM calls at all. → Admin onboarding tracker, Studio live
   • Admin onboarding tracker · Report · Astro page — The agency’s cross-studio milestone board, with correction, advance, provisioning-retry and link-resend actions attached — each studio deriving to ready, blocked, aging past three weeks, or active, and feeding KPIs for studios in onboarding, average days to live, blocked or stalled, go-lives this week, and what needs the agency’s action. → Agency-API provisioning (manual provisioning retry), Flag a correction, Advance milestone
   • Pipelines board · Report · Astro page + polled beacon — A kanban of live CRM opportunities with per-card signed scorecard links and appointment-date enrichment, refreshed by polling a lightweight "something changed" beacon rather than refetching the board. → HMAC-signed link (per-card link)
   • Studio live · Outcome · Platform + CRM — A provisioned sub-account, a completed intake, seven milestones done, a client login, and a scorecard rendering inside the studio’s own dashboard.

8. Stage 08

   Scorecard

   The nine-point score — how it is stored, signed, embedded and revoked.

   • Nine-point score · Report · TypeScript model — Nine graded elements in three groups of three — the core system, paid and active-search acquisition, and passive organic presence — each graded empty, red, amber or green with free-text comments, graded by hand rather than derived. → Score storage & mirror
   • Score storage & mirror · CRM record · CRM custom values + fields — Each studio’s score is one JSON custom value in the agency’s own CRM location, all of them readable in a single list call; the nine states are additionally mirrored into nine per-contact dropdown fields, with the mirror deliberately skipped at conversion while the score is still empty. → HMAC-signed link
   • HMAC-signed link · Guard · HMAC-SHA256 — The widget URL carries the client key plus a base64url HMAC of it; verification splits on the last separator, length-checks and compares in constant time. → Embedded scorecard (signature valid)
   • Embedded scorecard · Report · Astro route in an iframe — A public, read-only, noindex route rendering the score as an interaction-disabled graphic, embedded as a custom-HTML widget inside each studio’s own CRM dashboard — and the only route exempted from the deployment’s deny-framing header. → Studio live

9. Stage 09

   Webhooks, crons & assurance

   Real-time events, scheduled sweeps, lifecycle email, the isolated risk and the tests.

   • CRM webhook receiver · Trigger · Astro API endpoints — Receives appointment, pipeline and conversion events authenticated by a shared secret compared in constant time — and if the secret is not configured it logs once and rejects everything. Two legacy lead receivers alongside it verify a real body HMAC, hex-decoded, length-checked and timing-safe. → Normalize & dedupe
   • Normalize & dedupe · Guard · TypeScript + TTL map — Maps the CRM’s native payload into three internal event shapes — tolerating two misspelled vendor field names, ignoring a status field that describes the slot rather than the appointment, and trimming trailing spaces out of custom-data keys — then collapses re-deliveries on a key built from the event’s own shape, held in a self-pruning ten-minute map. → Stateless orchestrator (not a re-delivery)
   • Daily stage sweep · Scheduled job · Vercel cron (daily) — Four age-based rules retire stalled opportunities — two no-show stages after five days, a pending-next-call stage after a week, the deciding stage after three weeks — each writing a reason, moving the deal to long-term nurture with a recurring monthly touch, and re-stamping the entered-at timestamp, with per-rule error isolation and a structured run report. → Eight-stage sales pipeline (moved to long-term nurture)
   • Signup webhook · Trigger · Astro API endpoint — The checkout push, secret-authenticated across three possible carriers because the vendor may drop headers, which recovers the contact id from the email when the vendor’s merge field arrives empty, discards the location id when it resolves to the agency’s own account, and always answers 200 once authorized so the vendor does not hammer retries. → Reconcile sub-account
   • Reconcile backstop cron · Scheduled job · Vercel cron (minutes) — Pages the account list, skips anything not activated on the right plan, and skips only studios that are both linked and already emailed — so a "created but never emailed" partial failure is repaired on the next pass. → Reconcile sub-account (backstop, every few minutes)
   • 20 lifecycle emails · Message · JSON definitions → renderer → CRM — Twenty branded emails across eight campaigns — call confirmation and reminder, two no-show drips, a pending-next-step drip, a five-touch conversion drip, three onboarding emails, a recurring long-term monthly, and a payment receipt — authored as structured JSON, rendered to reviewable HTML previews and pushed by name.
   • Quarantined risk module · Guard · Node scripts outside the app — Five decisions were recorded before any code existed, and the one that carries real risk — using the vendor’s unsupported internal API to create workflows the public API cannot — is confined to a clearly marked toolchain living entirely outside the application source, with only two scripts ever touching a harvested token and everything built to draft for a human to publish. → 20 lifecycle emails (workflows built to draft)
   • Fail-closed test suite · Report · Vitest — Twenty-five test files whose security-relevant cases assert the invariants directly — unknown host denied, a client token rejected by the admin gate, a client token resolving only its own studio, submissions persisted before any CRM call, the enumeration-free uniform responses, one studio per CRM account enforced at the database level, and the idempotency of every retry path. → Host-based router (asserts default-deny), One studio per account (asserts one studio per account), Submit intake (asserts no data loss), Admin & client auth (asserts no cross-studio access)

Platforms · Astro · PostgreSQL · Drizzle · Vercel · GoHighLevel