# amay-xd/breachalpha architecture

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

- Interactive diagram: https://gitdiagram.com/amay-xd/breachalpha
- Repository: https://github.com/amay-xd/breachalpha

## Overview

BreachAlpha is a cyber-risk intelligence product that turns a company or breach search into a market-impact report. The main workflow runs from the dashboard through the REST client to Flask, which looks up breach data, obtains company and benchmark prices, calculates correlation and recovery metrics, and returns AI commentary and an executive risk score. Separate branches support historical and sector analysis and PDF reporting. The README documents the wider API and dashboard capabilities; some backend routes and PDF wiring were not shown in the excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`backend/app.py`](https://github.com/amay-xd/breachalpha/blob/main/backend/app.py) (Flask API), [`frontend/src/App.tsx`](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/App.tsx) (Search Dashboard), [`frontend/src/api.ts`](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/api.ts) (REST Client), [`collectors/stock_collector.py`](https://github.com/amay-xd/breachalpha/blob/main/collectors/stock_collector.py) (Price Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Search Dashboard<br/>[App.tsx]"]
  node_ui["Dashboard Layout<br/>[ui.tsx]"]
  node_charts["Pattern Charts<br/>[charts.tsx]"]
  node_api_client["REST Client<br/>[api.ts]"]
end

subgraph group_backend["Analysis API"]
  node_flask["Flask API<br/>[app.py]"]
end

subgraph group_data["Breach Data"]
  node_breach_lookup["Breach Search<br/>[breach_lookup.py]"]
  node_breach_store[("Breach Dataset<br/>[breaches.json]")]
end

subgraph group_market["Market Analysis"]
  node_stock_collector["Price Collector<br/>[stock_collector.py]"]
  node_alpha_vantage["Alpha Vantage"]
  node_synthetic_data["Synthetic Prices<br/>[stock_collector.py]"]
  node_sp500["S&amp;P 500 Prices"]
  node_correlations["Correlation Metrics<br/>[correlations.py]"]
end

subgraph group_intelligence["Intelligence Output"]
  node_mistral_analysis["AI Analysis"]
  node_mistral["Mistral AI"]
  node_risk_score["Executive Risk Score<br/>[app.py]"]
  node_pdf_report["PDF Reports<br/>[pdf.py]"]
  node_market_report["Market Report<br/>[app.py]"]
end

node_user(("Researcher"))

node_user -->|"searches"| node_dashboard
node_dashboard -->|"requests analysis"| node_api_client
node_dashboard -->|"renders layout"| node_ui
node_dashboard -->|"renders patterns"| node_charts
node_ui -->|"checks health"| node_api_client
node_api_client -->|"calls REST API"| node_flask
node_flask -->|"finds breach"| node_breach_lookup
node_breach_lookup -->|"loads records"| node_breach_store
node_flask -->|"gets prices"| node_stock_collector
node_stock_collector -->|"fetches prices"| node_alpha_vantage
node_stock_collector -->|"falls back"| node_synthetic_data
node_flask -.->|"compares benchmark"| node_sp500
node_flask -->|"calculates metrics"| node_correlations
node_flask -->|"requests analysis"| node_mistral_analysis
node_mistral_analysis -->|"generates commentary"| node_mistral
node_flask -->|"scores risk"| node_risk_score
node_flask -->|"returns analysis"| node_market_report
node_flask -.->|"exports report"| node_pdf_report
node_api_client -.->|"provides patterns"| node_charts

click node_dashboard "https://github.com/amay-xd/breachalpha/blob/main/frontend/src/App.tsx"
click node_ui "https://github.com/amay-xd/breachalpha/blob/main/frontend/src/ui.tsx"
click node_charts "https://github.com/amay-xd/breachalpha/blob/main/frontend/src/charts.tsx"
click node_api_client "https://github.com/amay-xd/breachalpha/blob/main/frontend/src/api.ts"
click node_flask "https://github.com/amay-xd/breachalpha/blob/main/backend/app.py"
click node_breach_lookup "https://github.com/amay-xd/breachalpha/blob/main/data/breach_lookup.py"
click node_breach_store "https://github.com/amay-xd/breachalpha/blob/main/data/breaches.json"
click node_stock_collector "https://github.com/amay-xd/breachalpha/blob/main/collectors/stock_collector.py"
click node_synthetic_data "https://github.com/amay-xd/breachalpha/blob/main/collectors/stock_collector.py"
click node_correlations "https://github.com/amay-xd/breachalpha/blob/main/collectors/correlations.py"
click node_mistral_analysis "https://github.com/amay-xd/breachalpha/blob/main/ai_engine/mistral_analysis.py"
click node_risk_score "https://github.com/amay-xd/breachalpha/blob/main/backend/app.py"
click node_pdf_report "https://github.com/amay-xd/breachalpha/blob/main/output/pdf.py"
click node_market_report "https://github.com/amay-xd/breachalpha/blob/main/backend/app.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_dashboard,node_ui,node_charts,node_api_client toneBlue
class node_flask toneAmber
class node_breach_lookup,node_breach_store toneMint
class node_stock_collector,node_alpha_vantage,node_synthetic_data,node_sp500,node_correlations toneRose
class node_mistral_analysis,node_mistral,node_risk_score,node_pdf_report,node_market_report,node_user toneIndigo
```

## Components

### Dashboard

- [Search Dashboard](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard Layout](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/ui.tsx): `frontend/src/ui.tsx`
- [Pattern Charts](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/charts.tsx): `frontend/src/charts.tsx`
- [REST Client](https://github.com/amay-xd/breachalpha/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Analysis API

- [Flask API](https://github.com/amay-xd/breachalpha/blob/main/backend/app.py): `backend/app.py`

### Breach Data

- [Breach Search](https://github.com/amay-xd/breachalpha/blob/main/data/breach_lookup.py): `data/breach_lookup.py`
- [Breach Dataset](https://github.com/amay-xd/breachalpha/blob/main/data/breaches.json): `data/breaches.json`

### Market Analysis

- [Price Collector](https://github.com/amay-xd/breachalpha/blob/main/collectors/stock_collector.py): `collectors/stock_collector.py`
- **Alpha Vantage**
- [Synthetic Prices](https://github.com/amay-xd/breachalpha/blob/main/collectors/stock_collector.py): `collectors/stock_collector.py`
- **S&P 500 Prices**
- [Correlation Metrics](https://github.com/amay-xd/breachalpha/blob/main/collectors/correlations.py): `collectors/correlations.py`

### Intelligence Output

- [AI Analysis](https://github.com/amay-xd/breachalpha/blob/main/ai_engine/mistral_analysis.py): `ai_engine/mistral_analysis.py`
- **Mistral AI**
- [Executive Risk Score](https://github.com/amay-xd/breachalpha/blob/main/backend/app.py): `backend/app.py`
- [PDF Reports](https://github.com/amay-xd/breachalpha/blob/main/output/pdf.py): `output/pdf.py`
- [Market Report](https://github.com/amay-xd/breachalpha/blob/main/backend/app.py): `backend/app.py`

### Other components

- **Researcher**

## Connections

- Researcher → Search Dashboard: searches
- Search Dashboard → REST Client: requests analysis (evidence: `frontend/src/App.tsx`)
- Search Dashboard → Dashboard Layout: renders layout (evidence: `frontend/src/App.tsx`)
- Search Dashboard → Pattern Charts: renders patterns (evidence: `frontend/src/App.tsx`)
- Dashboard Layout → REST Client: checks health (evidence: `frontend/src/ui.tsx`)
- REST Client → Flask API: calls REST API (evidence: `README.md`)
- Flask API → Breach Search: finds breach (evidence: `backend/app.py`)
- Breach Search → Breach Dataset: loads records (evidence: `data/breach_lookup.py`)
- Flask API → Price Collector: gets prices (evidence: `backend/app.py`)
- Price Collector → Alpha Vantage: fetches prices (evidence: `collectors/stock_collector.py`)
- Price Collector → Synthetic Prices: falls back (evidence: `collectors/stock_collector.py`)
- Flask API → S&P 500 Prices: compares benchmark (evidence: `README.md`)
- Flask API → Correlation Metrics: calculates metrics (evidence: `backend/app.py`)
- Flask API → AI Analysis: requests analysis (evidence: `backend/app.py`)
- AI Analysis → Mistral AI: generates commentary (evidence: `ai_engine/mistral_analysis.py`)
- Flask API → Executive Risk Score: scores risk (evidence: `backend/app.py`)
- Flask API → Market Report: returns analysis (evidence: `README.md`)
- Flask API → PDF Reports: exports report (evidence: `backend/app.py`)
- REST Client → Pattern Charts: provides patterns (evidence: `frontend/src/charts.tsx`)
