# dhyani2206/sec-regulatory-rag architecture

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

- Interactive diagram: https://gitdiagram.com/dhyani2206/sec-regulatory-rag
- Repository: https://github.com/dhyani2206/sec-regulatory-rag

## Overview

SEC Regulatory RAG is an evidence-first research assistant: users select a filing scope, ask a regulatory question, and receive a structured, cited answer or a grounded refusal. The Streamlit app is a thin client; FastAPI delegates query work to the RAG engine, which routes questions, retrieves filing and CFR evidence, ranks it, and applies an evidence guard before answering. Separate ingestion and indexing modules prepare the two corpora. The README documents comparison and compliance-summary capabilities; their runtime wiring is not established by the sampled code, so those branches are shown without invented connections.

Main entry points: [`src/rag/answer_engine.py`](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/answer_engine.py) (Answer engine), [`frontend/frontend/api_client.py`](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/frontend/api_client.py) (API client), [`app/services/query_service.py`](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/services/query_service.py) (Query service), [`frontend/app.py`](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/app.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interface and API"]
  node_frontend["Streamlit app<br/>[app.py]"]
  node_api_client["API client<br/>[api_client.py]"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_query_endpoint["Query endpoint<br/>[query.py]"]
  node_options_endpoint["Scope options<br/>[options.py]"]
end

subgraph group_answering["Grounded query workflow"]
  node_query_service["Query service<br/>[query_service.py]"]
  node_answer_engine["Answer engine<br/>[answer_engine.py]"]
  node_query_router["Filing query router<br/>[query_router.py]"]
  node_rules_router["Rules router<br/>[rules_router.py]"]
  node_filing_retrieval["Filing retrieval"]
  node_section_retrieval["Section retrieval"]
  node_rule_retrieval["Rule retrieval<br/>[retrieve_rules.py]"]
  node_evidence_ranker["Evidence ranking<br/>[evidence_ranker.py]"]
  node_evidence_pack["Evidence guard<br/>[evidence_pack.py]"]
end

subgraph group_corpora["Regulatory corpora"]
  node_filing_extract["Filing extraction<br/>[batch_extractor.py]"]
  node_filing_index["Filing index builder<br/>[embeddings.py]"]
  node_rule_ingest["CFR ingestion"]
  node_rule_index["Rules index builder"]
  node_filing_store[("Filing vector index")]
  node_rules_store[("Rules vector index")]
end

subgraph group_analysis["Research extensions"]
  node_diff_engine["Filing comparison<br/>[diff_engine.py]"]
  node_compliance_summary["Compliance summary"]
end

node_user(("Researcher"))
node_ecfr["eCFR"]
node_llm["Language model"]

node_user -->|"asks question"| node_frontend
node_frontend -->|"requests options and answers"| node_api_client
node_api_client -->|"GET options"| node_options_endpoint
node_api_client -->|"POST query"| node_query_endpoint
node_query_endpoint -->|"calls"| node_query_service
node_query_service -->|"processes query"| node_answer_engine
node_answer_engine -->|"routes filing query"| node_query_router
node_answer_engine -->|"routes rule query"| node_rules_router
node_answer_engine -->|"retrieves filings"| node_filing_retrieval
node_answer_engine -->|"retrieves sections"| node_section_retrieval
node_answer_engine -->|"retrieves rules"| node_rule_retrieval
node_answer_engine -->|"ranks evidence"| node_evidence_ranker
node_answer_engine -->|"checks evidence"| node_evidence_pack
node_query_service -->|"returns structured response"| node_frontend
node_options_endpoint -.->|"reads filing metadata"| node_filing_extract
node_filing_extract -->|"provides extracted sections"| node_filing_index
node_filing_index -->|"builds index"| node_filing_store
node_rule_ingest -->|"fetches regulations"| node_ecfr
node_rule_ingest -->|"provides rule text"| node_rule_index
node_rule_index -->|"builds index"| node_rules_store
node_filing_retrieval -->|"searches"| node_filing_store
node_section_retrieval -->|"searches"| node_filing_store
node_rule_retrieval -->|"searches"| node_rules_store
node_answer_engine -.->|"generates grounded answer"| node_llm

click node_frontend "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/app.py"
click node_api_client "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/frontend/api_client.py"
click node_fastapi "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/main.py"
click node_query_endpoint "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/api/v1/endpoints/query.py"
click node_options_endpoint "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/api/v1/endpoints/options.py"
click node_query_service "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/services/query_service.py"
click node_answer_engine "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/answer_engine.py"
click node_query_router "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/query_router.py"
click node_rules_router "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/rules_router.py"
click node_filing_retrieval "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_filings.py"
click node_section_retrieval "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_filing_sections.py"
click node_rule_retrieval "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_rules.py"
click node_evidence_ranker "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/evidence_ranker.py"
click node_evidence_pack "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/evidence_pack.py"
click node_filing_extract "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/extraction/batch_extractor.py"
click node_filing_index "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/embeddings.py"
click node_rule_ingest "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rules/ingest_ecfr_rules.py"
click node_rule_index "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rules/build_rules_index.py"
click node_diff_engine "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/diff_engine.py"
click node_compliance_summary "https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/compliance_summary.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_frontend,node_api_client,node_fastapi,node_query_endpoint,node_options_endpoint toneBlue
class node_query_service,node_answer_engine,node_query_router,node_rules_router,node_filing_retrieval,node_section_retrieval,node_rule_retrieval,node_evidence_ranker,node_evidence_pack toneAmber
class node_filing_extract,node_filing_index,node_rule_ingest,node_rule_index,node_filing_store,node_rules_store toneMint
class node_diff_engine,node_compliance_summary toneRose
class node_user,node_ecfr,node_llm toneIndigo
```

## Components

### User interface and API

- [Streamlit app](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/app.py): `frontend/app.py`
- [API client](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/frontend/frontend/api_client.py): `frontend/frontend/api_client.py`
- [FastAPI app](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/main.py): `app/main.py`
- [Query endpoint](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/api/v1/endpoints/query.py): `app/api/v1/endpoints/query.py`
- [Scope options](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/api/v1/endpoints/options.py): `app/api/v1/endpoints/options.py`

### Grounded query workflow

- [Query service](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/app/services/query_service.py): `app/services/query_service.py`
- [Answer engine](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/answer_engine.py): `src/rag/answer_engine.py`
- [Filing query router](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/query_router.py): `src/rag/query_router.py`
- [Rules router](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/rules_router.py): `src/rag/rules_router.py`
- [Filing retrieval](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_filings.py): `src/rag/retrieve_filings.py`
- [Section retrieval](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_filing_sections.py): `src/rag/retrieve_filing_sections.py`
- [Rule retrieval](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/retrieve_rules.py): `src/rag/retrieve_rules.py`
- [Evidence ranking](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/evidence_ranker.py): `src/rag/evidence_ranker.py`
- [Evidence guard](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/evidence_pack.py): `src/rag/evidence_pack.py`

### Regulatory corpora

- [Filing extraction](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/extraction/batch_extractor.py): `src/extraction/batch_extractor.py`
- [Filing index builder](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/embeddings.py): `src/rag/embeddings.py`
- [CFR ingestion](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rules/ingest_ecfr_rules.py): `src/rules/ingest_ecfr_rules.py`
- [Rules index builder](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rules/build_rules_index.py): `src/rules/build_rules_index.py`
- **Filing vector index**
- **Rules vector index**

### Research extensions

- [Filing comparison](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/diff_engine.py): `src/rag/diff_engine.py`
- [Compliance summary](https://github.com/dhyani2206/sec-regulatory-rag/blob/main/src/rag/compliance_summary.py): `src/rag/compliance_summary.py`

### Other components

- **Researcher**
- **eCFR**
- **Language model**

## Connections

- Researcher → Streamlit app: asks question
- Streamlit app → API client: requests options and answers
- API client → Scope options: GET options
- API client → Query endpoint: POST query
- Query endpoint → Query service: calls
- Query service → Answer engine: processes query
- Answer engine → Filing query router: routes filing query
- Answer engine → Rules router: routes rule query
- Answer engine → Filing retrieval: retrieves filings
- Answer engine → Section retrieval: retrieves sections
- Answer engine → Rule retrieval: retrieves rules
- Answer engine → Evidence ranking: ranks evidence
- Answer engine → Evidence guard: checks evidence
- Query service → Streamlit app: returns structured response
- Scope options → Filing extraction: reads filing metadata
- Filing extraction → Filing index builder: provides extracted sections
- Filing index builder → Filing vector index: builds index
- CFR ingestion → eCFR: fetches regulations
- CFR ingestion → Rules index builder: provides rule text
- Rules index builder → Rules vector index: builds index
- Filing retrieval → Filing vector index: searches
- Section retrieval → Filing vector index: searches
- Rule retrieval → Rules vector index: searches
- Answer engine → Language model: generates grounded answer