# falahhilal/multi-agent-financial-advisor architecture

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

- Interactive diagram: https://gitdiagram.com/falahhilal/multi-agent-financial-advisor
- Repository: https://github.com/falahhilal/multi-agent-financial-advisor

## Overview

This repository’s sampled runtime is a financial-news collection and enrichment pipeline, not the broader advisor application suggested by the backend dependency list. News jobs archive RSS, publisher archives, and GDELT article indexes; a separate job fetches indexed article text, while another scores news with FinBERT. Shared parsing and collection helpers provide normalization, polite HTTP, and dataset persistence. The README is empty, so the map relies on source excerpts and the source index; connections to unsampled internals are omitted where not established.

Main entry points: [`backend/jobs/news_gdelt_text.py`](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_gdelt_text.py) (Article text), [`backend/jobs/common.py`](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/common.py) (Job helpers), [`backend/jobs/news_rss.py`](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_rss.py) (RSS archive), [`backend/jobs/news_aaj_psx.py`](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_aaj_psx.py) (Aaj archive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["News collection"]
  node_rss["RSS archive<br/>[news_rss.py]"]
  node_aaj["Aaj archive<br/>[news_aaj_psx.py]"]
  node_gdelt["GDELT index<br/>[news_gdelt.py]"]
  node_nation["Nation archive"]
end

subgraph group_enrichment["News enrichment"]
  node_article_text["Article text<br/>[news_gdelt_text.py]"]
  node_sentiment["FinBERT sentiment<br/>[news_finbert.py]"]
end

subgraph group_shared["Shared job services"]
  node_parser["News parser<br/>[news_common.py]"]
  node_job_helpers["Job helpers<br/>[common.py]"]
end

node_publishers(("News publishers"))
node_gdelt_service(("GDELT service"))
node_hf_dataset[("Hugging Face dataset")]
node_finbert_model{{"FinBERT model"}}

node_rss -->|"fetches feeds"| node_publishers
node_aaj -->|"fetches pages"| node_publishers
node_nation -->|"fetches archive"| node_publishers
node_gdelt -->|"queries index"| node_gdelt_service
node_article_text -->|"fetches articles"| node_publishers
node_article_text -.->|"reads index links"| node_gdelt
node_rss -->|"uses parsing"| node_parser
node_aaj -->|"parses articles"| node_parser
node_nation -->|"parses articles"| node_parser
node_rss -->|"uses job helpers"| node_job_helpers
node_aaj -->|"uses job helpers"| node_job_helpers
node_gdelt -->|"uses job helpers"| node_job_helpers
node_nation -->|"uses job helpers"| node_job_helpers
node_article_text -->|"uses job helpers"| node_job_helpers
node_sentiment -->|"uses job helpers"| node_job_helpers
node_article_text -->|"parses pages"| node_parser
node_rss -->|"uploads archive"| node_hf_dataset
node_aaj -->|"uploads archive"| node_hf_dataset
node_gdelt -->|"uploads index"| node_hf_dataset
node_nation -->|"uploads archive"| node_hf_dataset
node_article_text -->|"uploads text"| node_hf_dataset
node_sentiment -->|"reads and uploads"| node_hf_dataset
node_sentiment -->|"scores with"| node_finbert_model

click node_rss "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_rss.py"
click node_aaj "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_aaj_psx.py"
click node_gdelt "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_gdelt.py"
click node_nation "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_nation_archive.py"
click node_article_text "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_gdelt_text.py"
click node_sentiment "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_finbert.py"
click node_parser "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_common.py"
click node_job_helpers "https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/common.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_rss,node_aaj,node_gdelt,node_nation toneBlue
class node_article_text,node_sentiment,node_hf_dataset toneAmber
class node_parser,node_job_helpers toneMint
class node_publishers,node_gdelt_service,node_finbert_model toneIndigo
```

## Components

### News collection

- [RSS archive](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_rss.py): `backend/jobs/news_rss.py`
- [Aaj archive](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_aaj_psx.py): `backend/jobs/news_aaj_psx.py`
- [GDELT index](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_gdelt.py): `backend/jobs/news_gdelt.py`
- [Nation archive](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_nation_archive.py): `backend/jobs/news_nation_archive.py`

### News enrichment

- [Article text](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_gdelt_text.py): `backend/jobs/news_gdelt_text.py`
- [FinBERT sentiment](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_finbert.py): `backend/jobs/news_finbert.py`

### Shared job services

- [News parser](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/news_common.py): `backend/jobs/news_common.py`
- [Job helpers](https://github.com/falahhilal/multi-agent-financial-advisor/blob/main/backend/jobs/common.py): `backend/jobs/common.py`

### Other components

- **News publishers**
- **GDELT service**
- **Hugging Face dataset**
- **FinBERT model**

## Connections

- RSS archive → News publishers: fetches feeds (evidence: `backend/jobs/news_rss.py`)
- Aaj archive → News publishers: fetches pages (evidence: `backend/jobs/news_aaj_psx.py`)
- Nation archive → News publishers: fetches archive (evidence: `backend/jobs/news_nation_archive.py`)
- GDELT index → GDELT service: queries index (evidence: `backend/jobs/news_gdelt.py`)
- Article text → News publishers: fetches articles (evidence: `backend/jobs/news_gdelt_text.py`)
- Article text → GDELT index: reads index links (evidence: `backend/jobs/news_gdelt_text.py`)
- RSS archive → News parser: uses parsing (evidence: `backend/jobs/news_rss.py`)
- Aaj archive → News parser: parses articles (evidence: `backend/jobs/news_aaj_psx.py`)
- Nation archive → News parser: parses articles (evidence: `backend/jobs/news_nation_archive.py`)
- RSS archive → Job helpers: uses job helpers (evidence: `backend/jobs/news_rss.py`)
- Aaj archive → Job helpers: uses job helpers (evidence: `backend/jobs/news_aaj_psx.py`)
- GDELT index → Job helpers: uses job helpers (evidence: `backend/jobs/news_gdelt.py`)
- Nation archive → Job helpers: uses job helpers (evidence: `backend/jobs/news_nation_archive.py`)
- Article text → Job helpers: uses job helpers (evidence: `backend/jobs/news_gdelt_text.py`)
- FinBERT sentiment → Job helpers: uses job helpers (evidence: `backend/jobs/news_finbert.py`)
- Article text → News parser: parses pages (evidence: `backend/jobs/news_gdelt_text.py`)
- RSS archive → Hugging Face dataset: uploads archive (evidence: `backend/jobs/news_rss.py`)
- Aaj archive → Hugging Face dataset: uploads archive (evidence: `backend/jobs/news_aaj_psx.py`)
- GDELT index → Hugging Face dataset: uploads index (evidence: `backend/jobs/news_gdelt.py`)
- Nation archive → Hugging Face dataset: uploads archive (evidence: `backend/jobs/news_nation_archive.py`)
- Article text → Hugging Face dataset: uploads text (evidence: `backend/jobs/news_gdelt_text.py`)
- FinBERT sentiment → Hugging Face dataset: reads and uploads (evidence: `backend/jobs/news_finbert.py`)
- FinBERT sentiment → FinBERT model: scores with (evidence: `backend/jobs/news_finbert.py`)
