# waats0n/bytebrief architecture

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

- Interactive diagram: https://gitdiagram.com/waats0n/bytebrief
- Repository: https://github.com/waats0n/bytebrief

## Overview

ByteBrief collects news, deduplicates and enriches it, persists articles, and serves digests and account features through a Django API to a React interface. The main user workflow is browsing or searching for a digest; scheduled collection and AI-assisted processing supply the article corpus. The graph includes documented capabilities and sampled call relationships. Several frontend pages and backend subsystems are represented by their exact paths but were not sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`Frontend/src/App.js`](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/App.js) (App and routes), [`backend/src/bytebrief/agent/orchestrator.py`](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/orchestrator.py) (Agent orchestrator), [`Frontend/src/services/api.js`](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/services/api.js) (API client), [`backend/news_brief/tasks.py`](https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/tasks.py) (Background tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React experience"]
  node_app["App and routes<br/>[App.js]"]
  node_layout["Page layout<br/>[Layout.js]"]
  node_navigation["Navigation<br/>[Navigation.js]"]
  node_home_sections["Digest sections<br/>[FeaturedNews.js]"]
  node_article_image["Article imagery<br/>[ArticleImage.js]"]
  node_brand_seal["Brand seal<br/>[BrandSeal.js]"]
  node_search_page["Search results<br/>[SearchPage.js]"]
  node_article_page["Article digest"]
  node_account_page["Account settings<br/>[AccountSettings.js]"]
  node_login_page["Login<br/>[Login.js]"]
  node_faq_page["FAQ<br/>[FAQPage.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_auth_client["Authentication client<br/>[authService.js]"]
  node_icon_map["Icon map<br/>[iconMap.js]"]
end

subgraph group_api["Django application"]
  node_django_urls["API routing<br/>[urls.py]"]
  node_api_views["API views<br/>[views.py]"]
  node_scheduler["Scheduled collection<br/>[scheduler.py]"]
  node_tasks["Background tasks<br/>[tasks.py]"]
end

subgraph group_collection["News collection"]
  node_agent["Agent orchestrator<br/>[orchestrator.py]"]
  node_scrapers["News scrapers<br/>[factory.py]"]
  node_google_scraper["Keyword search scraper<br/>[google_search.py]"]
end

subgraph group_processing["Article processing"]
  node_processor["Categorize and summarize<br/>[processor.py]"]
  node_deduplicator["Article comparer<br/>[comparer.py]"]
  node_article_model["Scraped article model<br/>[models.py]"]
end

subgraph group_state["Product data"]
  node_db_models[("Users and news records<br/>[models.py]")]
end

node_reader(("Reader"))
node_external_sources(("News publishers"))
node_google_news(("Google News RSS"))
node_email(("Email service"))

node_reader -->|"browses"| node_app
node_app -->|"renders"| node_layout
node_layout -->|"renders"| node_navigation
node_app -->|"renders"| node_home_sections
node_home_sections -->|"renders"| node_article_image
node_navigation -->|"renders"| node_brand_seal
node_app -->|"requests digest"| node_api_client
node_search_page -->|"requests results"| node_api_client
node_search_page -->|"renders results"| node_home_sections
node_app -->|"routes to"| node_article_page
node_app -->|"routes to"| node_account_page
node_app -->|"routes to"| node_login_page
node_app -->|"routes to"| node_faq_page
node_account_page -->|"uses"| node_api_client
node_account_page -->|"uses"| node_auth_client
node_login_page -.->|"authenticates via"| node_auth_client
node_auth_client -->|"uses base URL"| node_api_client
node_api_client -.->|"HTTP requests"| node_api_views
node_django_urls -->|"routes to"| node_api_views
node_api_views -->|"reads and writes"| node_db_models
node_scheduler -.->|"schedules"| node_tasks
node_tasks -->|"reads articles"| node_db_models
node_tasks -->|"runs collection"| node_agent
node_agent -->|"selects scrapers"| node_scrapers
node_agent -->|"supplements keyword results"| node_google_scraper
node_scrapers -.->|"scrapes publishers"| node_external_sources
node_google_scraper -->|"fetches RSS"| node_google_news
node_agent -->|"deduplicates"| node_deduplicator
node_agent -->|"processes articles"| node_processor
node_processor -->|"persists articles"| node_db_models
node_processor -->|"processes"| node_article_model
node_tasks -->|"sends digests"| node_email
node_app -.->|"uses icons"| node_icon_map

click node_app "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/App.js"
click node_layout "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/layout/Layout.js"
click node_navigation "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/layout/Navigation.js"
click node_home_sections "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/sections/FeaturedNews.js"
click node_article_image "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/common/ArticleImage.js"
click node_brand_seal "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/common/BrandSeal.js"
click node_search_page "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/SearchPage.js"
click node_article_page "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/ArticleDigestPage.js"
click node_account_page "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/AccountSettings.js"
click node_login_page "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/Login.js"
click node_faq_page "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/FAQPage.js"
click node_api_client "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/services/api.js"
click node_auth_client "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/services/authService.js"
click node_icon_map "https://github.com/waats0n/bytebrief/blob/master/Frontend/src/utils/iconMap.js"
click node_django_urls "https://github.com/waats0n/bytebrief/blob/master/backend/bytebrief_web/urls.py"
click node_api_views "https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/views.py"
click node_scheduler "https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/scheduler.py"
click node_tasks "https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/tasks.py"
click node_agent "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/orchestrator.py"
click node_scrapers "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/scrapers/factory.py"
click node_google_scraper "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/scrapers/google_search.py"
click node_processor "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/processor.py"
click node_deduplicator "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/comparer.py"
click node_article_model "https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/core/models.py"
click node_db_models "https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/models.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_app,node_layout,node_navigation,node_home_sections,node_article_image,node_brand_seal,node_search_page,node_article_page,node_account_page,node_login_page,node_faq_page,node_api_client,node_auth_client,node_icon_map toneBlue
class node_django_urls,node_api_views,node_scheduler,node_tasks toneAmber
class node_agent,node_scrapers,node_google_scraper toneMint
class node_processor,node_deduplicator,node_article_model toneRose
class node_db_models,node_reader,node_external_sources,node_google_news,node_email toneIndigo
```

## Components

### React experience

- [App and routes](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/App.js): `Frontend/src/App.js`
- [Page layout](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/layout/Layout.js): `Frontend/src/components/layout/Layout.js`
- [Navigation](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/layout/Navigation.js): `Frontend/src/components/layout/Navigation.js`
- [Digest sections](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/sections/FeaturedNews.js): `Frontend/src/components/sections/FeaturedNews.js`
- [Article imagery](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/common/ArticleImage.js): `Frontend/src/components/common/ArticleImage.js`
- [Brand seal](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/components/common/BrandSeal.js): `Frontend/src/components/common/BrandSeal.js`
- [Search results](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/SearchPage.js): `Frontend/src/pages/SearchPage.js`
- [Article digest](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/ArticleDigestPage.js): `Frontend/src/pages/ArticleDigestPage.js`
- [Account settings](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/AccountSettings.js): `Frontend/src/pages/AccountSettings.js`
- [Login](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/Login.js): `Frontend/src/pages/Login.js`
- [FAQ](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/pages/FAQPage.js): `Frontend/src/pages/FAQPage.js`
- [API client](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/services/api.js): `Frontend/src/services/api.js`
- [Authentication client](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/services/authService.js): `Frontend/src/services/authService.js`
- [Icon map](https://github.com/waats0n/bytebrief/blob/master/Frontend/src/utils/iconMap.js): `Frontend/src/utils/iconMap.js`

### Django application

- [API routing](https://github.com/waats0n/bytebrief/blob/master/backend/bytebrief_web/urls.py): `backend/bytebrief_web/urls.py`
- [API views](https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/views.py): `backend/news_brief/views.py`
- [Scheduled collection](https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/scheduler.py): `backend/news_brief/scheduler.py`
- [Background tasks](https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/tasks.py): `backend/news_brief/tasks.py`

### News collection

- [Agent orchestrator](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/orchestrator.py): `backend/src/bytebrief/agent/orchestrator.py`
- [News scrapers](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/scrapers/factory.py): `backend/src/bytebrief/scrapers/factory.py`
- [Keyword search scraper](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/scrapers/google_search.py): `backend/src/bytebrief/scrapers/google_search.py`

### Article processing

- [Categorize and summarize](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/processor.py): `backend/src/bytebrief/agent/processor.py`
- [Article comparer](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/agent/comparer.py): `backend/src/bytebrief/agent/comparer.py`
- [Scraped article model](https://github.com/waats0n/bytebrief/blob/master/backend/src/bytebrief/core/models.py): `backend/src/bytebrief/core/models.py`

### Product data

- [Users and news records](https://github.com/waats0n/bytebrief/blob/master/backend/news_brief/models.py): `backend/news_brief/models.py`

### Other components

- **Reader**
- **News publishers**
- **Google News RSS**
- **Email service**

## Connections

- Reader → App and routes: browses (evidence: `Frontend/src/App.js`)
- App and routes → Page layout: renders (evidence: `Frontend/src/App.js`)
- Page layout → Navigation: renders (evidence: `Frontend/src/components/layout/Layout.js`)
- App and routes → Digest sections: renders (evidence: `Frontend/src/App.js`)
- Digest sections → Article imagery: renders (evidence: `Frontend/src/components/sections/FeaturedNews.js`)
- Navigation → Brand seal: renders (evidence: `Frontend/src/components/layout/Navigation.js`)
- App and routes → API client: requests digest (evidence: `Frontend/src/App.js`)
- Search results → API client: requests results (evidence: `Frontend/src/pages/SearchPage.js`)
- Search results → Digest sections: renders results (evidence: `Frontend/src/pages/SearchPage.js`)
- App and routes → Article digest: routes to (evidence: `Frontend/src/App.js`)
- App and routes → Account settings: routes to (evidence: `Frontend/src/App.js`)
- App and routes → Login: routes to (evidence: `Frontend/src/App.js`)
- App and routes → FAQ: routes to (evidence: `Frontend/src/App.js`)
- Account settings → API client: uses (evidence: `Frontend/src/pages/AccountSettings.js`)
- Account settings → Authentication client: uses (evidence: `Frontend/src/pages/AccountSettings.js`)
- Login → Authentication client: authenticates via
- Authentication client → API client: uses base URL (evidence: `Frontend/src/services/authService.js`)
- API client → API views: HTTP requests
- API routing → API views: routes to (evidence: `backend/bytebrief_web/urls.py`)
- API views → Users and news records: reads and writes (evidence: `backend/news_brief/views.py`)
- Scheduled collection → Background tasks: schedules
- Background tasks → Users and news records: reads articles (evidence: `backend/news_brief/tasks.py`)
- Background tasks → Agent orchestrator: runs collection (evidence: `backend/news_brief/tasks.py`)
- Agent orchestrator → News scrapers: selects scrapers (evidence: `backend/src/bytebrief/agent/orchestrator.py`)
- Agent orchestrator → Keyword search scraper: supplements keyword results (evidence: `backend/src/bytebrief/agent/orchestrator.py`)
- News scrapers → News publishers: scrapes publishers
- Keyword search scraper → Google News RSS: fetches RSS (evidence: `backend/src/bytebrief/scrapers/google_search.py`)
- Agent orchestrator → Article comparer: deduplicates (evidence: `backend/src/bytebrief/agent/orchestrator.py`)
- Agent orchestrator → Categorize and summarize: processes articles (evidence: `backend/src/bytebrief/agent/orchestrator.py`)
- Categorize and summarize → Users and news records: persists articles (evidence: `backend/src/bytebrief/agent/processor.py`)
- Categorize and summarize → Scraped article model: processes (evidence: `backend/src/bytebrief/agent/processor.py`)
- Background tasks → Email service: sends digests (evidence: `backend/news_brief/tasks.py`)
- App and routes → Icon map: uses icons
