# tarenpaper/valoreax architecture

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

- Interactive diagram: https://gitdiagram.com/tarenpaper/valoreax
- Repository: https://github.com/tarenpaper/valoreax

## Overview

ValoreaX is an account-scoped biotech research application. A user signs in, selects a public healthcare company, and the frontend requests backend research APIs; SEC data is ingested, normalized and persisted before valuation, catalyst tracking and explainable signals are presented. Separate product branches cover news, analyst coverage, watchlists, backtesting and experimental clinical-trial ML. The graph reflects README capabilities and the supplied source index/excerpts; several API and service internals were not sampled, so undocumented connections are omitted.

Main entry points: [`backend/app/api/v1`](https://github.com/tarenpaper/valoreax/tree/main/backend/app/api/v1) (Versioned API), [`frontend/src/api/client.ts`](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/api/client.ts) (Typed API client), [`backend/app/services/ingestion_service.py`](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/ingestion_service.py) (SEC ingestion), [`backend/app/models`](https://github.com/tarenpaper/valoreax/tree/main/backend/app/models) (Research data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_auth["Account access<br/>[AuthGate.tsx]"]
  node_app["Application navigation<br/>[App.tsx]"]
  node_dashboard["Company dashboard<br/>[Dashboard.tsx]"]
  node_newsui["News dashboard<br/>[News.tsx]"]
  node_watchui["Watchlists<br/>[Watchlist.tsx]"]
  node_backtestui["Backtest view<br/>[Backtest.tsx]"]
  node_api_client["Typed API client<br/>[client.ts]"]
end

subgraph group_ingestion["Data ingestion"]
  node_providers["External data adapters<br/>[base.py]"]
  node_ingest["SEC ingestion"]
  node_normalize["Financial normalization<br/>[normalization.py]"]
end

subgraph group_research["Research intelligence"]
  node_valuation["Drug valuation<br/>[rnpv_valuation.py]"]
  node_signals["Explainable signals<br/>[signals.py]"]
  node_catalysts["Catalyst tracking"]
  node_analysts["Analyst coverage"]
  node_news["News intelligence<br/>[news_analysis.py]"]
  node_watchlists["Watchlist service<br/>[watchlist.py]"]
  node_backtests["Signal evaluation<br/>[evaluation.py]"]
  node_gemini["Evidence research<br/>[research.py]"]
  node_gemini_provider["Gemini adapter<br/>[gemini.py]"]
end

subgraph group_platform["Backend platform"]
  node_api["Versioned API"]
  node_auth_backend["API authorization<br/>[auth.py]"]
  node_models[("Research data models")]
end

subgraph group_clinicalml["Clinical ML"]
  node_clinicalml_ui["Clinical ML panel"]
  node_clinicalml["Clinical ML workflow<br/>[clinical_ml.py]"]
  node_ml_training["Model training<br/>[training.py]"]
end

node_user(("Research user"))

node_user -->|"signs in"| node_auth
node_auth -->|"opens workspace"| node_app
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_newsui
node_api_client -->|"gets token"| node_auth
node_dashboard -->|"requests data"| node_api_client
node_newsui -->|"requests news"| node_api_client
node_watchui -->|"requests watchlists"| node_api_client
node_backtestui -->|"requests evaluation"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"protects requests"| node_auth_backend
node_api -.->|"starts ingestion"| node_ingest
node_ingest -->|"fetches facts"| node_providers
node_ingest -->|"normalizes payload"| node_normalize
node_ingest -->|"persists filings"| node_models
node_normalize -.->|"supplies metrics"| node_models
node_api -.->|"serves valuation"| node_valuation
node_api -.->|"serves signals"| node_signals
node_api -.->|"serves catalysts"| node_catalysts
node_api -.->|"serves analyst data"| node_analysts
node_api -.->|"serves news"| node_news
node_api -.->|"serves watchlists"| node_watchlists
node_api -.->|"evaluates signals"| node_backtests
node_api -->|"routes research"| node_gemini
node_gemini -->|"generates analysis"| node_gemini_provider
node_clinicalml_ui -.->|"requests ML"| node_api_client
node_api -.->|"serves trial model"| node_clinicalml
node_clinicalml -.->|"uses trained models"| node_ml_training
node_valuation -.->|"reads research data"| node_models
node_signals -.->|"persists signal runs"| node_models

click node_auth "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/auth/AuthGate.tsx"
click node_app "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Dashboard.tsx"
click node_newsui "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/News.tsx"
click node_watchui "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Watchlist.tsx"
click node_backtestui "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Backtest.tsx"
click node_api_client "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/tarenpaper/valoreax/tree/main/backend/app/api/v1"
click node_auth_backend "https://github.com/tarenpaper/valoreax/blob/main/backend/app/auth.py"
click node_providers "https://github.com/tarenpaper/valoreax/blob/main/backend/app/providers/base.py"
click node_ingest "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/ingestion_service.py"
click node_normalize "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/normalization.py"
click node_models "https://github.com/tarenpaper/valoreax/tree/main/backend/app/models"
click node_valuation "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/rnpv_valuation.py"
click node_signals "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/signals.py"
click node_catalysts "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/catalyst_ingestion.py"
click node_analysts "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/analyst_ingestion.py"
click node_news "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/news_analysis.py"
click node_watchlists "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/watchlist.py"
click node_backtests "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/evaluation.py"
click node_clinicalml_ui "https://github.com/tarenpaper/valoreax/blob/main/frontend/src/components/ClinicalMLPanel.tsx"
click node_clinicalml "https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/clinical_ml.py"
click node_ml_training "https://github.com/tarenpaper/valoreax/blob/main/backend/app/ml/training.py"
click node_gemini "https://github.com/tarenpaper/valoreax/blob/main/backend/app/api/v1/research.py"
click node_gemini_provider "https://github.com/tarenpaper/valoreax/blob/main/backend/app/providers/gemini.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_auth,node_app,node_dashboard,node_newsui,node_watchui,node_backtestui,node_api_client,node_user toneBlue
class node_providers,node_ingest,node_normalize toneAmber
class node_valuation,node_signals,node_catalysts,node_analysts,node_news,node_watchlists,node_backtests,node_gemini,node_gemini_provider toneMint
class node_api,node_auth_backend,node_models toneRose
class node_clinicalml_ui,node_clinicalml,node_ml_training toneIndigo
```

## Components

### User experience

- [Account access](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/auth/AuthGate.tsx): `frontend/src/auth/AuthGate.tsx`
- [Application navigation](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Company dashboard](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [News dashboard](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/News.tsx): `frontend/src/pages/News.tsx`
- [Watchlists](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Watchlist.tsx): `frontend/src/pages/Watchlist.tsx`
- [Backtest view](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/pages/Backtest.tsx): `frontend/src/pages/Backtest.tsx`
- [Typed API client](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Data ingestion

- [External data adapters](https://github.com/tarenpaper/valoreax/blob/main/backend/app/providers/base.py): `backend/app/providers/base.py`
- [SEC ingestion](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Financial normalization](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/normalization.py): `backend/app/services/normalization.py`

### Research intelligence

- [Drug valuation](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/rnpv_valuation.py): `backend/app/services/rnpv_valuation.py`
- [Explainable signals](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/signals.py): `backend/app/services/signals.py`
- [Catalyst tracking](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/catalyst_ingestion.py): `backend/app/services/catalyst_ingestion.py`
- [Analyst coverage](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/analyst_ingestion.py): `backend/app/services/analyst_ingestion.py`
- [News intelligence](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/news_analysis.py): `backend/app/services/news_analysis.py`
- [Watchlist service](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/watchlist.py): `backend/app/services/watchlist.py`
- [Signal evaluation](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/evaluation.py): `backend/app/services/evaluation.py`
- [Evidence research](https://github.com/tarenpaper/valoreax/blob/main/backend/app/api/v1/research.py): `backend/app/api/v1/research.py`
- [Gemini adapter](https://github.com/tarenpaper/valoreax/blob/main/backend/app/providers/gemini.py): `backend/app/providers/gemini.py`

### Backend platform

- [Versioned API](https://github.com/tarenpaper/valoreax/tree/main/backend/app/api/v1): `backend/app/api/v1`
- [API authorization](https://github.com/tarenpaper/valoreax/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Research data models](https://github.com/tarenpaper/valoreax/tree/main/backend/app/models): `backend/app/models`

### Clinical ML

- [Clinical ML panel](https://github.com/tarenpaper/valoreax/blob/main/frontend/src/components/ClinicalMLPanel.tsx): `frontend/src/components/ClinicalMLPanel.tsx`
- [Clinical ML workflow](https://github.com/tarenpaper/valoreax/blob/main/backend/app/services/clinical_ml.py): `backend/app/services/clinical_ml.py`
- [Model training](https://github.com/tarenpaper/valoreax/blob/main/backend/app/ml/training.py): `backend/app/ml/training.py`

### Other components

- **Research user**

## Connections

- Research user → Account access: signs in (evidence: `frontend/src/auth/AuthGate.tsx`)
- Account access → Application navigation: opens workspace (evidence: `frontend/src/main.tsx`)
- Application navigation → Company dashboard: renders (evidence: `frontend/src/App.tsx`)
- Application navigation → News dashboard: renders (evidence: `frontend/src/App.tsx`)
- Typed API client → Account access: gets token (evidence: `frontend/src/api/client.ts`)
- Company dashboard → Typed API client: requests data (evidence: `frontend/src/pages/Dashboard.tsx`)
- News dashboard → Typed API client: requests news (evidence: `frontend/src/pages/News.tsx`)
- Watchlists → Typed API client: requests watchlists (evidence: `frontend/src/pages/Watchlist.tsx`)
- Backtest view → Typed API client: requests evaluation (evidence: `frontend/src/pages/Backtest.tsx`)
- Typed API client → Versioned API: calls API (evidence: `frontend/src/api/client.ts`)
- Versioned API → API authorization: protects requests
- Versioned API → SEC ingestion: starts ingestion
- SEC ingestion → External data adapters: fetches facts (evidence: `backend/app/services/ingestion_service.py`)
- SEC ingestion → Financial normalization: normalizes payload (evidence: `backend/app/services/ingestion_service.py`)
- SEC ingestion → Research data models: persists filings (evidence: `backend/app/services/ingestion_service.py`)
- Financial normalization → Research data models: supplies metrics
- Versioned API → Drug valuation: serves valuation
- Versioned API → Explainable signals: serves signals
- Versioned API → Catalyst tracking: serves catalysts
- Versioned API → Analyst coverage: serves analyst data
- Versioned API → News intelligence: serves news
- Versioned API → Watchlist service: serves watchlists
- Versioned API → Signal evaluation: evaluates signals
- Versioned API → Evidence research: routes research (evidence: `backend/app/api/v1/research.py`)
- Evidence research → Gemini adapter: generates analysis (evidence: `backend/app/api/v1/research.py`)
- Clinical ML panel → Typed API client: requests ML
- Versioned API → Clinical ML workflow: serves trial model
- Clinical ML workflow → Model training: uses trained models
- Drug valuation → Research data models: reads research data
- Explainable signals → Research data models: persists signal runs