# m1zhar/tsrp architecture

> Architecture diagram of the GitHub repository m1zhar/tsrp, 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/m1zhar/tsrp
- Repository: https://github.com/m1zhar/tsrp

## Overview

TSRP is an educational listed-company research app: a user selects a ticker and research section, the frontend presents analysis and related views, and the Python service supplies analysis and market data. The backend is the calculation authority; it gathers and aligns provider data before computing scores and valuation. The README also identifies expectations, catalysts and risks, snapshot comparison, charts, and exports as product capabilities. Some frontend wiring and unsampled endpoint implementations are not shown, so those relationships are omitted where evidence is insufficient.

Main entry points: [`backend/api/index.py`](https://github.com/m1zhar/tsrp/blob/main/backend/api/index.py) (ASGI dispatcher), [`backend/research_service.py`](https://github.com/m1zhar/tsrp/blob/main/backend/research_service.py) (Research orchestration), [`frontend/components/research-workspace.tsx`](https://github.com/m1zhar/tsrp/blob/main/frontend/components/research-workspace.tsx) (Research workspace), [`backend/api/analyze.py`](https://github.com/m1zhar/tsrp/blob/main/backend/api/analyze.py) (Company analysis route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research frontend"]
  node_workspace["Research workspace"]
  node_research_brief["Research brief<br/>[research-brief.ts]"]
  node_chart["Price chart<br/>[price-chart.tsx]"]
  node_export["Research export<br/>[research-export.ts]"]
  node_snapshot_ui["Snapshot comparison"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_token_route["Backend token route<br/>[route.ts]"]
end

subgraph group_api["API service"]
  node_api_entry["ASGI dispatcher<br/>[index.py]"]
  node_analyze["Company analysis route<br/>[analyze.py]"]
  node_search["Company search route<br/>[search.py]"]
  node_scenario["Scenario route<br/>[scenario.py]"]
  node_movers["Market movers route<br/>[movers.py]"]
  node_top_stocks["Top stocks route<br/>[top_stocks.py]"]
  node_snapshot_diff["Snapshot diff route<br/>[snapshot_diff.py]"]
end

subgraph group_analysis["Research calculations"]
  node_service["Research orchestration"]
  node_engine["Score and valuation<br/>[engine.py]"]
  node_expectations["Growth expectations<br/>[expectations.py]"]
  node_valuation_basis["Valuation basis<br/>[valuation_basis.py]"]
end

subgraph group_data["Market data"]
  node_financial_data["Period alignment<br/>[financial_data.py]"]
  node_providers["Yahoo and SEC adapters"]
end

subgraph group_security["Request security"]
  node_api_auth["API token verification<br/>[api_auth.py]"]
  node_scenario_context["Signed scenario context"]
  node_token_minter["Token issuance"]
end

node_researcher(("Researcher"))

node_researcher -->|"selects research"| node_workspace
node_workspace -->|"presents research"| node_research_brief
node_workspace -->|"shows charts"| node_chart
node_research_brief -->|"supports export"| node_export
node_workspace -->|"offers comparison"| node_snapshot_ui
node_api_entry -->|"dispatches"| node_analyze
node_api_entry -->|"dispatches"| node_search
node_api_entry -->|"dispatches"| node_scenario
node_api_entry -->|"dispatches"| node_movers
node_api_entry -->|"dispatches"| node_top_stocks
node_api_entry -->|"dispatches"| node_snapshot_diff
node_analyze -->|"analyzes company"| node_service
node_analyze -->|"issues context"| node_scenario_context
node_analyze -->|"checks token"| node_api_auth
node_search -->|"checks token"| node_api_auth
node_search -->|"searches companies"| node_service
node_service -->|"calculates valuation"| node_engine
node_service -->|"uses expectations"| node_expectations
node_service -->|"selects basis"| node_valuation_basis
node_service -->|"aligns periods"| node_financial_data
node_providers -->|"aligns provider data"| node_financial_data
node_token_route -.->|"issues token"| node_token_minter
node_token_minter -.->|"authorizes requests"| node_api_auth

click node_workspace "https://github.com/m1zhar/tsrp/blob/main/frontend/components/research-workspace.tsx"
click node_research_brief "https://github.com/m1zhar/tsrp/blob/main/frontend/lib/research-brief.ts"
click node_chart "https://github.com/m1zhar/tsrp/blob/main/frontend/components/price-chart.tsx"
click node_export "https://github.com/m1zhar/tsrp/blob/main/frontend/lib/research-export.ts"
click node_snapshot_ui "https://github.com/m1zhar/tsrp/blob/main/frontend/lib/snapshot-comparison.ts"
click node_api_client "https://github.com/m1zhar/tsrp/blob/main/frontend/lib/api-client.ts"
click node_token_route "https://github.com/m1zhar/tsrp/blob/main/frontend/app/api/backend-token/route.ts"
click node_api_entry "https://github.com/m1zhar/tsrp/blob/main/backend/api/index.py"
click node_analyze "https://github.com/m1zhar/tsrp/blob/main/backend/api/analyze.py"
click node_search "https://github.com/m1zhar/tsrp/blob/main/backend/api/search.py"
click node_scenario "https://github.com/m1zhar/tsrp/blob/main/backend/api/scenario.py"
click node_movers "https://github.com/m1zhar/tsrp/blob/main/backend/api/movers.py"
click node_top_stocks "https://github.com/m1zhar/tsrp/blob/main/backend/api/top_stocks.py"
click node_snapshot_diff "https://github.com/m1zhar/tsrp/blob/main/backend/api/snapshot_diff.py"
click node_service "https://github.com/m1zhar/tsrp/blob/main/backend/research_service.py"
click node_engine "https://github.com/m1zhar/tsrp/blob/main/backend/engine.py"
click node_expectations "https://github.com/m1zhar/tsrp/blob/main/backend/expectations.py"
click node_valuation_basis "https://github.com/m1zhar/tsrp/blob/main/backend/valuation_basis.py"
click node_financial_data "https://github.com/m1zhar/tsrp/blob/main/backend/financial_data.py"
click node_providers "https://github.com/m1zhar/tsrp/blob/main/backend/research_service.py"
click node_api_auth "https://github.com/m1zhar/tsrp/blob/main/backend/api_auth.py"
click node_scenario_context "https://github.com/m1zhar/tsrp/blob/main/backend/scenario_context.py"
click node_token_minter "https://github.com/m1zhar/tsrp/blob/main/frontend/lib/api-access-token.ts"

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_workspace,node_research_brief,node_chart,node_export,node_snapshot_ui,node_api_client,node_token_route toneBlue
class node_api_entry,node_analyze,node_search,node_scenario,node_movers,node_top_stocks,node_snapshot_diff toneAmber
class node_service,node_engine,node_expectations,node_valuation_basis toneMint
class node_financial_data,node_providers toneRose
class node_api_auth,node_scenario_context,node_token_minter,node_researcher toneIndigo
```

## Components

### Research frontend

- [Research workspace](https://github.com/m1zhar/tsrp/blob/main/frontend/components/research-workspace.tsx): `frontend/components/research-workspace.tsx`
- [Research brief](https://github.com/m1zhar/tsrp/blob/main/frontend/lib/research-brief.ts): `frontend/lib/research-brief.ts`
- [Price chart](https://github.com/m1zhar/tsrp/blob/main/frontend/components/price-chart.tsx): `frontend/components/price-chart.tsx`
- [Research export](https://github.com/m1zhar/tsrp/blob/main/frontend/lib/research-export.ts): `frontend/lib/research-export.ts`
- [Snapshot comparison](https://github.com/m1zhar/tsrp/blob/main/frontend/lib/snapshot-comparison.ts): `frontend/lib/snapshot-comparison.ts`
- [API client](https://github.com/m1zhar/tsrp/blob/main/frontend/lib/api-client.ts): `frontend/lib/api-client.ts`
- [Backend token route](https://github.com/m1zhar/tsrp/blob/main/frontend/app/api/backend-token/route.ts): `frontend/app/api/backend-token/route.ts`

### API service

- [ASGI dispatcher](https://github.com/m1zhar/tsrp/blob/main/backend/api/index.py): `backend/api/index.py`
- [Company analysis route](https://github.com/m1zhar/tsrp/blob/main/backend/api/analyze.py): `backend/api/analyze.py`
- [Company search route](https://github.com/m1zhar/tsrp/blob/main/backend/api/search.py): `backend/api/search.py`
- [Scenario route](https://github.com/m1zhar/tsrp/blob/main/backend/api/scenario.py): `backend/api/scenario.py`
- [Market movers route](https://github.com/m1zhar/tsrp/blob/main/backend/api/movers.py): `backend/api/movers.py`
- [Top stocks route](https://github.com/m1zhar/tsrp/blob/main/backend/api/top_stocks.py): `backend/api/top_stocks.py`
- [Snapshot diff route](https://github.com/m1zhar/tsrp/blob/main/backend/api/snapshot_diff.py): `backend/api/snapshot_diff.py`

### Research calculations

- [Research orchestration](https://github.com/m1zhar/tsrp/blob/main/backend/research_service.py): `backend/research_service.py`
- [Score and valuation](https://github.com/m1zhar/tsrp/blob/main/backend/engine.py): `backend/engine.py`
- [Growth expectations](https://github.com/m1zhar/tsrp/blob/main/backend/expectations.py): `backend/expectations.py`
- [Valuation basis](https://github.com/m1zhar/tsrp/blob/main/backend/valuation_basis.py): `backend/valuation_basis.py`

### Market data

- [Period alignment](https://github.com/m1zhar/tsrp/blob/main/backend/financial_data.py): `backend/financial_data.py`
- [Yahoo and SEC adapters](https://github.com/m1zhar/tsrp/blob/main/backend/research_service.py): `backend/research_service.py`

### Request security

- [API token verification](https://github.com/m1zhar/tsrp/blob/main/backend/api_auth.py): `backend/api_auth.py`
- [Signed scenario context](https://github.com/m1zhar/tsrp/blob/main/backend/scenario_context.py): `backend/scenario_context.py`
- [Token issuance](https://github.com/m1zhar/tsrp/blob/main/frontend/lib/api-access-token.ts): `frontend/lib/api-access-token.ts`

### Other components

- **Researcher**

## Connections

- Researcher → Research workspace: selects research (evidence: `README.md`)
- Research workspace → Research brief: presents research (evidence: `README.md`)
- Research workspace → Price chart: shows charts (evidence: `README.md`)
- Research brief → Research export: supports export (evidence: `frontend/lib/research-export.ts`)
- Research workspace → Snapshot comparison: offers comparison (evidence: `README.md`)
- ASGI dispatcher → Company analysis route: dispatches (evidence: `backend/api/index.py`)
- ASGI dispatcher → Company search route: dispatches (evidence: `backend/api/index.py`)
- ASGI dispatcher → Scenario route: dispatches (evidence: `backend/api/index.py`)
- ASGI dispatcher → Market movers route: dispatches (evidence: `backend/api/index.py`)
- ASGI dispatcher → Top stocks route: dispatches (evidence: `backend/api/index.py`)
- ASGI dispatcher → Snapshot diff route: dispatches (evidence: `backend/api/index.py`)
- Company analysis route → Research orchestration: analyzes company (evidence: `backend/api/analyze.py`)
- Company analysis route → Signed scenario context: issues context (evidence: `backend/api/analyze.py`)
- Company analysis route → API token verification: checks token (evidence: `backend/api/analyze.py`)
- Company search route → API token verification: checks token (evidence: `backend/api/search.py`)
- Company search route → Research orchestration: searches companies (evidence: `backend/api/search.py`)
- Research orchestration → Score and valuation: calculates valuation (evidence: `backend/research_service.py`)
- Research orchestration → Growth expectations: uses expectations (evidence: `backend/research_service.py`)
- Research orchestration → Valuation basis: selects basis (evidence: `backend/research_service.py`)
- Research orchestration → Period alignment: aligns periods (evidence: `backend/research_service.py`)
- Yahoo and SEC adapters → Period alignment: aligns provider data (evidence: `backend/research_service.py`)
- Backend token route → Token issuance: issues token
- Token issuance → API token verification: authorizes requests
