# choeyunbeom/finscope architecture

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

- Interactive diagram: https://gitdiagram.com/choeyunbeom/finscope
- Repository: https://github.com/choeyunbeom/finscope

## Overview

finscope ingests public-company filings, chunks and indexes them, then answers a user query through a LangGraph retrieval, analysis, and citation-review workflow. Insufficiently supported analyses can be rewritten and retried. The API coordinates ingestion and graph execution; the README also documents a Streamlit UI and optional Langfuse tracing. The graph follows the sampled API, ingestion, retrieval, and orchestration code plus documented capabilities; unsampled implementations are represented only at their supported paths.

Main entry points: [`src/ingestion/ingest.py`](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/ingest.py) (Ingestion coordinator), [`src/agents/graph.py`](https://github.com/choeyunbeom/finscope/blob/main/src/agents/graph.py) (Workflow graph), [`src/api/main.py`](https://github.com/choeyunbeom/finscope/blob/main/src/api/main.py) (Analysis API), [`src/retrieval/hybrid_retriever.py`](https://github.com/choeyunbeom/finscope/blob/main/src/retrieval/hybrid_retriever.py) (Hybrid search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Filing ingestion"]
  node_ingest["Ingestion coordinator<br/>[ingest.py]"]
  node_sec["SEC EDGAR loader<br/>[sec_edgar.py]"]
  node_companies["Companies House loader<br/>[companies_house.py]"]
  node_documents["Document model<br/>[base.py]"]
  node_chunker["Filing chunker<br/>[chunker.py]"]
  node_indexer["Filing indexer<br/>[indexer.py]"]
end

subgraph group_retrieval["Search and retrieval"]
  node_chroma[("ChromaDB index")]
  node_hybrid["Hybrid search"]
end

subgraph group_agents["Analysis agents"]
  node_agent_retriever["Retriever agent<br/>[retriever.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_analyzer["Risk growth competitor<br/>[analyzer.py]"]
  node_critic["Citation critic<br/>[critic.py]"]
  node_rewriter["Query rewriter<br/>[query_rewriter.py]"]
  node_schemas["Agent output schemas<br/>[schemas.py]"]
end

subgraph group_interface["User interface"]
  node_api["Analysis API<br/>[main.py]"]
  node_ui["Streamlit UI<br/>[app.py]"]
end

node_user(("Analyst"))
node_ollama["Ollama embeddings"]
node_langfuse["Langfuse tracing<br/>[langfuse_config.py]"]
node_sec_service["SEC EDGAR"]
node_ch_service["Companies House"]
node_groq["Groq LLM"]
node_report["Cited analysis"]

node_user -->|"submits query"| node_api
node_api -->|"starts ingestion"| node_ingest
node_api -->|"invokes analysis"| node_graph
node_api -->|"traces analysis"| node_langfuse
node_api -->|"returns report"| node_report
node_ingest -->|"loads SEC filings"| node_sec
node_ingest -->|"loads accounts"| node_companies
node_sec -->|"fetches filings"| node_sec_service
node_companies -->|"fetches accounts"| node_ch_service
node_ingest -->|"chunks documents"| node_chunker
node_ingest -->|"indexes chunks"| node_indexer
node_ingest -->|"uses document model"| node_documents
node_indexer -->|"writes chunks"| node_chroma
node_graph -->|"dispatches retrieval"| node_agent_retriever
node_graph -->|"dispatches analysis"| node_analyzer
node_graph -->|"dispatches review"| node_critic
node_graph -->|"dispatches retry"| node_rewriter
node_agent_retriever -->|"loads chunks"| node_chroma
node_agent_retriever -->|"searches query"| node_hybrid
node_hybrid -->|"queries vectors"| node_chroma
node_hybrid -->|"requests embeddings"| node_ollama
node_analyzer -->|"validates output"| node_schemas
node_critic -->|"validates verdict"| node_schemas
node_rewriter -->|"validates query"| node_schemas
node_critic -->|"requests review"| node_groq
node_rewriter -->|"rewrites query"| node_groq
node_graph -->|"completes workflow"| node_report
node_ui -.->|"uses analysis endpoint"| node_api

click node_api "https://github.com/choeyunbeom/finscope/blob/main/src/api/main.py"
click node_ui "https://github.com/choeyunbeom/finscope/blob/main/ui/app.py"
click node_ingest "https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/ingest.py"
click node_sec "https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/sec_edgar.py"
click node_companies "https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/companies_house.py"
click node_documents "https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/base.py"
click node_chunker "https://github.com/choeyunbeom/finscope/blob/main/src/retrieval/chunker.py"
click node_indexer "https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/indexer.py"
click node_agent_retriever "https://github.com/choeyunbeom/finscope/blob/main/src/agents/retriever.py"
click node_hybrid "https://github.com/choeyunbeom/finscope/blob/main/src/retrieval/hybrid_retriever.py"
click node_graph "https://github.com/choeyunbeom/finscope/blob/main/src/agents/graph.py"
click node_analyzer "https://github.com/choeyunbeom/finscope/blob/main/src/agents/analyzer.py"
click node_critic "https://github.com/choeyunbeom/finscope/blob/main/src/agents/critic.py"
click node_rewriter "https://github.com/choeyunbeom/finscope/blob/main/src/agents/query_rewriter.py"
click node_schemas "https://github.com/choeyunbeom/finscope/blob/main/src/agents/schemas.py"
click node_langfuse "https://github.com/choeyunbeom/finscope/blob/main/monitoring/langfuse_config.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_ingest,node_sec,node_companies,node_documents,node_chunker,node_indexer toneBlue
class node_chroma,node_hybrid toneAmber
class node_agent_retriever,node_graph,node_analyzer,node_critic,node_rewriter,node_schemas toneMint
class node_api,node_ui toneRose
class node_user,node_ollama,node_sec_service,node_ch_service,node_groq,node_report toneIndigo
class node_langfuse toneTeal
```

## Components

### Filing ingestion

- [Ingestion coordinator](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/ingest.py): `src/ingestion/ingest.py`
- [SEC EDGAR loader](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/sec_edgar.py): `src/ingestion/sec_edgar.py`
- [Companies House loader](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/companies_house.py): `src/ingestion/companies_house.py`
- [Document model](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/base.py): `src/ingestion/base.py`
- [Filing chunker](https://github.com/choeyunbeom/finscope/blob/main/src/retrieval/chunker.py): `src/retrieval/chunker.py`
- [Filing indexer](https://github.com/choeyunbeom/finscope/blob/main/src/ingestion/indexer.py): `src/ingestion/indexer.py`

### Search and retrieval

- **ChromaDB index**
- [Hybrid search](https://github.com/choeyunbeom/finscope/blob/main/src/retrieval/hybrid_retriever.py): `src/retrieval/hybrid_retriever.py`

### Analysis agents

- [Retriever agent](https://github.com/choeyunbeom/finscope/blob/main/src/agents/retriever.py): `src/agents/retriever.py`
- [Workflow graph](https://github.com/choeyunbeom/finscope/blob/main/src/agents/graph.py): `src/agents/graph.py`
- [Risk growth competitor](https://github.com/choeyunbeom/finscope/blob/main/src/agents/analyzer.py): `src/agents/analyzer.py`
- [Citation critic](https://github.com/choeyunbeom/finscope/blob/main/src/agents/critic.py): `src/agents/critic.py`
- [Query rewriter](https://github.com/choeyunbeom/finscope/blob/main/src/agents/query_rewriter.py): `src/agents/query_rewriter.py`
- [Agent output schemas](https://github.com/choeyunbeom/finscope/blob/main/src/agents/schemas.py): `src/agents/schemas.py`

### User interface

- [Analysis API](https://github.com/choeyunbeom/finscope/blob/main/src/api/main.py): `src/api/main.py`
- [Streamlit UI](https://github.com/choeyunbeom/finscope/blob/main/ui/app.py): `ui/app.py`

### Other components

- **Analyst**
- **Ollama embeddings**
- [Langfuse tracing](https://github.com/choeyunbeom/finscope/blob/main/monitoring/langfuse_config.py): `monitoring/langfuse_config.py`
- **SEC EDGAR**
- **Companies House**
- **Groq LLM**
- **Cited analysis**

## Connections

- Analyst → Analysis API: submits query (evidence: `README.md`)
- Analysis API → Ingestion coordinator: starts ingestion (evidence: `src/api/main.py`)
- Analysis API → Workflow graph: invokes analysis (evidence: `src/api/main.py`)
- Analysis API → Langfuse tracing: traces analysis (evidence: `src/api/main.py`)
- Analysis API → Cited analysis: returns report (evidence: `src/api/main.py`)
- Ingestion coordinator → SEC EDGAR loader: loads SEC filings (evidence: `src/ingestion/ingest.py`)
- Ingestion coordinator → Companies House loader: loads accounts (evidence: `src/ingestion/ingest.py`)
- SEC EDGAR loader → SEC EDGAR: fetches filings (evidence: `README.md`)
- Companies House loader → Companies House: fetches accounts (evidence: `README.md`)
- Ingestion coordinator → Filing chunker: chunks documents (evidence: `src/ingestion/ingest.py`)
- Ingestion coordinator → Filing indexer: indexes chunks (evidence: `src/ingestion/ingest.py`)
- Ingestion coordinator → Document model: uses document model (evidence: `src/ingestion/ingest.py`)
- Filing indexer → ChromaDB index: writes chunks (evidence: `src/ingestion/indexer.py`)
- Workflow graph → Retriever agent: dispatches retrieval (evidence: `src/agents/graph.py`)
- Workflow graph → Risk growth competitor: dispatches analysis (evidence: `src/agents/graph.py`)
- Workflow graph → Citation critic: dispatches review (evidence: `src/agents/graph.py`)
- Workflow graph → Query rewriter: dispatches retry (evidence: `src/agents/graph.py`)
- Retriever agent → ChromaDB index: loads chunks (evidence: `src/agents/retriever.py`)
- Retriever agent → Hybrid search: searches query (evidence: `src/agents/retriever.py`)
- Hybrid search → ChromaDB index: queries vectors (evidence: `src/retrieval/hybrid_retriever.py`)
- Hybrid search → Ollama embeddings: requests embeddings (evidence: `src/retrieval/hybrid_retriever.py`)
- Risk growth competitor → Agent output schemas: validates output (evidence: `src/agents/analyzer.py`)
- Citation critic → Agent output schemas: validates verdict (evidence: `src/agents/critic.py`)
- Query rewriter → Agent output schemas: validates query (evidence: `src/agents/query_rewriter.py`)
- Citation critic → Groq LLM: requests review (evidence: `src/agents/critic.py`)
- Query rewriter → Groq LLM: rewrites query (evidence: `src/agents/query_rewriter.py`)
- Workflow graph → Cited analysis: completes workflow (evidence: `README.md`)
- Streamlit UI → Analysis API: uses analysis endpoint