# nickr145/worldmarket-screener architecture

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

- Interactive diagram: https://gitdiagram.com/nickr145/worldmarket-screener
- Repository: https://github.com/nickr145/worldmarket-screener

## Overview

WorldMarket is a local market-attractiveness screener. Its main user workflow is to enter a company description, review and confirm the parsed profile, then view ranked country candidates with labels, estimates, intervals, and caveats. The repository also contains a data-refresh and model-evaluation pipeline, plus dashboard detail, explanation, and model-card pages. Some subsystem links below rely on README descriptions or the source index; unsampled modules are represented at their exact file paths without assuming unshown calls.

Main entry points: [`screener/features/run_panel.py`](https://github.com/nickr145/worldmarket-screener/blob/main/screener/features/run_panel.py) (Panel refresh orchestration), [`screener/app/app.py`](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/app.py) (Streamlit dashboard), [`screener/app/services.py`](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/services.py) (Dashboard services), [`screener/score/score_cells.py`](https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/score_cells.py) (Shipped cell scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_screen["Screen page<br/>[screen.py]"]
  node_detail["Market detail<br/>[detail.py]"]
  node_explainer["Label explainer<br/>[explainer.py]"]
  node_modelcard["Model card page<br/>[modelcard.py]"]
  node_cli["Command-line screener<br/>[cli.py]"]
end

subgraph group_profile["Profile and screening"]
  node_services["Dashboard services<br/>[services.py]"]
  node_parser["Description parser<br/>[parser.py]"]
  node_schema["Profile schema<br/>[schema.py]"]
  node_candidates["Candidate selection<br/>[candidates.py]"]
  node_labels["Labels and display rules<br/>[labels.py]"]
  node_narrator["Plain-language narrator<br/>[narrate.py]"]
end

subgraph group_data["Data preparation"]
  node_ingest["Market data ingestion"]
  node_clean["Financial data cleaning"]
  node_panel["Panel construction<br/>[build_panel.py]"]
  node_refresh["Panel refresh orchestration<br/>[run_panel.py]"]
end

subgraph group_models["Scoring and evaluation"]
  node_baselines["Growth baselines<br/>[baselines.py]"]
  node_boosted["Boosted models<br/>[boosted.py]"]
  node_risk["Risk models<br/>[risk_models.py]"]
  node_scorer["Shipped cell scoring<br/>[score_cells.py]"]
  node_evaluation["Verdict evaluation<br/>[verdict_v2_eval.py]"]
end

node_user(("Company screener user"))
node_anthropic{{"Anthropic API"}}

node_user -->|"opens"| node_dashboard
node_dashboard -->|"routes to"| node_screen
node_dashboard -->|"routes to"| node_detail
node_dashboard -->|"routes to"| node_explainer
node_dashboard -->|"routes to"| node_modelcard
node_user -->|"runs"| node_cli
node_screen -->|"parses description"| node_parser
node_parser -->|"validates profile"| node_schema
node_parser -->|"sends prompt"| node_anthropic
node_screen -.->|"requests scoring"| node_services
node_screen -->|"selects markets"| node_candidates
node_cli -->|"parses prompt"| node_parser
node_cli -->|"selects markets"| node_candidates
node_services -->|"loads panel logic"| node_refresh
node_services -->|"loads model helpers"| node_baselines
node_detail -->|"reads market data"| node_services
node_detail -.->|"requests narration"| node_narrator
node_detail -->|"formats labels"| node_labels
node_explainer -->|"uses definitions"| node_labels
node_explainer -->|"requests narration"| node_narrator
node_modelcard -->|"reads model data"| node_services
node_modelcard -->|"uses definitions"| node_labels
node_narrator -->|"generates text"| node_anthropic
node_refresh -.->|"loads source data"| node_ingest
node_refresh -->|"uses currency checks"| node_clean
node_clean -->|"supports panel building"| node_panel
node_refresh -->|"builds panel"| node_panel
node_baselines -->|"loads panel data"| node_refresh
node_risk -->|"reuses predictors"| node_baselines
node_risk -->|"uses model definitions"| node_boosted
node_scorer -->|"loads panel data"| node_refresh
node_scorer -->|"uses growth models"| node_baselines
node_scorer -->|"uses risk models"| node_risk
node_scorer -->|"applies display rules"| node_labels
node_evaluation -->|"evaluates verdict signals"| node_risk

click node_dashboard "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/app.py"
click node_screen "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/screen.py"
click node_detail "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/detail.py"
click node_explainer "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/explainer.py"
click node_modelcard "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/modelcard.py"
click node_cli "https://github.com/nickr145/worldmarket-screener/blob/main/screener/cli.py"
click node_services "https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/services.py"
click node_parser "https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/parser.py"
click node_schema "https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/schema.py"
click node_candidates "https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/candidates.py"
click node_labels "https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/labels.py"
click node_narrator "https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/narrate.py"
click node_ingest "https://github.com/nickr145/worldmarket-screener/tree/main/screener/ingest"
click node_clean "https://github.com/nickr145/worldmarket-screener/tree/main/screener/clean"
click node_panel "https://github.com/nickr145/worldmarket-screener/blob/main/screener/features/build_panel.py"
click node_refresh "https://github.com/nickr145/worldmarket-screener/blob/main/screener/features/run_panel.py"
click node_baselines "https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/baselines.py"
click node_boosted "https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/boosted.py"
click node_risk "https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/risk_models.py"
click node_scorer "https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/score_cells.py"
click node_evaluation "https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/verdict_v2_eval.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_screen,node_detail,node_explainer,node_modelcard,node_cli,node_user toneBlue
class node_services,node_parser,node_schema,node_candidates,node_labels,node_narrator toneAmber
class node_ingest,node_clean,node_panel,node_refresh,node_anthropic toneMint
class node_baselines,node_boosted,node_risk,node_scorer,node_evaluation toneRose
```

## Components

### User interfaces

- [Streamlit dashboard](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/app.py): `screener/app/app.py`
- [Screen page](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/screen.py): `screener/app/views/screen.py`
- [Market detail](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/detail.py): `screener/app/views/detail.py`
- [Label explainer](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/explainer.py): `screener/app/views/explainer.py`
- [Model card page](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/views/modelcard.py): `screener/app/views/modelcard.py`
- [Command-line screener](https://github.com/nickr145/worldmarket-screener/blob/main/screener/cli.py): `screener/cli.py`

### Profile and screening

- [Dashboard services](https://github.com/nickr145/worldmarket-screener/blob/main/screener/app/services.py): `screener/app/services.py`
- [Description parser](https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/parser.py): `screener/parse/parser.py`
- [Profile schema](https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/schema.py): `screener/parse/schema.py`
- [Candidate selection](https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/candidates.py): `screener/score/candidates.py`
- [Labels and display rules](https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/labels.py): `screener/score/labels.py`
- [Plain-language narrator](https://github.com/nickr145/worldmarket-screener/blob/main/screener/parse/narrate.py): `screener/parse/narrate.py`

### Data preparation

- [Market data ingestion](https://github.com/nickr145/worldmarket-screener/tree/main/screener/ingest): `screener/ingest`
- [Financial data cleaning](https://github.com/nickr145/worldmarket-screener/tree/main/screener/clean): `screener/clean`
- [Panel construction](https://github.com/nickr145/worldmarket-screener/blob/main/screener/features/build_panel.py): `screener/features/build_panel.py`
- [Panel refresh orchestration](https://github.com/nickr145/worldmarket-screener/blob/main/screener/features/run_panel.py): `screener/features/run_panel.py`

### Scoring and evaluation

- [Growth baselines](https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/baselines.py): `screener/model/baselines.py`
- [Boosted models](https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/boosted.py): `screener/model/boosted.py`
- [Risk models](https://github.com/nickr145/worldmarket-screener/blob/main/screener/model/risk_models.py): `screener/model/risk_models.py`
- [Shipped cell scoring](https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/score_cells.py): `screener/score/score_cells.py`
- [Verdict evaluation](https://github.com/nickr145/worldmarket-screener/blob/main/screener/score/verdict_v2_eval.py): `screener/score/verdict_v2_eval.py`

### Other components

- **Company screener user**
- **Anthropic API**

## Connections

- Company screener user → Streamlit dashboard: opens
- Streamlit dashboard → Screen page: routes to (evidence: `screener/app/app.py`)
- Streamlit dashboard → Market detail: routes to (evidence: `screener/app/app.py`)
- Streamlit dashboard → Label explainer: routes to (evidence: `screener/app/app.py`)
- Streamlit dashboard → Model card page: routes to (evidence: `screener/app/app.py`)
- Company screener user → Command-line screener: runs
- Screen page → Description parser: parses description (evidence: `screener/app/views/screen.py`)
- Description parser → Profile schema: validates profile (evidence: `screener/parse/parser.py`)
- Description parser → Anthropic API: sends prompt (evidence: `screener/parse/parser.py`)
- Screen page → Dashboard services: requests scoring (evidence: `screener/app/views/screen.py`)
- Screen page → Candidate selection: selects markets (evidence: `screener/app/views/screen.py`)
- Command-line screener → Description parser: parses prompt (evidence: `screener/cli.py`)
- Command-line screener → Candidate selection: selects markets (evidence: `screener/cli.py`)
- Dashboard services → Panel refresh orchestration: loads panel logic (evidence: `screener/app/services.py`)
- Dashboard services → Growth baselines: loads model helpers (evidence: `screener/app/services.py`)
- Market detail → Dashboard services: reads market data (evidence: `screener/app/views/detail.py`)
- Market detail → Plain-language narrator: requests narration (evidence: `screener/app/views/detail.py`)
- Market detail → Labels and display rules: formats labels (evidence: `screener/app/views/detail.py`)
- Label explainer → Labels and display rules: uses definitions (evidence: `screener/app/views/explainer.py`)
- Label explainer → Plain-language narrator: requests narration (evidence: `screener/app/views/explainer.py`)
- Model card page → Dashboard services: reads model data (evidence: `screener/app/views/modelcard.py`)
- Model card page → Labels and display rules: uses definitions (evidence: `screener/app/views/modelcard.py`)
- Plain-language narrator → Anthropic API: generates text (evidence: `screener/parse/narrate.py`)
- Panel refresh orchestration → Market data ingestion: loads source data (evidence: `screener/features/run_panel.py`)
- Panel refresh orchestration → Financial data cleaning: uses currency checks (evidence: `screener/features/run_panel.py`)
- Financial data cleaning → Panel construction: supports panel building (evidence: `screener/clean/currency_check.py`)
- Panel refresh orchestration → Panel construction: builds panel (evidence: `screener/features/run_panel.py`)
- Growth baselines → Panel refresh orchestration: loads panel data (evidence: `screener/model/baselines.py`)
- Risk models → Growth baselines: reuses predictors (evidence: `screener/model/risk_models.py`)
- Risk models → Boosted models: uses model definitions (evidence: `screener/model/risk_models.py`)
- Shipped cell scoring → Panel refresh orchestration: loads panel data (evidence: `screener/score/score_cells.py`)
- Shipped cell scoring → Growth baselines: uses growth models (evidence: `screener/score/score_cells.py`)
- Shipped cell scoring → Risk models: uses risk models (evidence: `screener/score/score_cells.py`)
- Shipped cell scoring → Labels and display rules: applies display rules (evidence: `screener/score/score_cells.py`)
- Verdict evaluation → Risk models: evaluates verdict signals (evidence: `screener/score/verdict_v2_eval.py`)
