FCR Dashboard — Developer Onboarding

Start here. This is the map of the whole system for a new developer: what it is, how the pieces fit, where the code is, and where to read next. Each linked doc goes deep on one area.

What it is (in one minute)

The FCR Dashboard is an internal sales & account-management intelligence platform. It pulls FCR's data (CRM, billing, HubSpot deals, GBP, ads, search, keywords, census/area) into BigQuery, puts an AI advisor (Claude) on top, and surfaces it in three places reps already work: a web dashboard, the HubSpot deal sidebar, and Roam chat. All three are clients of one back-end.

The mental model

   Web UI (Pages)   HubSpot card   Roam chat        ← 3 surfaces (clients)
        └───────────────┼──────────────┘
                        ▼
          ONE Worker: fcr-dashboard-api             ← all logic, at the edge
        (131 routes, Claude advisor, crons, queue)
                        │  reads
        ┌───────────────┼───────────────┬───────────────┐
     BigQuery        Vectorize          KV            external/live
   (warehouse)   (semantic search)   (cache)    (CRM, Google, Ahrefs, Meta)
        ▲
        │  writes (ETL)
     n8n workflows (cron) + BQ scheduled queries

Three things to internalise:

One monolith Worker does all the compute, at Cloudflare's edge. The UI is static; Roam/HubSpot are surfaces. (CF dashboard "Workers: 0 bound" = no other workers, not "no code".)
The Worker reads; n8n writes. ETL into BigQuery is owned by n8n cron jobs
- BQ scheduled queries. The Worker is mostly read-only over that data.
Precompute over live. The slow work (GBP, crawls, enrichment) is precomputed into cached "deal briefs" so reps get instant answers.

By team — the playbooks

Not a developer? Start with the role playbook for what the platform does for you: Account Managers · Sales · Marketing/Product/GTM · Business Planning · Operations — index: playbooks/.

The doc map — read in this order

#	Doc	What it covers
1	`fcr-dashboard-architecture-overview.md`	The big picture — surfaces, the edge Worker, data layer, the deal-brief system, the advisor, end-to-end flow, bindings/secrets/runtime reference, glossary
2	`bigquery-and-sync.md`	The data — datasets, the 78 `fcr_operations` tables by domain, and the daily/weekly/monthly sync sequence
3	`hubspot-data-architecture.md`	HubSpot deep-dive — open vs the 18-month closed cohort view, engagements, vector indexes, the deal-brief data flow
3b	`data-feeds-and-knowledge.md`	Feeds & how to update them — Google Ads/MC/GA4/GSC/GMB transfers + subscriber bridges, the customer site index, company knowledge base, product portfolio, outreach email templates
3c	CRM & billing — `billing-model.md` (the CRM billing model + revenue recognition), `BQ_ACTIVE_BILLING_EXTRACT.md` (order tables `Accounts_and_related_data` → the `active_clients` snapshot SQL), `billing-rules-comparison.md` (the per-view SQL differences: client / solution / revenue-bridge / AM-portfolio — MRR calc, setup/DEA, BG dedup), `suspension-treatment.md`	How CRM order data becomes billing numbers, and how each dashboard view's SQL differs
3d	CSO & area data — `data/map/DATA_DOCUMENTATION.md`	The 8 census/area sources (Census 2022, Pobal, valuation, CRO, new-dwelling completions, commencements), BQ storage + transforms. New-builds update + FB/IG reach (manual) covered here + below.
3e	FCR Keyword Knowledge Base — `data/keyword-intelligence/REPORT_1_Structure_and_Maintenance.md` (8 sources, schema, cleaning, maintenance), `data/keyword-intelligence/README.md` (the SQL normalisation pipeline), `data/keyword-intelligence/REPORT_3_Facebook_Reach_Integration.md` (manual FB/IG reach)	How the keyword KB is built — every source, the normalisation/cleaning, the monthly maintenance, and the "what customers care about" category inputs
4	`worker-endpoints.md`	The API surface — all 131 Worker routes grouped by domain
4b	`maps-and-lrc.md`	Maps & LRC — how the rank-check grid computes (SerpAPI), LRC vs Dashboard Discovery vs Prospect, which service supplies each data point (Pleper/SerpAPI/Maps/CSO/FB-IG/Keyword-KB), local-insights maps, quick-who-ranks, identify-competitors. Read-the-report explainer: `lrc-methodology.md`
5	`n8n-workflows.md`	Automation — the 55 n8n workflows, what each does, and the Worker handler that twins/replaces it
6	`commit-and-deploy.md`	Shipping — git policy, the gated deploy script, Pages + HubSpot card deploys, rollback
—	`fcr-dashboard-architecture-deck.md`	Slide-by-slide storyboard to present all of the above

Where the code lives

Surface	Path	Ships to
Worker (API + advisor + crons)	`worker/src/**` (entry `index.js`, `router.js`, 126 `handlers/`)	one edge bundle on CF
Web UI (React/Vite)	`src/**`	CF Pages (`fcr-dashboard-ui`)
HubSpot card	`hubspot-extension/src/**`	HubSpot UI-extension sandbox
Deploy + lint config	`scripts/` (`deploy-worker.sh`, eslint config)	—

Repo: github.com/FCR4IE/DASHBOARD. Source of truth for all three surfaces.

Quick start

git clone https://github.com/FCR4IE/DASHBOARD.git && cd DASHBOARD
# get .env.local from a teammate (CF tokens, API keys — never committed)
npm install

# UI locally
npm run dev

# Worker locally (from worker/)
cd worker && npx wrangler dev

# Smoke-test a live endpoint
API_KEY=$(grep ' x-api-key=' .env.local | cut -d= -f2-)
curl -s -H "x-api-key: $API_KEY" \
  "https://fcr-dashboard-api.fcrmedia.workers.dev/health"   # lists all routes

To ship: edit → commit (specific files) → scripts/deploy-worker.sh → git push. Full rules in commit-and-deploy.md.

Key conventions (the stuff that bites)

Auth: every endpoint needs x-api-key (from .env.local). DDL/writes also need x-admin-key via /dashboard-bq-admin.
Ads spend is retail (what the client pays FCR) — never "media spend".
active_clients MRR: filter ri_period > 0 (DEA/Setup one-offs carry the full amount and overstate MRR).
hubspot_deals is open-only; closed deals live in the 18-month back-catalogue.
n8n tenant is fcrmedia.app.n8n.cloud — never the legacy dcathal one.
Deploy gate refuses a dirty worker/ tree — commit first (or stash unrelated WIP), never --force casually.
Vector indexes can include non-clients (free listings) — split, don't just read, when presenting "clients".

Maintained in docs/. If you change architecture, update the relevant doc and the counts (they're verified, not guessed).

FCR Dashboard documentation · generated from docs/ · keep counts verified, not guessed.