# maan034/sales-research-agent architecture

> Architecture diagram of the GitHub repository maan034/sales-research-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maan034/sales-research-agent
- Repository: https://github.com/maan034/sales-research-agent

## Overview

Sales Research Agent is a C++ HTTP service for company research. Its principal flow accepts a company name at POST /api/research, validates it, delegates research through ResearchService, and returns company details and an ICP score. The tree and README also describe web-evidence gathering and LLM-backed extraction; the HTTP handler shown constructs an OpenAIResearchProvider directly, while Application.cpp assembles a separate web-research pipeline. Some provider internals and scoring logic were not sampled, so those links are limited to documented behavior and visible construction.

Main entry points: [`src/app/Application.cpp`](https://github.com/maan034/sales-research-agent/blob/main/src/app/Application.cpp) (Application bootstrap), [`src/research/ResearchService.cpp`](https://github.com/maan034/sales-research-agent/blob/main/src/research/ResearchService.cpp) (Research service), [`src/research/WebResearchProvider.cpp`](https://github.com/maan034/sales-research-agent/blob/main/src/research/WebResearchProvider.cpp) (Web research provider), [`include/sra/domain/ResearchResult.h`](https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/ResearchResult.h) (Research result)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entry"]
  node_main["HTTP server<br/>[main.cpp]"]
  node_controller["Research controller"]
  node_application["Application bootstrap<br/>[Application.cpp]"]
end

subgraph group_research["Research pipeline"]
  node_service["Research service"]
  node_provider_iface["Provider interface<br/>[ResearchProvider.h]"]
  node_web_provider["Web research provider"]
end

subgraph group_domain["Research domain"]
  node_evidence["Evidence records<br/>[Evidence.h]"]
  node_signals["Research signals<br/>[ResearchSignal.h]"]
  node_company["Company model<br/>[Company.h]"]
  node_result["Research result<br/>[ResearchResult.h]"]
end

subgraph group_integrations["Research integrations"]
  node_openai_provider["OpenAI provider"]
  node_demo_provider["Demo provider"]
  node_search_client["Web search client"]
  node_search_iface["Search interface<br/>[IWebSearchClient.h]"]
end

node_caller(("API caller"))
node_llm_service(("LLM service"))

node_caller -->|"sends request"| node_main
node_main -->|"dispatches request"| node_controller
node_controller -->|"calls research"| node_service
node_controller -->|"constructs provider"| node_openai_provider
node_service -->|"dispatches research"| node_provider_iface
node_service -->|"returns result"| node_result
node_web_provider -->|"searches web"| node_search_iface
node_search_client -->|"returns evidence"| node_evidence
node_openai_provider -.->|"requests extraction"| node_llm_service
node_application -->|"constructs client"| node_search_client
node_application -->|"constructs provider"| node_openai_provider
node_application -->|"constructs pipeline"| node_web_provider
node_application -->|"constructs service"| node_service
node_application -->|"calls research"| node_service
node_application -->|"prints summary"| node_result
node_web_provider -->|"produces signals"| node_signals
node_web_provider -->|"uses evidence"| node_evidence
node_result -->|"includes company"| node_company
node_result -->|"includes signals"| node_signals

click node_main "https://github.com/maan034/sales-research-agent/blob/main/src/main.cpp"
click node_controller "https://github.com/maan034/sales-research-agent/blob/main/src/api/ResearchController.cpp"
click node_service "https://github.com/maan034/sales-research-agent/blob/main/src/research/ResearchService.cpp"
click node_provider_iface "https://github.com/maan034/sales-research-agent/blob/main/include/sra/research/ResearchProvider.h"
click node_web_provider "https://github.com/maan034/sales-research-agent/blob/main/src/research/WebResearchProvider.cpp"
click node_openai_provider "https://github.com/maan034/sales-research-agent/blob/main/src/research/OpenAIResearchProvider.cpp"
click node_demo_provider "https://github.com/maan034/sales-research-agent/blob/main/src/research/DemoResearchProvider.cpp"
click node_search_client "https://github.com/maan034/sales-research-agent/blob/main/src/research/DuckDuckGoSearchClient.cpp"
click node_search_iface "https://github.com/maan034/sales-research-agent/blob/main/include/sra/research/IWebSearchClient.h"
click node_evidence "https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/Evidence.h"
click node_signals "https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/ResearchSignal.h"
click node_company "https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/Company.h"
click node_result "https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/ResearchResult.h"
click node_application "https://github.com/maan034/sales-research-agent/blob/main/src/app/Application.cpp"

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_main,node_controller,node_application toneBlue
class node_service,node_provider_iface,node_web_provider toneAmber
class node_evidence,node_signals,node_company,node_result,node_caller toneMint
class node_openai_provider,node_demo_provider,node_search_client,node_search_iface toneRose
class node_llm_service toneIndigo
```

## Components

### HTTP entry

- [HTTP server](https://github.com/maan034/sales-research-agent/blob/main/src/main.cpp): `src/main.cpp`
- [Research controller](https://github.com/maan034/sales-research-agent/blob/main/src/api/ResearchController.cpp): `src/api/ResearchController.cpp`
- [Application bootstrap](https://github.com/maan034/sales-research-agent/blob/main/src/app/Application.cpp): `src/app/Application.cpp`

### Research pipeline

- [Research service](https://github.com/maan034/sales-research-agent/blob/main/src/research/ResearchService.cpp): `src/research/ResearchService.cpp`
- [Provider interface](https://github.com/maan034/sales-research-agent/blob/main/include/sra/research/ResearchProvider.h): `include/sra/research/ResearchProvider.h`
- [Web research provider](https://github.com/maan034/sales-research-agent/blob/main/src/research/WebResearchProvider.cpp): `src/research/WebResearchProvider.cpp`

### Research domain

- [Evidence records](https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/Evidence.h): `include/sra/domain/Evidence.h`
- [Research signals](https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/ResearchSignal.h): `include/sra/domain/ResearchSignal.h`
- [Company model](https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/Company.h): `include/sra/domain/Company.h`
- [Research result](https://github.com/maan034/sales-research-agent/blob/main/include/sra/domain/ResearchResult.h): `include/sra/domain/ResearchResult.h`

### Research integrations

- [OpenAI provider](https://github.com/maan034/sales-research-agent/blob/main/src/research/OpenAIResearchProvider.cpp): `src/research/OpenAIResearchProvider.cpp`
- [Demo provider](https://github.com/maan034/sales-research-agent/blob/main/src/research/DemoResearchProvider.cpp): `src/research/DemoResearchProvider.cpp`
- [Web search client](https://github.com/maan034/sales-research-agent/blob/main/src/research/DuckDuckGoSearchClient.cpp): `src/research/DuckDuckGoSearchClient.cpp`
- [Search interface](https://github.com/maan034/sales-research-agent/blob/main/include/sra/research/IWebSearchClient.h): `include/sra/research/IWebSearchClient.h`

### Other components

- **API caller**
- **LLM service**

## Connections

- API caller → HTTP server: sends request
- HTTP server → Research controller: dispatches request
- Research controller → Research service: calls research
- Research controller → OpenAI provider: constructs provider
- Research service → Provider interface: dispatches research
- Research service → Research result: returns result
- Web research provider → Search interface: searches web
- Web search client → Evidence records: returns evidence
- OpenAI provider → LLM service: requests extraction
- Application bootstrap → Web search client: constructs client
- Application bootstrap → OpenAI provider: constructs provider
- Application bootstrap → Web research provider: constructs pipeline
- Application bootstrap → Research service: constructs service
- Application bootstrap → Research service: calls research
- Application bootstrap → Research result: prints summary
- Web research provider → Research signals: produces signals
- Web research provider → Evidence records: uses evidence
- Research result → Company model: includes company
- Research result → Research signals: includes signals