# salmanmalvasi/sectorlens architecture

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

- Interactive diagram: https://gitdiagram.com/salmanmalvasi/sectorlens
- Repository: https://github.com/salmanmalvasi/sectorlens

## Overview

SectorLens compares 2–5 public companies using SEC filings and earnings transcripts, then returns citation-grounded analysis. The main flow runs from ticker selection through resolution, document retrieval, fact extraction, sector-aware comparison, and claim verification to the React results views. The README documents both data providers, caching, sector contexts, and the search, sector, and health API capabilities. Several source files were not sampled, so their internal calls are represented only where the README or sampled orchestrator establishes them.

Main entry points: [`backend/pipeline.py`](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/pipeline.py) (Pipeline orchestrator), [`backend/main.py`](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/main.py) (HTTP API), [`frontend/src/App.jsx`](https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/App.jsx) (Results workflow), [`backend/data/ticker_resolver.py`](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/ticker_resolver.py) (Ticker resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_search_ui["Ticker search<br/>[TickerSearch.jsx]"]
  node_app["Results workflow<br/>[App.jsx]"]
  node_progress["Pipeline progress"]
  node_results_views["Results views"]
end

subgraph group_api["Backend API"]
  node_api_routes["HTTP API<br/>[main.py]"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.py]"]
end

subgraph group_research["Company research"]
  node_resolver["Ticker resolver<br/>[ticker_resolver.py]"]
  node_sector_context["Sector context<br/>[sector_context.py]"]
  node_edgar["SEC filing fetcher<br/>[edgar_fetcher.py]"]
  node_finnhub["Transcript fetcher<br/>[finnhub_fetcher.py]"]
  node_fact_cache[("Extracted facts cache<br/>[extractor.py]")]
end

subgraph group_analysis["Analysis agents"]
  node_extractor["Fact extractor<br/>[extractor.py]"]
  node_comparator["Company comparator<br/>[comparator.py]"]
  node_verifier["Claim verifier<br/>[verifier.py]"]
end

node_user(("Analyst"))
node_gemini{{"Gemini service"}}
node_sec{{"SEC EDGAR"}}
node_finnhub_service{{"Finnhub service"}}

node_user -->|"searches tickers"| node_search_ui
node_search_ui -->|"requests matches"| node_api_routes
node_api_routes -->|"searches SEC index"| node_resolver
node_resolver -->|"fetches company data"| node_sec
node_api_routes -->|"returns matches"| node_app
node_user -->|"submits companies"| node_app
node_app -->|"posts comparison"| node_api_routes
node_api_routes -->|"validates tickers"| node_resolver
node_api_routes -->|"runs pipeline"| node_pipeline
node_pipeline -->|"resolves companies"| node_resolver
node_pipeline -->|"reads metadata"| node_resolver
node_pipeline -->|"detects sector"| node_sector_context
node_pipeline -->|"fetches filings"| node_edgar
node_edgar -->|"retrieves 10-K"| node_sec
node_pipeline -->|"fetches transcripts"| node_finnhub
node_finnhub -->|"retrieves transcripts"| node_finnhub_service
node_pipeline -->|"extracts company facts"| node_extractor
node_extractor -->|"reads and writes"| node_fact_cache
node_extractor -->|"extracts cited facts"| node_gemini
node_pipeline -->|"compares extracted facts"| node_comparator
node_comparator -->|"uses sector metrics"| node_sector_context
node_comparator -->|"generates narrative"| node_gemini
node_pipeline -->|"verifies narrative"| node_verifier
node_verifier -->|"checks claim support"| node_gemini
node_pipeline -->|"returns analysis"| node_app
node_app -->|"shows stage status"| node_progress
node_app -->|"renders results"| node_results_views
node_results_views -->|"shows verified outputs"| node_user

click node_search_ui "https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/components/TickerSearch.jsx"
click node_app "https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/App.jsx"
click node_progress "https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/components/LoadingPipeline.jsx"
click node_results_views "https://github.com/salmanmalvasi/sectorlens/tree/main/frontend/src/components"
click node_api_routes "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/main.py"
click node_pipeline "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/pipeline.py"
click node_resolver "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/ticker_resolver.py"
click node_sector_context "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/sector_context.py"
click node_edgar "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/edgar_fetcher.py"
click node_finnhub "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/finnhub_fetcher.py"
click node_fact_cache "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/extractor.py"
click node_extractor "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/extractor.py"
click node_comparator "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/comparator.py"
click node_verifier "https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/verifier.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_search_ui,node_app,node_progress,node_results_views toneBlue
class node_api_routes,node_pipeline toneAmber
class node_resolver,node_sector_context,node_edgar,node_finnhub,node_fact_cache toneMint
class node_extractor,node_comparator,node_verifier toneRose
class node_user,node_gemini,node_sec,node_finnhub_service toneIndigo
```

## Components

### Web client

- [Ticker search](https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/components/TickerSearch.jsx): `frontend/src/components/TickerSearch.jsx`
- [Results workflow](https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Pipeline progress](https://github.com/salmanmalvasi/sectorlens/blob/main/frontend/src/components/LoadingPipeline.jsx): `frontend/src/components/LoadingPipeline.jsx`
- [Results views](https://github.com/salmanmalvasi/sectorlens/tree/main/frontend/src/components): `frontend/src/components`

### Backend API

- [HTTP API](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/main.py): `backend/main.py`
- [Pipeline orchestrator](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/pipeline.py): `backend/pipeline.py`

### Company research

- [Ticker resolver](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/ticker_resolver.py): `backend/data/ticker_resolver.py`
- [Sector context](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/sector_context.py): `backend/sector_context.py`
- [SEC filing fetcher](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/edgar_fetcher.py): `backend/data/edgar_fetcher.py`
- [Transcript fetcher](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/data/finnhub_fetcher.py): `backend/data/finnhub_fetcher.py`
- [Extracted facts cache](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/extractor.py): `backend/agents/extractor.py`

### Analysis agents

- [Fact extractor](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/extractor.py): `backend/agents/extractor.py`
- [Company comparator](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/comparator.py): `backend/agents/comparator.py`
- [Claim verifier](https://github.com/salmanmalvasi/sectorlens/blob/main/backend/agents/verifier.py): `backend/agents/verifier.py`

### Other components

- **Analyst**
- **Gemini service**
- **SEC EDGAR**
- **Finnhub service**

## Connections

- Analyst → Ticker search: searches tickers
- Ticker search → HTTP API: requests matches
- HTTP API → Ticker resolver: searches SEC index
- Ticker resolver → SEC EDGAR: fetches company data
- HTTP API → Results workflow: returns matches
- Analyst → Results workflow: submits companies
- Results workflow → HTTP API: posts comparison
- HTTP API → Ticker resolver: validates tickers
- HTTP API → Pipeline orchestrator: runs pipeline
- Pipeline orchestrator → Ticker resolver: resolves companies
- Pipeline orchestrator → Ticker resolver: reads metadata
- Pipeline orchestrator → Sector context: detects sector
- Pipeline orchestrator → SEC filing fetcher: fetches filings
- SEC filing fetcher → SEC EDGAR: retrieves 10-K
- Pipeline orchestrator → Transcript fetcher: fetches transcripts
- Transcript fetcher → Finnhub service: retrieves transcripts
- Pipeline orchestrator → Fact extractor: extracts company facts
- Fact extractor → Extracted facts cache: reads and writes
- Fact extractor → Gemini service: extracts cited facts
- Pipeline orchestrator → Company comparator: compares extracted facts
- Company comparator → Sector context: uses sector metrics
- Company comparator → Gemini service: generates narrative
- Pipeline orchestrator → Claim verifier: verifies narrative
- Claim verifier → Gemini service: checks claim support
- Pipeline orchestrator → Results workflow: returns analysis
- Results workflow → Pipeline progress: shows stage status
- Results workflow → Results views: renders results
- Results views → Analyst: shows verified outputs