17 - CARR Platform Architecture (Current Build)

What the CARR platform is made of today — the "Current Virtual Environment." This is the clean overview discussed on the 2026-07-21 working session. The platform is four layers: the app users see, the Edge Functions (backend logic) it calls, the database underneath, and the external supply chain that keeps it fed. Understanding all four is required before planning how each moves to Azure.
Triggers: "architecture overview", "current build", "virtual environment", "four layers", "how is carr built", "what does carr run on".

How it's built and hosted today

Layer 1 — The App (what users see)

The CARR Intel Hub is a React/Vite single-page application (SPA) with 22+ pages: Accounts, Target Universe, Campaigns, Pipeline, Content Studio, Team Analytics, and more.

How it's built:
- Source code lives in GitHub (carr-biosystems-hub repository)
- Built with React 18 + TypeScript + Vite (standard modern web stack)
- Developed by BioCreative using Windsurf IDE; code changes are committed to GitHub

How it's hosted:
- Lovable watches the GitHub repo (via sync) and serves the compiled static files on its CDN
- A custom domain purchased by BioCreative points to Lovable's hosting
- Lovable is hosting only — it provides no auth, no data, no build logic. It is purely a static-file CDN

How login/access works:
- BioCreative manually adds users to the user_profiles table in Supabase and creates their Supabase Auth credentials (email + password)
- The frontend uses supabase-js to sign in (signInWithPassword) and get a session JWT
- Every page checks: (1) valid session exists, (2) user's is_active = true in user_profiles — shows the app or redirects to login
- The supabase-js library also connects the frontend to PostgREST (the auto-generated API) and the Edge Functions

What connects the app to the backend:
- PostgREST (Supabase's auto-API): the frontend reads/writes data via supabase-js → PostgREST → Postgres, with RLS enforcing per-user access
- Edge Functions (Layer 2 below): the app also calls supabase-js's functions.invoke() to run the backend verbs

Layer 2 — Edge Functions (backend logic)

Between the app and the database sits a tier of 26 Edge Functions — Deno/TypeScript serverless functions that hold the backend logic the app calls. Important: these run on Supabase Edge (Deno runtime), which is separate compute from the Postgres database — they are not stored inside the DB. They are the "back-end verbs":

The app invokes them with a session JWT; they in turn talk to the database over SQL/PostgREST. Full census (all 26 + their Azure landing): 08_edge_function_census.md.

Layer 3 — The Database (the engine room)

Everything the app does is powered by a Supabase-hosted PostgreSQL database. This is where the real value lives.

Key point: the database is not just storage — it is an active execution environment. The pg_cron jobs, pg_net/http outbound calls, and triggers mean the database does things on its own without any user or frontend interaction.

Layer 4 — The Supply Chain (three separate things to replace)

The CARR database doesn't fill itself. It is fed by a supply chain that runs outside the database on BC infrastructure. This layer is three separate things — and CARR has to stand up its own version of each. Keeping them separate matters because they are replaced in different ways: one is subscriptions, one is compute, one is SaaS workspaces.

4a — Data-source APIs (the feeds that continually pull data in)

The raw material. These APIs are pinged on a schedule to pull in life-science intelligence and people data.

• Life-science + news feeds: ClinicalTrials.gov (trials), NIH RePORTER (grants), SEC EDGAR (filings), PatentsView (patents), PubMed + 22+ RSS feeds (news/signal scoring)
• Sourcing + enrichment SaaS: Sales Navigator (lead search definitions), PhantomBuster (scrapes Sales Nav → ~81K contacts), Clay (Find-People + contact enrichment), FullEnrich (email find + verify)

What CARR must stand up: their own API subscriptions + keys for each third-party service, stored in Key Vault, plus the integration code (the pull/push chains) that calls them. This is a procurement + wiring task, not a rebuild.

4b — The Agent Virtual Environment (the compute that does the work)

The APIs are just taps — something has to run continuously to open them, capture the results, and turn raw data into CARR-ready records. Today that "something" is BC's virtual environment:

• bc-ops VPS crons: carr_burst_classify_seed.sh (every 30 min), sync_carr_emails.py (every 20 min), Clay push (manual)
• Colab notebooks: account import, contact import, account matcher, classifier, enrichment, Clay orchestration, batch email generation — run manually against the CARR DB

The work this environment does, in sequence: capture (pull from the 4a APIs) → summarize (score/condense news + signals) → match (resolve to canonical CARR accounts) → enrich (fill contact/company fields) → internalize (write clean records into the CARR DB for downstream app work).

What CARR must stand up: their own virtual environment — a set of containers / scheduled jobs (Azure Container Apps + Functions timers, or a VPS) running the 7-agent fleet (11_carr_agent_fleet.md) that manages the 4a APIs and performs this enrich/normalize/match pipeline. This is the genuine build.

4c — Outreach platforms + BC Hub (send + seed)

Distinct from the data-pull chain: the platforms that send outreach and the master DB that seeds CARR.

• HeyReach + EmailBison: LinkedIn + email send platforms, wired via 17 Edge Functions (Layer 2). Both a source (replies, accepted connections sync back) and a destination (sends go out)
• BC Hub DB feed: the BC Hub (mjsgtszehjltxmbxtctz, 17,290-company master) seeds CARR via sync RPCs: sync_cgt_accounts_from_hub, sync_clinical_trials_from_hub, sync_grants_from_hub, sync_news_from_life_science, sync_academic_*_from_hub, import_hub_contacts

What CARR must stand up: their own HeyReach/EmailBison workspaces + keys (the integration code moves with the Edge Functions). The Hub is retired over time — the 4b Ingestion agent pulls the 4a APIs directly instead of leaning on the Hub feed.

The pipeline in one line

4a APIs (pull)  →  4b Agent VE (capture · summarize · match · enrich · internalize)  →  CARR DB (Layer 3)  →  Edge Functions + app (Layers 2–1)
                                   ↕
                     4c Outreach (send) + Hub (seed)

This is the layer BW has the least visibility into today. It runs entirely on BC infrastructure and pushes into CARR via webhooks and sync RPCs. The full inventory is in 09_upstream_data_agents.md; the target-state fleet is in 11_carr_agent_fleet.md.

Migration target for each layer

The full component-by-component crosswalk is in 05_carr_migration_map.md. The sequenced migration plan with decisions and blockers is in 18_migration_roadmap.md.