# raghuvarma-gilth/cycloneiq architecture

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

## Overview

IP-SAKTI Sahayak is a multilingual, source-cited regulatory and IP research platform. A user asks a question in the Streamlit research UI; the API runs the RAG pipeline, which detects language, classifies intent and product, extracts entities, routes the query, retrieves and filters evidence, then generates and verifies a cited answer. The repository also documents document ingestion, temporal/version-aware research, knowledge-graph context, and evaluation. The graph follows the README and sampled orchestration/API excerpts; unsampled subsystem wiring is shown only where documented, and ingestion detail is limited to the available tree.

Main entry points: [`backend/rag/pipeline.py`](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/pipeline.py) (RAG pipeline), [`backend/rag/retriever.py`](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/retriever.py) (Hybrid retriever), [`backend/api/app.py`](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/api/app.py) (FastAPI API), [`frontend/app.py`](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/frontend/app.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_research_pages["Research pages"]
  node_fastapi["FastAPI API<br/>[app.py]"]
end

subgraph group_intelligence["Query intelligence"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_language["Language detection"]
  node_query_classifiers["Query classifiers"]
  node_legal_ner["Legal NER<br/>[legal_ner.py]"]
  node_router["Domain router<br/>[query_router.py]"]
end

subgraph group_evidence["Evidence retrieval"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_dense["Dense search<br/>[dense_retriever.py]"]
  node_bm25["BM25 search<br/>[bm25_retriever.py]"]
  node_fusion["Fusion and reranking<br/>[rrf.py]"]
  node_evidence_filter["Evidence filtering<br/>[evidence_filter.py]"]
  node_vector_store[("Vector index<br/>[dense_retriever.py]")]
  node_temporal["Temporal retrieval"]
  node_knowledge_graph["Knowledge graph<br/>[graph.py]"]
end

subgraph group_answering["Grounded answering"]
  node_prompt_builder["Prompt builder<br/>[prompt_builder.py]"]
  node_llm_provider["LLM provider<br/>[provider.py]"]
  node_citation_verifier["Citation verification"]
end

subgraph group_corpus["Corpus and evaluation"]
  node_ingestion["Document ingestion"]
  node_evaluation["Evaluation metrics"]
end

node_researcher(("Researcher"))
node_llm_service{{"LLM service"}}

node_researcher -->|"asks"| node_streamlit
node_streamlit -->|"opens"| node_research_pages
node_research_pages -->|"queries"| node_pipeline
node_researcher -.->|"submits query"| node_fastapi
node_fastapi -->|"runs"| node_pipeline
node_pipeline -->|"detects language"| node_language
node_pipeline -->|"classifies query"| node_query_classifiers
node_pipeline -->|"extracts entities"| node_legal_ner
node_pipeline -->|"routes query"| node_router
node_pipeline -->|"retrieves evidence"| node_retriever
node_retriever -->|"searches semantically"| node_dense
node_retriever -->|"searches keywords"| node_bm25
node_retriever -->|"fuses and reranks"| node_fusion
node_retriever -->|"filters evidence"| node_evidence_filter
node_dense -->|"reads index"| node_vector_store
node_pipeline -->|"filters by time"| node_temporal
node_pipeline -->|"adds graph context"| node_knowledge_graph
node_pipeline -->|"builds prompt"| node_prompt_builder
node_pipeline -->|"requests generation"| node_llm_provider
node_llm_provider -->|"generates answer"| node_llm_service
node_pipeline -->|"verifies citations"| node_citation_verifier
node_citation_verifier -->|"returns verified result"| node_fastapi
node_ingestion -.->|"builds index"| node_vector_store
node_pipeline -.->|"measured by"| node_evaluation

click node_streamlit "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/frontend/app.py"
click node_research_pages "https://github.com/raghuvarma-gilth/cycloneiq/tree/main/frontend/pages"
click node_fastapi "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/api/app.py"
click node_pipeline "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/pipeline.py"
click node_language "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/ml/language_detector.py"
click node_query_classifiers "https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/ml"
click node_legal_ner "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/ml/legal_ner.py"
click node_router "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/query_router.py"
click node_retriever "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/retriever.py"
click node_dense "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/dense_retriever.py"
click node_bm25 "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/bm25_retriever.py"
click node_fusion "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/rrf.py"
click node_evidence_filter "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/evidence_filter.py"
click node_vector_store "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/dense_retriever.py"
click node_temporal "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/temporal/temporal_retrieval.py"
click node_knowledge_graph "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/knowledge_graph/graph.py"
click node_prompt_builder "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/prompt_builder.py"
click node_llm_provider "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/generation/provider.py"
click node_citation_verifier "https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/generation/citation_verifier.py"
click node_ingestion "https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/ingestion"
click node_evaluation "https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/evaluation"

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_streamlit,node_research_pages,node_fastapi toneBlue
class node_pipeline,node_language,node_query_classifiers,node_legal_ner,node_router toneAmber
class node_retriever,node_dense,node_bm25,node_fusion,node_evidence_filter,node_vector_store,node_temporal,node_knowledge_graph toneMint
class node_prompt_builder,node_llm_provider,node_citation_verifier toneRose
class node_ingestion,node_evaluation,node_researcher,node_llm_service toneIndigo
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/frontend/app.py): `frontend/app.py`
- [Research pages](https://github.com/raghuvarma-gilth/cycloneiq/tree/main/frontend/pages): `frontend/pages`
- [FastAPI API](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/api/app.py): `backend/api/app.py`

### Query intelligence

- [RAG pipeline](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/pipeline.py): `backend/rag/pipeline.py`
- [Language detection](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/ml/language_detector.py): `backend/ml/language_detector.py`
- [Query classifiers](https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/ml): `backend/ml`
- [Legal NER](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/ml/legal_ner.py): `backend/ml/legal_ner.py`
- [Domain router](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/query_router.py): `backend/rag/query_router.py`

### Evidence retrieval

- [Hybrid retriever](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Dense search](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/dense_retriever.py): `backend/retrieval/dense_retriever.py`
- [BM25 search](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/bm25_retriever.py): `backend/retrieval/bm25_retriever.py`
- [Fusion and reranking](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/rrf.py): `backend/retrieval/rrf.py`
- [Evidence filtering](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/evidence_filter.py): `backend/retrieval/evidence_filter.py`
- [Vector index](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/retrieval/dense_retriever.py): `backend/retrieval/dense_retriever.py`
- [Temporal retrieval](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/temporal/temporal_retrieval.py): `backend/temporal/temporal_retrieval.py`
- [Knowledge graph](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/knowledge_graph/graph.py): `backend/knowledge_graph/graph.py`

### Grounded answering

- [Prompt builder](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/rag/prompt_builder.py): `backend/rag/prompt_builder.py`
- [LLM provider](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/generation/provider.py): `backend/generation/provider.py`
- [Citation verification](https://github.com/raghuvarma-gilth/cycloneiq/blob/main/backend/generation/citation_verifier.py): `backend/generation/citation_verifier.py`

### Corpus and evaluation

- [Document ingestion](https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/ingestion): `backend/ingestion`
- [Evaluation metrics](https://github.com/raghuvarma-gilth/cycloneiq/tree/main/backend/evaluation): `backend/evaluation`

### Other components

- **Researcher**
- **LLM service**

## Connections

- Researcher → Streamlit UI: asks
- Streamlit UI → Research pages: opens
- Research pages → RAG pipeline: queries
- Researcher → FastAPI API: submits query
- FastAPI API → RAG pipeline: runs
- RAG pipeline → Language detection: detects language
- RAG pipeline → Query classifiers: classifies query
- RAG pipeline → Legal NER: extracts entities
- RAG pipeline → Domain router: routes query
- RAG pipeline → Hybrid retriever: retrieves evidence
- Hybrid retriever → Dense search: searches semantically
- Hybrid retriever → BM25 search: searches keywords
- Hybrid retriever → Fusion and reranking: fuses and reranks
- Hybrid retriever → Evidence filtering: filters evidence
- Dense search → Vector index: reads index
- RAG pipeline → Temporal retrieval: filters by time
- RAG pipeline → Knowledge graph: adds graph context
- RAG pipeline → Prompt builder: builds prompt
- RAG pipeline → LLM provider: requests generation
- LLM provider → LLM service: generates answer
- RAG pipeline → Citation verification: verifies citations
- Citation verification → FastAPI API: returns verified result
- Document ingestion → Vector index: builds index
- RAG pipeline → Evaluation metrics: measured by