# joaquinllenado/recurve-ai architecture

> Architecture diagram of the GitHub repository joaquinllenado/recurve-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joaquinllenado/recurve-ai
- Repository: https://github.com/joaquinllenado/recurve-ai

## Overview

Recurve AI is an autonomous SDR agent: a product description enters through the dashboard, the backend coordinates market research and strategy generation, then validates targeted leads and stores learned corrections. Scout-triggered signals add a separate outreach-pivot path. The dashboard presents strategy, leads, activity, history, and the knowledge graph. Relationships are based on the excerpts, SOURCE INDEX references, and README; unsampled API and UI behavior is represented only where documented, so some links are omitted.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/main.py`](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/main.py) (FastAPI routes), [`backend/agent/strategy.py`](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/strategy.py) (Strategy generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_product_input["Product input<br/>[ProductInput.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_dashboard_app["Dashboard<br/>[App.tsx]"]
  node_strategy_panel["Strategy panel<br/>[StrategyPanel.tsx]"]
  node_leads_table["Lead table<br/>[LeadsTable.tsx]"]
  node_activity_feed["Activity feed<br/>[ActivityFeed.tsx]"]
  node_activity_hook["Feed connection<br/>[useActivityFeed.ts]"]
  node_graph_view["Knowledge graph"]
  node_timeline["Strategy timeline"]
  node_admin["Admin controls<br/>[AdminPage.tsx]"]
end

subgraph group_api["Backend API"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
end

subgraph group_agent["Agent workflows"]
  node_strategy_flow["Strategy generation<br/>[strategy.py]"]
  node_validation_flow["Lead validation<br/>[validation.py]"]
end

subgraph group_integrations["Services and state"]
  node_market_research["Web research<br/>[tavily_service.py]"]
  node_language_model["SLM inference<br/>[slm_service.py]"]
  node_graph_service["Graph access<br/>[neo4j_service.py]"]
  node_knowledge_graph[("Neo4j store")]
  node_activity_manager["Activity broadcast<br/>[feed_manager.py]"]
  node_voice_service["Voice transcription"]
end

subgraph group_scout["Scout pivots"]
  node_pivot_flow["Trigger pivot<br/>[scout_trigger.py]"]
  node_pivot_agent["Pivot drafting<br/>[pivot.py]"]
  node_scout_worker["Signal monitor<br/>[scout.py]"]
end

node_user(("Sales operator"))
node_web_search{{"Tavily"}}
node_pioneer{{"Fastino Pioneer"}}
node_status_source(("Signal endpoint"))
node_modulate{{"Modulate API"}}

node_user -->|"provides description"| node_product_input
node_product_input -->|"submits product"| node_api_client
node_api_client -->|"calls API"| node_backend_api
node_backend_api -->|"starts pipeline"| node_strategy_flow
node_strategy_flow -->|"researches market"| node_market_research
node_strategy_flow -->|"generates strategy"| node_language_model
node_strategy_flow -->|"reads lessons, stores strategy"| node_graph_service
node_market_research -->|"searches web"| node_web_search
node_language_model -->|"runs inference"| node_pioneer
node_graph_service -->|"reads and writes"| node_knowledge_graph
node_backend_api -->|"starts validation"| node_validation_flow
node_validation_flow -->|"fact-checks leads"| node_market_research
node_validation_flow -->|"classifies leads"| node_language_model
node_validation_flow -->|"stores evidence, lessons"| node_graph_service
node_strategy_flow -->|"broadcasts events"| node_activity_manager
node_validation_flow -->|"broadcasts progress"| node_activity_manager
node_scout_worker -->|"polls status"| node_status_source
node_scout_worker -->|"broadcasts changes"| node_activity_manager
node_scout_worker -->|"triggers flow"| node_pivot_flow
node_pivot_flow -->|"coordinates drafting"| node_pivot_agent
node_pivot_agent -->|"drafts outreach"| node_language_model
node_pivot_agent -->|"records pivot"| node_graph_service
node_backend_api -->|"transcribes audio"| node_voice_service
node_voice_service -.->|"sends audio"| node_modulate
node_activity_manager -->|"streams events"| node_activity_hook
node_activity_hook -->|"provides events"| node_activity_feed
node_dashboard_app -->|"renders"| node_product_input
node_dashboard_app -->|"renders"| node_strategy_panel
node_dashboard_app -->|"renders"| node_leads_table
node_dashboard_app -->|"renders"| node_activity_feed
node_dashboard_app -->|"renders"| node_graph_view
node_dashboard_app -->|"renders"| node_timeline
node_strategy_panel -->|"fetches strategy"| node_api_client
node_leads_table -->|"fetches leads"| node_api_client
node_graph_view -->|"fetches graph"| node_api_client
node_timeline -->|"fetches history"| node_api_client
node_admin -->|"calls controls"| node_api_client
node_backend_api -->|"serves graph and records"| node_graph_service

click node_product_input "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/ProductInput.tsx"
click node_api_client "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/api/client.ts"
click node_dashboard_app "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/App.tsx"
click node_strategy_panel "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/StrategyPanel.tsx"
click node_leads_table "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/LeadsTable.tsx"
click node_activity_feed "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/ActivityFeed.tsx"
click node_activity_hook "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/hooks/useActivityFeed.ts"
click node_graph_view "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/GraphVisualization.tsx"
click node_timeline "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/StrategyTimeline.tsx"
click node_admin "https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/pages/AdminPage.tsx"
click node_backend_api "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/main.py"
click node_strategy_flow "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/strategy.py"
click node_validation_flow "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/validation.py"
click node_pivot_flow "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/scout_trigger.py"
click node_pivot_agent "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/pivot.py"
click node_scout_worker "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/workers/scout.py"
click node_market_research "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/tavily_service.py"
click node_language_model "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/slm_service.py"
click node_graph_service "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/neo4j_service.py"
click node_activity_manager "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/feed_manager.py"
click node_voice_service "https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/modulate_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_product_input,node_api_client,node_dashboard_app,node_strategy_panel,node_leads_table,node_activity_feed,node_activity_hook,node_graph_view,node_timeline,node_admin toneBlue
class node_backend_api toneAmber
class node_strategy_flow,node_validation_flow,node_modulate toneMint
class node_market_research,node_language_model,node_graph_service,node_knowledge_graph,node_activity_manager,node_voice_service toneRose
class node_pivot_flow,node_pivot_agent,node_scout_worker,node_user,node_web_search,node_pioneer,node_status_source toneIndigo
```

