# candiedoutlaw763/stop_loss architecture

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

- Interactive diagram: https://gitdiagram.com/candiedoutlaw763/stop_loss
- Repository: https://github.com/candiedoutlaw763/stop_loss

## Overview

StopLoss is a financial intelligence terminal: a user submits a single-asset or portfolio question, the backend gathers market and event evidence, produces risk and hedge analysis, audits claims, and streams results to the terminal UI. The separate ingestion engine builds normalized, themed, deduplicated evidence and vector indexes. README statements support the major product flows; source excerpts and the SOURCE INDEX add implementation links. Some agent and ingestion details are documented but their implementation files were not sampled.

Main entry points: [`backend/src/stop_loss/ingestion/runner.py`](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/ingestion/runner.py) (Ingestion lanes), [`backend/src/stop_loss/agents/service.py`](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/service.py) (Analysis service), [`frontend/lib/chat/useChatStream.ts`](https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/lib/chat/useChatStream.ts) (Chat stream), [`backend/src/stop_loss/analytics/yfinance_client.py`](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/yfinance_client.py) (Yahoo market client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal interface"]
  node_terminal["Terminal UI<br/>[page.tsx]"]
  node_chatstream["Chat stream<br/>[useChatStream.ts]"]
  node_presentation["Analysis presentation"]
end

subgraph group_service["API and orchestration"]
  node_api["FastAPI<br/>[app.py]"]
  node_analysis_service["Analysis service<br/>[service.py]"]
  node_run_events["Typed run events<br/>[run_events.py]"]
end

subgraph group_analysis["Risk analysis"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_coordinator["Query coordinator<br/>[nodes.py]"]
  node_parallel_agents["Market, news, impact, analogs<br/>[nodes.py]"]
  node_quant["Quant risk<br/>[risk.py]"]
  node_hedging["Hedge strategy<br/>[portfolio_nodes.py]"]
  node_audit["Evidence audit<br/>[audit.py]"]
  node_analytics["Market analytics"]
  node_market_client["Yahoo market client<br/>[yfinance_client.py]"]
end

subgraph group_ingestion["Ingestion and retrieval"]
  node_ingest_runner["Ingestion lanes<br/>[runner.py]"]
  node_connectors["Source connectors"]
  node_retrieval["Analog retrieval<br/>[search.py]"]
end

subgraph group_foundation["Data foundations"]
  node_normalization["Typed records and themes<br/>[schemas.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_vectorstore[("Vector index<br/>[pinecone.py]")]
  node_evidence_log[("Evidence log<br/>[evidence.py]")]
  node_document_store[("Dedupe store<br/>[storage.py]")]
  node_resilience["Source resilience<br/>[resilience.py]"]
  node_models["Analysis models<br/>[models.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

node_user(("Investor"))

node_user -->|"asks"| node_terminal
node_terminal -->|"submits query"| node_chatstream
node_chatstream -->|"starts run"| node_api
node_api -->|"starts analysis"| node_analysis_service
node_analysis_service -->|"builds and invokes"| node_graph
node_graph -->|"routes query"| node_coordinator
node_coordinator -->|"dispatches"| node_parallel_agents
node_parallel_agents -->|"provides analysis"| node_quant
node_quant -->|"informs strategy"| node_hedging
node_hedging -->|"submits claims"| node_audit
node_analysis_service -->|"streams lifecycle"| node_run_events
node_api -->|"streams SSE"| node_chatstream
node_chatstream -->|"updates progress"| node_presentation
node_analytics -->|"fetches market data"| node_market_client
node_market_client -->|"guards requests"| node_resilience
node_market_client -->|"returns typed data"| node_models
node_ingest_runner -->|"fetches sources"| node_connectors
node_ingest_runner -->|"normalizes and tags"| node_normalization
node_ingest_runner -->|"embeds records"| node_embeddings
node_ingest_runner -->|"indexes records"| node_vectorstore
node_ingest_runner -->|"records provenance"| node_evidence_log
node_ingest_runner -->|"deduplicates records"| node_document_store
node_retrieval -->|"embeds queries"| node_embeddings
node_retrieval -->|"searches index"| node_vectorstore
node_analysis_service -->|"retrieves analogs"| node_retrieval
node_settings -.->|"configures client"| node_market_client

click node_terminal "https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/app/chat/page.tsx"
click node_chatstream "https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/lib/chat/useChatStream.ts"
click node_presentation "https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/components/chat/OrchestrationPanel.tsx"
click node_api "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/api/app.py"
click node_analysis_service "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/service.py"
click node_graph "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/graph.py"
click node_coordinator "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/nodes.py"
click node_parallel_agents "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/nodes.py"
click node_quant "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/risk.py"
click node_hedging "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/portfolio_nodes.py"
click node_audit "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/audit.py"
click node_run_events "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/run_events.py"
click node_analytics "https://github.com/candiedoutlaw763/stop_loss/tree/main/backend/src/stop_loss/analytics"
click node_ingest_runner "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/ingestion/runner.py"
click node_connectors "https://github.com/candiedoutlaw763/stop_loss/tree/main/backend/src/fin_terminal/connectors"
click node_normalization "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/schemas.py"
click node_embeddings "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/embeddings.py"
click node_vectorstore "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/vectorstore/pinecone.py"
click node_evidence_log "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/evidence.py"
click node_document_store "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/storage.py"
click node_retrieval "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/retrieval/search.py"
click node_market_client "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/yfinance_client.py"
click node_resilience "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/resilience.py"
click node_models "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/models.py"
click node_settings "https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/settings.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_terminal,node_chatstream,node_presentation toneBlue
class node_api,node_analysis_service,node_run_events toneAmber
class node_graph,node_coordinator,node_parallel_agents,node_quant,node_hedging,node_audit,node_analytics,node_market_client toneMint
class node_ingest_runner,node_connectors,node_retrieval toneRose
class node_normalization,node_embeddings,node_vectorstore,node_evidence_log,node_document_store,node_resilience,node_models,node_settings,node_user toneIndigo
```

## Components

### Terminal interface

- [Terminal UI](https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [Chat stream](https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/lib/chat/useChatStream.ts): `frontend/lib/chat/useChatStream.ts`
- [Analysis presentation](https://github.com/candiedoutlaw763/stop_loss/blob/main/frontend/components/chat/OrchestrationPanel.tsx): `frontend/components/chat/OrchestrationPanel.tsx`

### API and orchestration

- [FastAPI](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/api/app.py): `backend/src/stop_loss/api/app.py`
- [Analysis service](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/service.py): `backend/src/stop_loss/agents/service.py`
- [Typed run events](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/run_events.py): `backend/src/stop_loss/agents/run_events.py`

### Risk analysis

- [Agent graph](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/graph.py): `backend/src/stop_loss/agents/graph.py`
- [Query coordinator](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/nodes.py): `backend/src/stop_loss/agents/nodes.py`
- [Market, news, impact, analogs](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/nodes.py): `backend/src/stop_loss/agents/nodes.py`
- [Quant risk](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/risk.py): `backend/src/stop_loss/analytics/risk.py`
- [Hedge strategy](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/portfolio_nodes.py): `backend/src/stop_loss/agents/portfolio_nodes.py`
- [Evidence audit](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/agents/audit.py): `backend/src/stop_loss/agents/audit.py`
- [Market analytics](https://github.com/candiedoutlaw763/stop_loss/tree/main/backend/src/stop_loss/analytics): `backend/src/stop_loss/analytics`
- [Yahoo market client](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/yfinance_client.py): `backend/src/stop_loss/analytics/yfinance_client.py`

### Ingestion and retrieval

- [Ingestion lanes](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/ingestion/runner.py): `backend/src/stop_loss/ingestion/runner.py`
- [Source connectors](https://github.com/candiedoutlaw763/stop_loss/tree/main/backend/src/fin_terminal/connectors): `backend/src/fin_terminal/connectors`
- [Analog retrieval](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/retrieval/search.py): `backend/src/stop_loss/retrieval/search.py`

### Data foundations

- [Typed records and themes](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/schemas.py): `backend/src/fin_terminal/schemas.py`
- [Embeddings](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/embeddings.py): `backend/src/fin_terminal/embeddings.py`
- [Vector index](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/vectorstore/pinecone.py): `backend/src/fin_terminal/vectorstore/pinecone.py`
- [Evidence log](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/evidence.py): `backend/src/fin_terminal/evidence.py`
- [Dedupe store](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/storage.py): `backend/src/fin_terminal/storage.py`
- [Source resilience](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/fin_terminal/resilience.py): `backend/src/fin_terminal/resilience.py`
- [Analysis models](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/analytics/models.py): `backend/src/stop_loss/analytics/models.py`
- [Runtime settings](https://github.com/candiedoutlaw763/stop_loss/blob/main/backend/src/stop_loss/settings.py): `backend/src/stop_loss/settings.py`

### Other components

- **Investor**

## Connections

- Investor → Terminal UI: asks
- Terminal UI → Chat stream: submits query
- Chat stream → FastAPI: starts run (evidence: `backend/src/stop_loss/api/app.py`)
- FastAPI → Analysis service: starts analysis (evidence: `backend/src/stop_loss/api/app.py`)
- Analysis service → Agent graph: builds and invokes (evidence: `backend/src/stop_loss/agents/service.py`)
- Agent graph → Query coordinator: routes query
- Query coordinator → Market, news, impact, analogs: dispatches
- Market, news, impact, analogs → Quant risk: provides analysis
- Quant risk → Hedge strategy: informs strategy
- Hedge strategy → Evidence audit: submits claims
- Analysis service → Typed run events: streams lifecycle (evidence: `backend/src/stop_loss/agents/service.py`)
- FastAPI → Chat stream: streams SSE
- Chat stream → Analysis presentation: updates progress
- Market analytics → Yahoo market client: fetches market data (evidence: `backend/src/stop_loss/analytics/yahoo.py`)
- Yahoo market client → Source resilience: guards requests (evidence: `backend/src/stop_loss/analytics/yfinance_client.py`)
- Yahoo market client → Analysis models: returns typed data (evidence: `backend/src/stop_loss/analytics/yfinance_client.py`)
- Ingestion lanes → Source connectors: fetches sources
- Ingestion lanes → Typed records and themes: normalizes and tags
- Ingestion lanes → Embeddings: embeds records
- Ingestion lanes → Vector index: indexes records
- Ingestion lanes → Evidence log: records provenance
- Ingestion lanes → Dedupe store: deduplicates records
- Analog retrieval → Embeddings: embeds queries (evidence: `backend/src/stop_loss/retrieval/search.py`)
- Analog retrieval → Vector index: searches index (evidence: `backend/src/stop_loss/retrieval/search.py`)
- Analysis service → Analog retrieval: retrieves analogs (evidence: `backend/src/stop_loss/agents/service.py`)
- Runtime settings → Yahoo market client: configures client
