Start Here

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.

Pick your path

I'm on a team (AM, Sales, Marketing…) What the platform does for you and how to use it day to day — no code.

I'm building or operating it Architecture, the edge Worker, deploys, n8n, endpoints.

I need the data model BigQuery datasets, billing rules, HubSpot, keyword KB, maps/LRC.

I'm an AI agent Curated map at /llms.txt · everything concatenated at /llms-full.txt.

The mental model

Web UI (Pages)   HubSpot card   Roam chat        ← 3 surfaces (clients)
     └───────────────┼──────────────┘
                     ▼
       ONE Worker: fcr-dashboard-api             ← all logic, at the edge
     (133 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:

1. One monolith Worker does all the compute, at Cloudflare’s edge. The UI is static; Roam/HubSpot are surfaces.
2. 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.
3. Precompute over live. The slow work (GBP, crawls, enrichment) is precomputed into cached “deal briefs” so reps get instant answers.

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
npm run dev                 # UI locally
cd worker && npx wrangler dev   # Worker locally

Key conventions (the stuff that bites)

• Auth: every endpoint needs x-api-key; DDL/writes also need x-admin-key.
• Ads spend is retail (what the client pays FCR) — never “media spend”.
• active_clients MRR: filter ri_period > 0 (DEA/Setup one-offs 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, never --force casually.

---

Maintained in docs/. If you change architecture, update the relevant page and the counts — they’re verified, not guessed.