# avvud/competitor-intelligence-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/avvud/competitor-intelligence-orchestrator
- Repository: https://github.com/avvud/competitor-intelligence-orchestrator

## Overview

Competitor Intelligence Orchestrator turns a company website into a confirmed company profile, discovers candidate competitors for human approval, collects competitor data, analyzes it, and presents comparisons and downloadable reports. The shared pipeline service coordinates this workflow for the web API and MCP server; the README also documents a Streamlit dashboard. The graph preserves the distinct profile, discovery, collection, analysis, and reporting stages. Several capabilities are documented but their implementation details were not sampled, so those links are shown only where the README or source index supports them.

Main entry points: [`src/pipeline/service.py`](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/pipeline/service.py) (Pipeline service), [`src/discovery/pipeline.py`](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/pipeline.py) (Competitor discovery), [`src/analysis/pipeline.py`](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/pipeline.py) (Analysis pipeline), [`src/core/llm_client.py`](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/llm_client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web API and SPA<br/>[app.py]"]
  node_webservices["Web services<br/>[services.py]"]
  node_streamlit["Streamlit dashboard<br/>[app.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_workflow["Workflow orchestration"]
  node_orchestrator["Pipeline service<br/>[service.py]"]
end

subgraph group_intelligence["Intelligence stages"]
  node_profile["Profile intake<br/>[url_ingest.py]"]
  node_profileinfer["Profile inference<br/>[infer_profile.py]"]
  node_geography["Geographic inference<br/>[geo.py]"]
  node_discovery["Competitor discovery<br/>[pipeline.py]"]
  node_querygen["Query generation<br/>[query_gen.py]"]
  node_sources["Discovery sources<br/>[sources.py]"]
  node_scoring["Candidate scoring<br/>[scorer.py]"]
  node_dedup["Candidate deduplication<br/>[dedup.py]"]
  node_collection["Connector runner<br/>[runner.py]"]
  node_connectorcontract["Connector contract<br/>[base.py]"]
  node_analysis["Analysis pipeline<br/>[pipeline.py]"]
  node_comparison["Comparison matrix<br/>[comparison.py]"]
  node_rollup["Tier rollup<br/>[rollup.py]"]
  node_reports["Report downloads<br/>[services.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_db[("Application database<br/>[db.py]")]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_schemas["Domain schemas<br/>[models.py]"]
end

node_user(("User"))
node_llmprovider["LLM providers"]

node_user -->|"uses"| node_web
node_user -->|"uses"| node_streamlit
node_user -.->|"connects"| node_mcp
node_web -->|"routes to"| node_webservices
node_webservices -->|"delegates to"| node_orchestrator
node_mcp -->|"uses"| node_orchestrator
node_orchestrator -->|"ingests website"| node_profile
node_orchestrator -->|"infers profile"| node_profileinfer
node_profileinfer -->|"infers location"| node_geography
node_orchestrator -->|"discovers candidates"| node_discovery
node_discovery -->|"builds queries"| node_querygen
node_discovery -->|"fetches candidates"| node_sources
node_discovery -->|"scores candidates"| node_scoring
node_discovery -->|"deduplicates"| node_dedup
node_orchestrator -->|"collects data"| node_collection
node_collection -->|"dispatches connectors"| node_connectorcontract
node_orchestrator -->|"analyzes data"| node_analysis
node_analysis -->|"builds comparisons"| node_comparison
node_analysis -.->|"rolls up results"| node_rollup
node_webservices -->|"builds downloads"| node_reports
node_profile -->|"stores snapshots"| node_db
node_orchestrator -->|"reads and writes"| node_db
node_llm -.->|"calls"| node_llmprovider
node_profileinfer -->|"extracts profile"| node_llm
node_analysis -->|"analyzes content"| node_llm
node_discovery -->|"uses schemas"| node_schemas
node_comparison -->|"validates output"| node_schemas
node_llm -.->|"caches results"| node_db

click node_web "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/app.py"
click node_webservices "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/services.py"
click node_streamlit "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/ui/app.py"
click node_mcp "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/mcp/server.py"
click node_orchestrator "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/pipeline/service.py"
click node_profile "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/url_ingest.py"
click node_profileinfer "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/infer_profile.py"
click node_geography "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/geo.py"
click node_discovery "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/pipeline.py"
click node_querygen "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/query_gen.py"
click node_sources "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/sources.py"
click node_scoring "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/scorer.py"
click node_dedup "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/dedup.py"
click node_collection "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/connectors/runner.py"
click node_connectorcontract "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/connectors/base.py"
click node_analysis "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/pipeline.py"
click node_comparison "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/comparison.py"
click node_rollup "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/rollup.py"
click node_reports "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/services.py"
click node_db "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/db.py"
click node_llm "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/llm_client.py"
click node_schemas "https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/models.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_web,node_webservices,node_streamlit,node_mcp,node_user toneBlue
class node_orchestrator toneAmber
class node_profile,node_profileinfer,node_geography,node_discovery,node_querygen,node_sources,node_scoring,node_dedup,node_collection,node_connectorcontract,node_analysis,node_comparison,node_rollup,node_reports toneMint
class node_db,node_llm,node_schemas toneRose
class node_llmprovider toneIndigo
```

## Components

### User interfaces

- [Web API and SPA](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/app.py): `src/web/app.py`
- [Web services](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/services.py): `src/web/services.py`
- [Streamlit dashboard](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/ui/app.py): `src/ui/app.py`
- [MCP server](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/mcp/server.py): `src/mcp/server.py`

### Workflow orchestration

- [Pipeline service](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/pipeline/service.py): `src/pipeline/service.py`

### Intelligence stages

- [Profile intake](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/url_ingest.py): `src/profile/url_ingest.py`
- [Profile inference](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/infer_profile.py): `src/profile/infer_profile.py`
- [Geographic inference](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/profile/geo.py): `src/profile/geo.py`
- [Competitor discovery](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/pipeline.py): `src/discovery/pipeline.py`
- [Query generation](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/query_gen.py): `src/discovery/query_gen.py`
- [Discovery sources](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/sources.py): `src/discovery/sources.py`
- [Candidate scoring](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/scorer.py): `src/discovery/scorer.py`
- [Candidate deduplication](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/discovery/dedup.py): `src/discovery/dedup.py`
- [Connector runner](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/connectors/runner.py): `src/connectors/runner.py`
- [Connector contract](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/connectors/base.py): `src/connectors/base.py`
- [Analysis pipeline](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/pipeline.py): `src/analysis/pipeline.py`
- [Comparison matrix](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/comparison.py): `src/analysis/comparison.py`
- [Tier rollup](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/analysis/rollup.py): `src/analysis/rollup.py`
- [Report downloads](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/web/services.py): `src/web/services.py`

### Shared foundations

- [Application database](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/db.py): `src/core/db.py`
- [LLM client](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/llm_client.py): `src/core/llm_client.py`
- [Domain schemas](https://github.com/avvud/competitor-intelligence-orchestrator/blob/main/src/core/models.py): `src/core/models.py`

### Other components

- **User**
- **LLM providers**

## Connections

- User → Web API and SPA: uses (evidence: `README.md`)
- User → Streamlit dashboard: uses (evidence: `README.md`)
- User → MCP server: connects (evidence: `README.md`)
- Web API and SPA → Web services: routes to (evidence: `src/web/app.py`)
- Web services → Pipeline service: delegates to (evidence: `src/web/services.py`)
- MCP server → Pipeline service: uses (evidence: `src/mcp/server.py`)
- Pipeline service → Profile intake: ingests website (evidence: `src/pipeline/service.py`)
- Pipeline service → Profile inference: infers profile (evidence: `src/pipeline/service.py`)
- Profile inference → Geographic inference: infers location (evidence: `src/profile/infer_profile.py`)
- Pipeline service → Competitor discovery: discovers candidates (evidence: `src/pipeline/service.py`)
- Competitor discovery → Query generation: builds queries (evidence: `src/discovery/pipeline.py`)
- Competitor discovery → Discovery sources: fetches candidates (evidence: `src/discovery/pipeline.py`)
- Competitor discovery → Candidate scoring: scores candidates (evidence: `src/discovery/pipeline.py`)
- Competitor discovery → Candidate deduplication: deduplicates (evidence: `src/discovery/pipeline.py`)
- Pipeline service → Connector runner: collects data (evidence: `src/pipeline/service.py`)
- Connector runner → Connector contract: dispatches connectors (evidence: `src/connectors/runner.py`)
- Pipeline service → Analysis pipeline: analyzes data (evidence: `src/pipeline/service.py`)
- Analysis pipeline → Comparison matrix: builds comparisons (evidence: `src/pipeline/service.py`)
- Analysis pipeline → Tier rollup: rolls up results
- Web services → Report downloads: builds downloads (evidence: `src/web/services.py`)
- Profile intake → Application database: stores snapshots (evidence: `src/profile/url_ingest.py`)
- Pipeline service → Application database: reads and writes (evidence: `src/pipeline/service.py`)
- LLM client → LLM providers: calls
- Profile inference → LLM client: extracts profile (evidence: `src/profile/infer_profile.py`)
- Analysis pipeline → LLM client: analyzes content (evidence: `src/analysis/pipeline.py`)
- Competitor discovery → Domain schemas: uses schemas (evidence: `src/discovery/pipeline.py`)
- Comparison matrix → Domain schemas: validates output (evidence: `src/analysis/comparison.py`)
- LLM client → Application database: caches results
