# lwandomac/alpha-brief architecture

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

- Interactive diagram: https://gitdiagram.com/lwandomac/alpha-brief
- Repository: https://github.com/lwandomac/alpha-brief

## Overview

Alpha Brief is a focused investment-research journal: users record a ticker thesis and its assumptions, request an on-demand check using news or pasted text, then review the verdict and conviction history. The frontend pages use a typed API client to reach FastAPI routes. Thesis routes manage saved theses; the check route owns orchestration, calling the AI evaluator and persisting each result. The evaluator optionally fetches Google News snippets and calls the configured LLM. Storage and UI component wiring are based on README documentation where source excerpts were not provided.

Main entry points: [`frontend/src/App.tsx`](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/App.tsx) (Web app), [`backend/src/lib/ai.py`](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/ai.py) (Thesis evaluator), [`frontend/src/pages/ThesisDetail.tsx`](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/ThesisDetail.tsx) (Thesis detail), [`backend/src/routes/check.py`](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/routes/check.py) (Check route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research interface"]
  node_app["Web app<br/>[App.tsx]"]
  node_thesis_list["Thesis list<br/>[ThesisList.tsx]"]
  node_new_thesis["New thesis<br/>[NewThesis.tsx]"]
  node_thesis_detail["Thesis detail<br/>[ThesisDetail.tsx]"]
  node_chart["Conviction chart"]
  node_api_client["Typed API client<br/>[client.ts]"]
end

subgraph group_api["API and workflows"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_thesis_routes["Thesis routes<br/>[theses.py]"]
  node_check_route["Check route<br/>[check.py]"]
end

subgraph group_analysis["Check analysis"]
  node_ai_eval["Thesis evaluator<br/>[ai.py]"]
  node_news_search["News search<br/>[search.py]"]
  node_config["LLM configuration<br/>[config.py]"]
end

subgraph group_state["Persistent state"]
  node_database[("SQLite database<br/>[db.py]")]
end

node_researcher(("Researcher"))
node_llm{{"LLM provider"}}
node_google_news{{"Google News RSS"}}

node_researcher -->|"uses"| node_app
node_app -->|"routes to"| node_thesis_list
node_app -->|"routes to"| node_new_thesis
node_app -->|"routes to"| node_thesis_detail
node_thesis_list -->|"requests data"| node_api_client
node_new_thesis -->|"creates thesis"| node_api_client
node_thesis_detail -->|"requests and checks"| node_api_client
node_thesis_detail -->|"renders history"| node_chart
node_api_app -->|"registers router"| node_thesis_routes
node_api_app -->|"registers router"| node_check_route
node_thesis_routes -->|"reads and writes"| node_database
node_check_route -->|"loads and saves"| node_database
node_check_route -->|"runs evaluation"| node_ai_eval
node_ai_eval -->|"fetches snippets"| node_news_search
node_news_search -->|"requests RSS"| node_google_news
node_ai_eval -->|"reads provider settings"| node_config
node_ai_eval -->|"submits evaluation"| node_llm

click node_app "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/App.tsx"
click node_thesis_list "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/ThesisList.tsx"
click node_new_thesis "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/NewThesis.tsx"
click node_thesis_detail "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/ThesisDetail.tsx"
click node_chart "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/components/ConvictionChart.tsx"
click node_api_client "https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/api/client.ts"
click node_api_app "https://github.com/lwandomac/alpha-brief/blob/main/backend/main.py"
click node_thesis_routes "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/routes/theses.py"
click node_check_route "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/routes/check.py"
click node_ai_eval "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/ai.py"
click node_news_search "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/search.py"
click node_config "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/config.py"
click node_database "https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/db.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_thesis_list,node_new_thesis,node_thesis_detail,node_chart,node_api_client toneBlue
class node_api_app,node_thesis_routes,node_check_route toneAmber
class node_ai_eval,node_news_search,node_config toneMint
class node_database toneRose
class node_researcher,node_llm,node_google_news toneIndigo
```

## Components

### Research interface

- [Web app](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Thesis list](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/ThesisList.tsx): `frontend/src/pages/ThesisList.tsx`
- [New thesis](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/NewThesis.tsx): `frontend/src/pages/NewThesis.tsx`
- [Thesis detail](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/pages/ThesisDetail.tsx): `frontend/src/pages/ThesisDetail.tsx`
- [Conviction chart](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/components/ConvictionChart.tsx): `frontend/src/components/ConvictionChart.tsx`
- [Typed API client](https://github.com/lwandomac/alpha-brief/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and workflows

- [FastAPI app](https://github.com/lwandomac/alpha-brief/blob/main/backend/main.py): `backend/main.py`
- [Thesis routes](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/routes/theses.py): `backend/src/routes/theses.py`
- [Check route](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/routes/check.py): `backend/src/routes/check.py`

### Check analysis

- [Thesis evaluator](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/ai.py): `backend/src/lib/ai.py`
- [News search](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/search.py): `backend/src/lib/search.py`
- [LLM configuration](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/config.py): `backend/src/config.py`

### Persistent state

- [SQLite database](https://github.com/lwandomac/alpha-brief/blob/main/backend/src/lib/db.py): `backend/src/lib/db.py`

### Other components

- **Researcher**
- **LLM provider**
- **Google News RSS**

## Connections

- Researcher → Web app: uses
- Web app → Thesis list: routes to
- Web app → New thesis: routes to
- Web app → Thesis detail: routes to
- Thesis list → Typed API client: requests data
- New thesis → Typed API client: creates thesis
- Thesis detail → Typed API client: requests and checks
- Thesis detail → Conviction chart: renders history
- FastAPI app → Thesis routes: registers router
- FastAPI app → Check route: registers router
- Thesis routes → SQLite database: reads and writes
- Check route → SQLite database: loads and saves
- Check route → Thesis evaluator: runs evaluation
- Thesis evaluator → News search: fetches snippets
- News search → Google News RSS: requests RSS
- Thesis evaluator → LLM configuration: reads provider settings
- Thesis evaluator → LLM provider: submits evaluation