# lilibethlangat/opportunity_scout_ai architecture

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

- Interactive diagram: https://gitdiagram.com/lilibethlangat/opportunity_scout_ai
- Repository: https://github.com/lilibethlangat/opportunity_scout_ai

## Overview

Opportunity Scout AI is a startup opportunity decision-support app: users submit a venture profile in the dashboard, the API asks the prediction pipeline to gather market context and score it, then returns explanations and comparisons. The runtime combines aggregation, feature engineering, a gradient-boosting model, and SHAP-based explanations; the UI also supports what-if analysis and portfolio views. The README documents additional live signals and dashboard capabilities, but sampled excerpts do not establish every collector or persistence connection, so uncertain wiring is omitted.

Main entry points: [`pipeline.py`](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/pipeline.py) (Signal aggregation), [`main.py`](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/main.py) (FastAPI application), [`predictor.py`](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/predictor.py) (Opportunity predictor), [`Frontend/script.js`](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Frontend/script.js) (Interactive dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard"]
  node_dashboard["Interactive dashboard<br/>[script.js]"]
  node_web_assets["Dashboard assets<br/>[index.html]"]
end

subgraph group_api["Application API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_industry_reference["Industry / country reference<br/>[startup_core.csv]"]
  node_portfolio_scores["Scored venture data"]
end

subgraph group_scoring["Scoring pipeline"]
  node_predictor["Opportunity predictor<br/>[predictor.py]"]
  node_aggregation["Signal aggregation<br/>[pipeline.py]"]
  node_feature_engineer["Feature engineering"]
  node_model["LightGBM model"]
  node_explanation["SHAP explanations<br/>[predictor.py]"]
end

subgraph group_signals["Market data"]
  node_venture_data["Historical venture data<br/>[ventures.csv]"]
  node_trend_data["Trend history"]
  node_macro_data["Macro indicators<br/>[macro_data.csv]"]
  node_news_data["News signals<br/>[GDELT.csv]"]
  node_social_data["Reddit signals<br/>[reddit.csv]"]
end

node_founder(("Investor / founder"))
node_trends_service["Google Trends"]
node_reddit_service["Reddit data service"]
node_gdelt_service["GDELT / BigQuery"]
node_gdp_service["World Bank / GDP context"]
node_portfolio_user(("Portfolio reviewer"))

node_founder -->|"enters venture"| node_dashboard
node_dashboard -->|"requests evaluation"| node_api_app
node_api_app -->|"predicts / compares"| node_predictor
node_api_app -->|"reads options"| node_industry_reference
node_api_app -->|"reads scores"| node_portfolio_scores
node_predictor -->|"collects signals"| node_aggregation
node_aggregation -->|"looks up ventures"| node_venture_data
node_aggregation -->|"reads trends"| node_trend_data
node_aggregation -->|"reads macro data"| node_macro_data
node_aggregation -->|"reads news signals"| node_news_data
node_aggregation -->|"reads social signals"| node_social_data
node_aggregation -.->|"fetches trends"| node_trends_service
node_aggregation -.->|"fetches mentions"| node_reddit_service
node_aggregation -.->|"queries news data"| node_gdelt_service
node_aggregation -.->|"gets GDP context"| node_gdp_service
node_predictor -->|"transforms features"| node_feature_engineer
node_feature_engineer -->|"prepares model input"| node_model
node_predictor -->|"scores features"| node_model
node_predictor -->|"explains prediction"| node_explanation
node_predictor -->|"returns result"| node_api_app
node_api_app -->|"serves results"| node_dashboard
node_portfolio_user -->|"reviews portfolio"| node_dashboard
node_dashboard -->|"requests what-if / compare"| node_api_app
node_api_app -->|"returns portfolio view"| node_portfolio_scores
node_api_app -->|"serves interface"| node_web_assets

click node_dashboard "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Frontend/script.js"
click node_web_assets "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Frontend/index.html"
click node_api_app "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/main.py"
click node_industry_reference "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/startup_core.csv"
click node_portfolio_scores "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data_pipeline/historical_scored.csv"
click node_predictor "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/predictor.py"
click node_aggregation "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/pipeline.py"
click node_feature_engineer "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/feature_engineer.py"
click node_model "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Models/ventures_lightgbm.joblib"
click node_explanation "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/predictor.py"
click node_venture_data "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/ventures.csv"
click node_trend_data "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/industry_trends.csv"
click node_macro_data "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/macro_data.csv"
click node_news_data "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/GDELT.csv"
click node_social_data "https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/reddit.csv"

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_web_assets,node_portfolio_user toneBlue
class node_api_app,node_industry_reference,node_portfolio_scores toneAmber
class node_predictor,node_aggregation,node_feature_engineer,node_model,node_explanation toneMint
class node_venture_data,node_trend_data,node_macro_data,node_news_data,node_social_data toneRose
class node_founder,node_trends_service,node_reddit_service,node_gdelt_service,node_gdp_service toneIndigo
```

## Components

### Dashboard

- [Interactive dashboard](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Frontend/script.js): `Frontend/script.js`
- [Dashboard assets](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Frontend/index.html): `Frontend/index.html`

### Application API

- [FastAPI application](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/main.py): `main.py`
- [Industry / country reference](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/startup_core.csv): `Data/startup_core.csv`
- [Scored venture data](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data_pipeline/historical_scored.csv): `Data_pipeline/historical_scored.csv`

### Scoring pipeline

- [Opportunity predictor](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/predictor.py): `predictor.py`
- [Signal aggregation](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/pipeline.py): `pipeline.py`
- [Feature engineering](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/feature_engineer.py): `feature_engineer.py`
- [LightGBM model](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Models/ventures_lightgbm.joblib): `Models/ventures_lightgbm.joblib`
- [SHAP explanations](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/predictor.py): `predictor.py`

### Market data

- [Historical venture data](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/ventures.csv): `Data/ventures.csv`
- [Trend history](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/industry_trends.csv): `Data/industry_trends.csv`
- [Macro indicators](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/macro_data.csv): `Data/macro_data.csv`
- [News signals](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/GDELT.csv): `Data/GDELT.csv`
- [Reddit signals](https://github.com/lilibethlangat/opportunity_scout_ai/blob/main/Data/reddit.csv): `Data/reddit.csv`

### Other components

- **Investor / founder**
- **Google Trends**
- **Reddit data service**
- **GDELT / BigQuery**
- **World Bank / GDP context**
- **Portfolio reviewer**

## Connections

- Investor / founder → Interactive dashboard: enters venture
- Interactive dashboard → FastAPI application: requests evaluation
- FastAPI application → Opportunity predictor: predicts / compares
- FastAPI application → Industry / country reference: reads options
- FastAPI application → Scored venture data: reads scores
- Opportunity predictor → Signal aggregation: collects signals
- Signal aggregation → Historical venture data: looks up ventures
- Signal aggregation → Trend history: reads trends
- Signal aggregation → Macro indicators: reads macro data
- Signal aggregation → News signals: reads news signals
- Signal aggregation → Reddit signals: reads social signals
- Signal aggregation → Google Trends: fetches trends
- Signal aggregation → Reddit data service: fetches mentions
- Signal aggregation → GDELT / BigQuery: queries news data
- Signal aggregation → World Bank / GDP context: gets GDP context
- Opportunity predictor → Feature engineering: transforms features
- Feature engineering → LightGBM model: prepares model input
- Opportunity predictor → LightGBM model: scores features
- Opportunity predictor → SHAP explanations: explains prediction
- Opportunity predictor → FastAPI application: returns result
- FastAPI application → Interactive dashboard: serves results
- Portfolio reviewer → Interactive dashboard: reviews portfolio
- Interactive dashboard → FastAPI application: requests what-if / compare
- FastAPI application → Scored venture data: returns portfolio view
- FastAPI application → Dashboard assets: serves interface