System Architecture

How the Growth Intelligence Agent reasons over live SaaS data using tools, RAG, and an LLM.

Data & Request Flow

  Browser / API Client
        │
        ▼
  FastAPI Backend  (api/main.py · Vercel serverless)
        │
        ▼
  LangGraph ReAct Agent  (agent/agent.py)
  ┌─────┴─────────────────────────────────────┐
  │  System prompt + tool descriptions         │
  │  Max iterations: 8  ·  Model: Claude        │
  └─────┬─────────────────────────────────────┘
        │ selects tools as needed
  ┌─────┼──────────────────────────────────────────────────┐
  │     ▼               ▼               ▼                  │
  │  get_metric    get_pipeline    get_product_usage        │
  │  (metrics.csv) (opps+accts)   (usage events)           │
  │                                                         │
  │     ▼               ▼                                   │
  │  get_deals     get_company_context                      │
  │  (CRM stages)  (FAISS RAG over playbooks)               │
  └─────────────────────────────────────────────────────────┘
        │
        ▼
  Structured answer: Key Insight · Root Cause · Data · Actions

The 5 MCP-Pattern Tools

get_metric(query)
Keyword-maps natural language to rows in metrics.csv. Returns win rate, NRR, pipeline coverage, deal size, and 5 other KPIs — overall and by segment.
get_pipeline_by_segment(query)
Segments the CRM opportunity table by region, industry, or stage. Returns open pipeline value, deal counts, and win rates per segment.
get_product_usage(query)
Usage analytics with at-risk detection. Flags accounts with no activity in 30+ days. Can query by account ID (e.g. "account ACC0042").
get_deals_by_stage(query)
CRM deals filtered by mode: closing-this-month, high-value (top 20%), or stalled (no movement in 60+ days).
get_company_context(query)
RAG retrieval over 3 internal playbooks (ICP, growth strategy, pricing rules). Chunked at 800 chars with 100-char overlap, embedded with HuggingFace all-MiniLM-L6-v2, stored in FAISS. Returns top-4 relevant chunks. Degrades gracefully if vectorstore unavailable.

Stack

Python 3.12 FastAPI LangChain 1.x LangGraph (ReAct) Claude (Haiku / Sonnet) FAISS HuggingFace all-MiniLM-L6-v2 Pandas Vercel (serverless)

Data Layer

  scripts/generate_data.py     →  data/raw/*.csv
    300 accounts · 800 deals · 2,000 leads · 300 subscriptions
    7 industries · 4 regions · realistic distributions (seed=42)

  metrics/compute_metrics.py   →  data/processed/metrics.csv
    dbt-style models: win_rate, NRR, pipeline_coverage, etc.
    Regional win rates computed via accounts join

  rag/build_vectorstore.py     →  rag/vectorstore/ (FAISS index)
    3 markdown playbooks · 800-char chunks · 18 total vectors
GitHub Repository Live Dashboard API Reference