## Components

### Dashboard

- [Product input](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/ProductInput.tsx): `frontend/src/components/ProductInput.tsx`
- [API client](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Dashboard](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Strategy panel](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/StrategyPanel.tsx): `frontend/src/components/StrategyPanel.tsx`
- [Lead table](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/LeadsTable.tsx): `frontend/src/components/LeadsTable.tsx`
- [Activity feed](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/ActivityFeed.tsx): `frontend/src/components/ActivityFeed.tsx`
- [Feed connection](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/hooks/useActivityFeed.ts): `frontend/src/hooks/useActivityFeed.ts`
- [Knowledge graph](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/GraphVisualization.tsx): `frontend/src/components/GraphVisualization.tsx`
- [Strategy timeline](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/components/StrategyTimeline.tsx): `frontend/src/components/StrategyTimeline.tsx`
- [Admin controls](https://github.com/joaquinllenado/recurve-ai/blob/main/frontend/src/pages/AdminPage.tsx): `frontend/src/pages/AdminPage.tsx`

### Backend API

- [FastAPI routes](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/main.py): `backend/main.py`

### Agent workflows

- [Strategy generation](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/strategy.py): `backend/agent/strategy.py`
- [Lead validation](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/validation.py): `backend/agent/validation.py`

### Services and state

- [Web research](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/tavily_service.py): `backend/services/tavily_service.py`
- [SLM inference](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/slm_service.py): `backend/services/slm_service.py`
- [Graph access](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/neo4j_service.py): `backend/services/neo4j_service.py`
- **Neo4j store**
- [Activity broadcast](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/feed_manager.py): `backend/services/feed_manager.py`
- [Voice transcription](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/services/modulate_service.py): `backend/services/modulate_service.py`

### Scout pivots

- [Trigger pivot](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/scout_trigger.py): `backend/agent/scout_trigger.py`
- [Pivot drafting](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/agent/pivot.py): `backend/agent/pivot.py`
- [Signal monitor](https://github.com/joaquinllenado/recurve-ai/blob/main/backend/workers/scout.py): `backend/workers/scout.py`

### Other components

- **Sales operator**
- **Tavily**
- **Fastino Pioneer**
- **Signal endpoint**
- **Modulate API**

## Connections

- Sales operator → Product input: provides description (evidence: `README.md`)
- Product input → API client: submits product (evidence: `frontend/src/components/ProductInput.tsx`)
- API client → FastAPI routes: calls API (evidence: `frontend/src/api/client.ts`)
- FastAPI routes → Strategy generation: starts pipeline (evidence: `backend/main.py`)
- Strategy generation → Web research: researches market (evidence: `backend/agent/strategy.py`)
- Strategy generation → SLM inference: generates strategy (evidence: `backend/agent/strategy.py`)
- Strategy generation → Graph access: reads lessons, stores strategy (evidence: `backend/agent/strategy.py`)
- Web research → Tavily: searches web (evidence: `backend/services/tavily_service.py`)
- SLM inference → Fastino Pioneer: runs inference (evidence: `backend/services/slm_service.py`)
- Graph access → Neo4j store: reads and writes (evidence: `backend/services/neo4j_service.py`)
- FastAPI routes → Lead validation: starts validation (evidence: `backend/main.py`)
- Lead validation → Web research: fact-checks leads (evidence: `backend/agent/validation.py`)
- Lead validation → SLM inference: classifies leads (evidence: `backend/agent/validation.py`)
- Lead validation → Graph access: stores evidence, lessons (evidence: `backend/agent/validation.py`)
- Strategy generation → Activity broadcast: broadcasts events (evidence: `backend/agent/strategy.py`)
- Lead validation → Activity broadcast: broadcasts progress (evidence: `backend/agent/validation.py`)
- Signal monitor → Signal endpoint: polls status (evidence: `backend/workers/scout.py`)
- Signal monitor → Activity broadcast: broadcasts changes (evidence: `backend/workers/scout.py`)
- Signal monitor → Trigger pivot: triggers flow (evidence: `backend/workers/scout.py`)
- Trigger pivot → Pivot drafting: coordinates drafting
- Pivot drafting → SLM inference: drafts outreach (evidence: `backend/agent/pivot.py`)
- Pivot drafting → Graph access: records pivot (evidence: `backend/agent/pivot.py`)
- FastAPI routes → Voice transcription: transcribes audio (evidence: `backend/main.py`)
- Voice transcription → Modulate API: sends audio
- Activity broadcast → Feed connection: streams events (evidence: `README.md`)
- Feed connection → Activity feed: provides events (evidence: `frontend/src/App.tsx`)
- Dashboard → Product input: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Strategy panel: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Lead table: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Activity feed: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Knowledge graph: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Strategy timeline: renders (evidence: `frontend/src/App.tsx`)
- Strategy panel → API client: fetches strategy (evidence: `frontend/src/components/StrategyPanel.tsx`)
- Lead table → API client: fetches leads (evidence: `frontend/src/components/LeadsTable.tsx`)
- Knowledge graph → API client: fetches graph (evidence: `frontend/src/components/GraphVisualization.tsx`)
- Strategy timeline → API client: fetches history (evidence: `frontend/src/components/StrategyTimeline.tsx`)
- Admin controls → API client: calls controls (evidence: `frontend/src/pages/AdminPage.tsx`)
- FastAPI routes → Graph access: serves graph and records (evidence: `backend/main.py`)
