# hemanthsrp/hackmidwest26 architecture

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

- Interactive diagram: https://gitdiagram.com/hemanthsrp/hackmidwest26
- Repository: https://github.com/hemanthsrp/hackmidwest26

## Overview

Folio is an evidence-backed stock-research application: source adapters collect dated news, filings, disclosures, and market signals; the Research API and decision-maker turn stored evidence into a transparent assessment; the authenticated frontend presents research and account features. Separate branches cover portfolio linking, notifications, and option-volatility diagnostics. The README documents the main service boundaries; source-index references and excerpts support internal calls and persistence. Several frontend and auxiliary service internals were not sampled, so uncertain connections are omitted.

Main entry points: [`microservices/research-api/src/research_api/app.py`](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/app.py) (Research API), [`microservices/research-api/src/research_api/v1.py`](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/v1.py) (Research and account routes), [`microservices/decision-maker/src/decision_maker/service.py`](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/service.py) (Decision workflow), [`microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py`](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py) (Source ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web application"]
  node_dashboard["Research screens<br/>[page.tsx]"]
  node_research_route["Research endpoint<br/>[route.ts]"]
  node_frontend_api["Account and app APIs"]
  node_frontend_db[("Frontend database<br/>[db.ts]")]
end

subgraph group_collection["Evidence collection"]
  node_source_ingest["Source ingestion<br/>[ingest.py]"]
  node_source_adapters["Evidence sources"]
  node_evidence_pipeline["Evidence processing"]
  node_evidence_store[("Evidence store<br/>[store.py]")]
end

subgraph group_research["Research and assessment"]
  node_api_app["Research API<br/>[app.py]"]
  node_api_v1["Research and account routes<br/>[v1.py]"]
  node_api_assessment["Assessment orchestration<br/>[assessment.py]"]
  node_user_records[("Research user records<br/>[storage.py]")]
  node_decision_service["Decision workflow<br/>[service.py]"]
  node_evidence_reader["Evidence retrieval<br/>[retrieval.py]"]
  node_assessment_legs["Evidence readings<br/>[legs.py]"]
  node_assessment_explain["Assessment explanation<br/>[explain.py]"]
end

subgraph group_integrations["External integrations"]
  node_broker["Robinhood read-only link<br/>[broker.py]"]
  node_notifications["Notifications and digest<br/>[notifications.py]"]
end

subgraph group_market["Market diagnostics"]
  node_volatility["Volatility surface<br/>[pipeline.py]"]
  node_options_feed["Option data feed<br/>[data_feed.py]"]
end

node_researcher(("Research user"))
node_broker_service["Robinhood"]
node_market_provider["Market and news providers"]

node_researcher -->|"views research"| node_dashboard
node_dashboard -.->|"requests research"| node_research_route
node_research_route -.->|"forwards requests"| node_api_app
node_researcher -->|"uses account features"| node_frontend_api
node_frontend_api -.->|"uses"| node_frontend_db
node_api_app -->|"routes assessments"| node_api_assessment
node_api_app -->|"registers routes"| node_api_v1
node_api_app -->|"uses persistence"| node_user_records
node_api_v1 -->|"reads and writes"| node_user_records
node_api_v1 -->|"handles broker flow"| node_broker
node_api_v1 -->|"uses notifications"| node_notifications
node_api_assessment -->|"invokes assessment"| node_decision_service
node_source_ingest -->|"fetches evidence"| node_source_adapters
node_source_ingest -->|"processes records"| node_evidence_pipeline
node_source_ingest -->|"saves records"| node_evidence_store
node_source_adapters -.->|"retrieves data"| node_market_provider
node_evidence_reader -->|"reads evidence"| node_evidence_store
node_decision_service -->|"loads records"| node_evidence_reader
node_decision_service -->|"builds readings"| node_assessment_legs
node_decision_service -->|"creates explanation"| node_assessment_explain
node_broker -.->|"uses OAuth"| node_broker_service
node_volatility -->|"retrieves option data"| node_options_feed
node_options_feed -.->|"queries market data"| node_market_provider

click node_dashboard "https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/app/(dashboard)/stocks/%5Bsymbol%5D/page.tsx"
click node_research_route "https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/app/api/research/route.ts"
click node_frontend_api "https://github.com/hemanthsrp/hackmidwest26/tree/main/frontend/src/app/api"
click node_frontend_db "https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/lib/db.ts"
click node_source_ingest "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py"
click node_source_adapters "https://github.com/hemanthsrp/hackmidwest26/tree/main/microservices/scraper-analysis/src/scraper_analysis/sources"
click node_evidence_pipeline "https://github.com/hemanthsrp/hackmidwest26/tree/main/microservices/scraper-analysis/src/scraper_analysis/pipeline"
click node_evidence_store "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/scraper-analysis/src/scraper_analysis/storage/store.py"
click node_api_app "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/app.py"
click node_api_v1 "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/v1.py"
click node_api_assessment "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/assessment.py"
click node_user_records "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/storage.py"
click node_decision_service "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/service.py"
click node_evidence_reader "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/retrieval.py"
click node_assessment_legs "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/legs.py"
click node_assessment_explain "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/explain.py"
click node_broker "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/broker.py"
click node_notifications "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/notifications.py"
click node_volatility "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/volatility-surface-builder/src/vol_surface_builder/pipeline.py"
click node_options_feed "https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/volatility-surface-builder/src/vol_surface_builder/data_feed.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_dashboard,node_research_route,node_frontend_api,node_frontend_db,node_researcher toneBlue
class node_source_ingest,node_source_adapters,node_evidence_pipeline,node_evidence_store toneAmber
class node_api_app,node_api_v1,node_api_assessment,node_user_records,node_decision_service,node_evidence_reader,node_assessment_legs,node_assessment_explain toneMint
class node_broker,node_notifications toneRose
class node_volatility,node_options_feed,node_broker_service,node_market_provider toneIndigo
```

## Components

### Web application

- [Research screens](https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/app/(dashboard)/stocks/%5Bsymbol%5D/page.tsx): `frontend/src/app/(dashboard)/stocks/[symbol]/page.tsx`
- [Research endpoint](https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/app/api/research/route.ts): `frontend/src/app/api/research/route.ts`
- [Account and app APIs](https://github.com/hemanthsrp/hackmidwest26/tree/main/frontend/src/app/api): `frontend/src/app/api`
- [Frontend database](https://github.com/hemanthsrp/hackmidwest26/blob/main/frontend/src/lib/db.ts): `frontend/src/lib/db.ts`

### Evidence collection

- [Source ingestion](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py): `microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py`
- [Evidence sources](https://github.com/hemanthsrp/hackmidwest26/tree/main/microservices/scraper-analysis/src/scraper_analysis/sources): `microservices/scraper-analysis/src/scraper_analysis/sources`
- [Evidence processing](https://github.com/hemanthsrp/hackmidwest26/tree/main/microservices/scraper-analysis/src/scraper_analysis/pipeline): `microservices/scraper-analysis/src/scraper_analysis/pipeline`
- [Evidence store](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/scraper-analysis/src/scraper_analysis/storage/store.py): `microservices/scraper-analysis/src/scraper_analysis/storage/store.py`

### Research and assessment

- [Research API](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/app.py): `microservices/research-api/src/research_api/app.py`
- [Research and account routes](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/v1.py): `microservices/research-api/src/research_api/v1.py`
- [Assessment orchestration](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/assessment.py): `microservices/research-api/src/research_api/assessment.py`
- [Research user records](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/storage.py): `microservices/research-api/src/research_api/storage.py`
- [Decision workflow](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/service.py): `microservices/decision-maker/src/decision_maker/service.py`
- [Evidence retrieval](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/retrieval.py): `microservices/decision-maker/src/decision_maker/retrieval.py`
- [Evidence readings](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/legs.py): `microservices/decision-maker/src/decision_maker/legs.py`
- [Assessment explanation](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/decision-maker/src/decision_maker/explain.py): `microservices/decision-maker/src/decision_maker/explain.py`

### External integrations

- [Robinhood read-only link](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/broker.py): `microservices/research-api/src/research_api/broker.py`
- [Notifications and digest](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/research-api/src/research_api/notifications.py): `microservices/research-api/src/research_api/notifications.py`

### Market diagnostics

- [Volatility surface](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/volatility-surface-builder/src/vol_surface_builder/pipeline.py): `microservices/volatility-surface-builder/src/vol_surface_builder/pipeline.py`
- [Option data feed](https://github.com/hemanthsrp/hackmidwest26/blob/main/microservices/volatility-surface-builder/src/vol_surface_builder/data_feed.py): `microservices/volatility-surface-builder/src/vol_surface_builder/data_feed.py`

### Other components

- **Research user**
- **Robinhood**
- **Market and news providers**

## Connections

- Research user → Research screens: views research (evidence: `README.md`)
- Research screens → Research endpoint: requests research
- Research endpoint → Research API: forwards requests
- Research user → Account and app APIs: uses account features (evidence: `README.md`)
- Account and app APIs → Frontend database: uses
- Research API → Assessment orchestration: routes assessments (evidence: `microservices/research-api/src/research_api/app.py`)
- Research API → Research and account routes: registers routes (evidence: `microservices/research-api/src/research_api/app.py`)
- Research API → Research user records: uses persistence (evidence: `microservices/research-api/src/research_api/app.py`)
- Research and account routes → Research user records: reads and writes (evidence: `microservices/research-api/src/research_api/v1.py`)
- Research and account routes → Robinhood read-only link: handles broker flow (evidence: `microservices/research-api/src/research_api/v1.py`)
- Research and account routes → Notifications and digest: uses notifications (evidence: `microservices/research-api/src/research_api/v1.py`)
- Assessment orchestration → Decision workflow: invokes assessment (evidence: `microservices/research-api/src/research_api/assessment.py`)
- Source ingestion → Evidence sources: fetches evidence (evidence: `microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py`)
- Source ingestion → Evidence processing: processes records (evidence: `microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py`)
- Source ingestion → Evidence store: saves records (evidence: `microservices/scraper-analysis/src/scraper_analysis/pipeline/ingest.py`)
- Evidence sources → Market and news providers: retrieves data
- Evidence retrieval → Evidence store: reads evidence (evidence: `microservices/decision-maker/src/decision_maker/retrieval.py`)
- Decision workflow → Evidence retrieval: loads records (evidence: `microservices/decision-maker/src/decision_maker/service.py`)
- Decision workflow → Evidence readings: builds readings (evidence: `microservices/decision-maker/src/decision_maker/service.py`)
- Decision workflow → Assessment explanation: creates explanation (evidence: `microservices/decision-maker/src/decision_maker/service.py`)
- Robinhood read-only link → Robinhood: uses OAuth
- Volatility surface → Option data feed: retrieves option data (evidence: `microservices/volatility-surface-builder/src/vol_surface_builder/pipeline.py`)
- Option data feed → Market and news providers: queries market data