# arunima072004/signalwatch architecture

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

- Interactive diagram: https://gitdiagram.com/arunima072004/signalwatch
- Repository: https://github.com/arunima072004/signalwatch

## Overview

SignalWatch is a market-intelligence pipeline: it turns historical retail prices into detected change events, then investigates each event with targeted searches and produces an evidence-backed assessment. The graph follows those two documented phases and includes the internal search, evidence, and verification layers. Relationships in the detection phase are documented at the README level; the investigation links also draw on the supplied source index. Unsampled modules are represented only where the README describes their role.

Main entry points: [`src/investigation/orchestrator.py`](https://github.com/arunima072004/signalwatch/blob/main/src/investigation/orchestrator.py) (Investigation coordinator), [`src/search/provider_interface.py`](https://github.com/arunima072004/signalwatch/blob/main/src/search/provider_interface.py) (Search provider interface), [`src/events/event_generator.py`](https://github.com/arunima072004/signalwatch/blob/main/src/events/event_generator.py) (Change events), [`src/timeseries/builder.py`](https://github.com/arunima072004/signalwatch/blob/main/src/timeseries/builder.py) (Time-series builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Price detection"]
  node_data_prep["Data preparation<br/>[preprocessing.py]"]
  node_timeseries["Time-series builder<br/>[builder.py]"]
  node_price_features["Price features<br/>[price_features.py]"]
  node_competitive_features["Competitive features"]
  node_bocpd["BOCPD detector<br/>[detector.py]"]
  node_bocpd_config["Detector configuration<br/>[config.py]"]
  node_events["Change events<br/>[event_generator.py]"]
  node_weak_labels["Heuristic labels<br/>[label_generator.py]"]
end

subgraph group_investigation["Event investigation"]
  node_orchestrator["Investigation coordinator<br/>[orchestrator.py]"]
  node_hypotheses["Hypothesis generation"]
  node_hypothesis_model["Hypothesis model<br/>[hypothesis.py]"]
  node_strategies["Investigation strategies"]
  node_search_interface["Search provider interface"]
  node_tavily["Tavily search<br/>[tavily_provider.py]"]
  node_mock_search["Mock search<br/>[mock_provider.py]"]
  node_cached_search["Cached search<br/>[cached_provider.py]"]
  node_search_models["Query and result models<br/>[search.py]"]
end

subgraph group_evidence["Evidence verification"]
  node_extractor["Evidence extraction<br/>[extractor.py]"]
  node_parser["Page parser<br/>[parser.py]"]
  node_evidence_model["Evidence model<br/>[evidence.py]"]
  node_verification["Evidence verification"]
  node_verification_model["Verification model<br/>[verification.py]"]
end

subgraph group_results["Assessment output"]
  node_assessment["Event assessment<br/>[assessment.py]"]
  node_report["Markdown report<br/>[generate_report.py]"]
end

node_pricing_csv["Pricing CSV"]
node_event["Change event"]
node_assessment_output["Assessment JSON and report"]

node_pricing_csv -->|"preprocesses"| node_data_prep
node_data_prep -->|"builds series"| node_timeseries
node_timeseries -->|"engineers features"| node_price_features
node_timeseries -->|"engineers features"| node_competitive_features
node_price_features -->|"provides signals"| node_bocpd
node_competitive_features -->|"enriches events"| node_events
node_bocpd_config -->|"configures"| node_bocpd
node_bocpd -->|"flags change points"| node_events
node_events -->|"labels events"| node_weak_labels
node_events -->|"produces"| node_event
node_event -->|"investigates"| node_orchestrator
node_orchestrator -->|"generates hypotheses"| node_hypotheses
node_hypotheses -->|"creates"| node_hypothesis_model
node_orchestrator -->|"runs investigation"| node_strategies
node_strategies -->|"executes queries"| node_search_interface
node_tavily -->|"implements"| node_search_interface
node_mock_search -->|"implements"| node_search_interface
node_cached_search -->|"wraps provider"| node_search_interface
node_search_interface -->|"uses query models"| node_search_models
node_strategies -->|"extracts evidence"| node_extractor
node_extractor -->|"parses pages"| node_parser
node_extractor -->|"creates evidence"| node_evidence_model
node_orchestrator -->|"verifies evidence"| node_verification
node_verification -->|"builds verification"| node_verification_model
node_orchestrator -->|"assembles assessment"| node_assessment
node_assessment -->|"renders report"| node_report
node_report -->|"writes report"| node_assessment_output

click node_data_prep "https://github.com/arunima072004/signalwatch/blob/main/src/data/preprocessing.py"
click node_timeseries "https://github.com/arunima072004/signalwatch/blob/main/src/timeseries/builder.py"
click node_price_features "https://github.com/arunima072004/signalwatch/blob/main/src/features/price_features.py"
click node_competitive_features "https://github.com/arunima072004/signalwatch/blob/main/src/features/competitive_features.py"
click node_bocpd "https://github.com/arunima072004/signalwatch/blob/main/src/bocpd/detector.py"
click node_bocpd_config "https://github.com/arunima072004/signalwatch/blob/main/src/bocpd/config.py"
click node_events "https://github.com/arunima072004/signalwatch/blob/main/src/events/event_generator.py"
click node_weak_labels "https://github.com/arunima072004/signalwatch/blob/main/src/weak_supervision/label_generator.py"
click node_orchestrator "https://github.com/arunima072004/signalwatch/blob/main/src/investigation/orchestrator.py"
click node_hypotheses "https://github.com/arunima072004/signalwatch/blob/main/src/investigation/hypothesis_generator.py"
click node_hypothesis_model "https://github.com/arunima072004/signalwatch/blob/main/src/models/hypothesis.py"
click node_strategies "https://github.com/arunima072004/signalwatch/blob/main/src/investigation/investigation_agent.py"
click node_search_interface "https://github.com/arunima072004/signalwatch/blob/main/src/search/provider_interface.py"
click node_tavily "https://github.com/arunima072004/signalwatch/blob/main/src/search/tavily_provider.py"
click node_mock_search "https://github.com/arunima072004/signalwatch/blob/main/src/search/mock_provider.py"
click node_cached_search "https://github.com/arunima072004/signalwatch/blob/main/src/search/cached_provider.py"
click node_search_models "https://github.com/arunima072004/signalwatch/blob/main/src/models/search.py"
click node_extractor "https://github.com/arunima072004/signalwatch/blob/main/src/evidence/extractor.py"
click node_parser "https://github.com/arunima072004/signalwatch/blob/main/src/evidence/parser.py"
click node_evidence_model "https://github.com/arunima072004/signalwatch/blob/main/src/models/evidence.py"
click node_verification "https://github.com/arunima072004/signalwatch/blob/main/src/investigation/verification_agent.py"
click node_verification_model "https://github.com/arunima072004/signalwatch/blob/main/src/models/verification.py"
click node_assessment "https://github.com/arunima072004/signalwatch/blob/main/src/models/assessment.py"
click node_report "https://github.com/arunima072004/signalwatch/blob/main/scripts/generate_report.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_data_prep,node_timeseries,node_price_features,node_competitive_features,node_bocpd,node_bocpd_config,node_events,node_weak_labels toneBlue
class node_orchestrator,node_hypotheses,node_hypothesis_model,node_strategies,node_search_interface,node_tavily,node_mock_search,node_cached_search,node_search_models toneAmber
class node_extractor,node_parser,node_evidence_model,node_verification,node_verification_model toneMint
class node_assessment,node_report toneRose
class node_pricing_csv,node_event,node_assessment_output toneIndigo
```

## Components

### Price detection

- [Data preparation](https://github.com/arunima072004/signalwatch/blob/main/src/data/preprocessing.py): `src/data/preprocessing.py`
- [Time-series builder](https://github.com/arunima072004/signalwatch/blob/main/src/timeseries/builder.py): `src/timeseries/builder.py`
- [Price features](https://github.com/arunima072004/signalwatch/blob/main/src/features/price_features.py): `src/features/price_features.py`
- [Competitive features](https://github.com/arunima072004/signalwatch/blob/main/src/features/competitive_features.py): `src/features/competitive_features.py`
- [BOCPD detector](https://github.com/arunima072004/signalwatch/blob/main/src/bocpd/detector.py): `src/bocpd/detector.py`
- [Detector configuration](https://github.com/arunima072004/signalwatch/blob/main/src/bocpd/config.py): `src/bocpd/config.py`
- [Change events](https://github.com/arunima072004/signalwatch/blob/main/src/events/event_generator.py): `src/events/event_generator.py`
- [Heuristic labels](https://github.com/arunima072004/signalwatch/blob/main/src/weak_supervision/label_generator.py): `src/weak_supervision/label_generator.py`

### Event investigation

- [Investigation coordinator](https://github.com/arunima072004/signalwatch/blob/main/src/investigation/orchestrator.py): `src/investigation/orchestrator.py`
- [Hypothesis generation](https://github.com/arunima072004/signalwatch/blob/main/src/investigation/hypothesis_generator.py): `src/investigation/hypothesis_generator.py`
- [Hypothesis model](https://github.com/arunima072004/signalwatch/blob/main/src/models/hypothesis.py): `src/models/hypothesis.py`
- [Investigation strategies](https://github.com/arunima072004/signalwatch/blob/main/src/investigation/investigation_agent.py): `src/investigation/investigation_agent.py`
- [Search provider interface](https://github.com/arunima072004/signalwatch/blob/main/src/search/provider_interface.py): `src/search/provider_interface.py`
- [Tavily search](https://github.com/arunima072004/signalwatch/blob/main/src/search/tavily_provider.py): `src/search/tavily_provider.py`
- [Mock search](https://github.com/arunima072004/signalwatch/blob/main/src/search/mock_provider.py): `src/search/mock_provider.py`
- [Cached search](https://github.com/arunima072004/signalwatch/blob/main/src/search/cached_provider.py): `src/search/cached_provider.py`
- [Query and result models](https://github.com/arunima072004/signalwatch/blob/main/src/models/search.py): `src/models/search.py`

### Evidence verification

- [Evidence extraction](https://github.com/arunima072004/signalwatch/blob/main/src/evidence/extractor.py): `src/evidence/extractor.py`
- [Page parser](https://github.com/arunima072004/signalwatch/blob/main/src/evidence/parser.py): `src/evidence/parser.py`
- [Evidence model](https://github.com/arunima072004/signalwatch/blob/main/src/models/evidence.py): `src/models/evidence.py`
- [Evidence verification](https://github.com/arunima072004/signalwatch/blob/main/src/investigation/verification_agent.py): `src/investigation/verification_agent.py`
- [Verification model](https://github.com/arunima072004/signalwatch/blob/main/src/models/verification.py): `src/models/verification.py`

### Assessment output

- [Event assessment](https://github.com/arunima072004/signalwatch/blob/main/src/models/assessment.py): `src/models/assessment.py`
- [Markdown report](https://github.com/arunima072004/signalwatch/blob/main/scripts/generate_report.py): `scripts/generate_report.py`

### Other components

- **Pricing CSV**
- **Change event**
- **Assessment JSON and report**

## Connections

- Pricing CSV → Data preparation: preprocesses (evidence: `README.md`)
- Data preparation → Time-series builder: builds series (evidence: `README.md`)
- Time-series builder → Price features: engineers features (evidence: `README.md`)
- Time-series builder → Competitive features: engineers features (evidence: `README.md`)
- Price features → BOCPD detector: provides signals (evidence: `README.md`)
- Competitive features → Change events: enriches events (evidence: `README.md`)
- Detector configuration → BOCPD detector: configures (evidence: `src/bocpd/detector.py`)
- BOCPD detector → Change events: flags change points (evidence: `README.md`)
- Change events → Heuristic labels: labels events (evidence: `README.md`)
- Change events → Change event: produces (evidence: `README.md`)
- Change event → Investigation coordinator: investigates (evidence: `src/investigation/orchestrator.py`)
- Investigation coordinator → Hypothesis generation: generates hypotheses (evidence: `src/investigation/orchestrator.py`)
- Hypothesis generation → Hypothesis model: creates (evidence: `src/investigation/hypothesis_generator.py`)
- Investigation coordinator → Investigation strategies: runs investigation (evidence: `src/investigation/orchestrator.py`)
- Investigation strategies → Search provider interface: executes queries (evidence: `src/investigation/investigation_agent.py`)
- Tavily search → Search provider interface: implements (evidence: `src/search/tavily_provider.py`)
- Mock search → Search provider interface: implements (evidence: `src/search/mock_provider.py`)
- Cached search → Search provider interface: wraps provider (evidence: `src/search/cached_provider.py`)
- Search provider interface → Query and result models: uses query models (evidence: `src/search/provider_interface.py`)
- Investigation strategies → Evidence extraction: extracts evidence (evidence: `src/investigation/investigation_agent.py`)
- Evidence extraction → Page parser: parses pages (evidence: `src/evidence/extractor.py`)
- Evidence extraction → Evidence model: creates evidence (evidence: `src/evidence/extractor.py`)
- Investigation coordinator → Evidence verification: verifies evidence (evidence: `src/investigation/orchestrator.py`)
- Evidence verification → Verification model: builds verification (evidence: `src/investigation/verification_agent.py`)
- Investigation coordinator → Event assessment: assembles assessment (evidence: `src/investigation/orchestrator.py`)
- Event assessment → Markdown report: renders report (evidence: `README.md`)
- Markdown report → Assessment JSON and report: writes report (evidence: `README.md`)
