# aigurutinix/r2ai-stage-1 architecture

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

- Interactive diagram: https://gitdiagram.com/aigurutinix/r2ai-stage-1
- Repository: https://github.com/aigurutinix/r2ai-stage-1

## Overview

This repository is a collection of independent Vietnamese legal-information-retrieval and legal-QA contest submissions, not one shared runtime. The principal workflow is a user question entering a team’s application, being matched against legal-document indexes, and producing a grounded answer with citations. The graph highlights the sampled NextGen and Hung&Phong runtime paths, plus other documented/core subsystems. Some components are represented by their exact tree paths but were not sampled; their internal connections are therefore omitted. The README describes intended capabilities, not a shared implementation.

Main entry points: [`nextgen/src/main.py`](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/main.py) (Pipeline runner), [`nextgen/src/src/app/service.py`](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/app/service.py) (RAG service), [`nextgen/src/src/hybrid_retriever.py`](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/hybrid_retriever.py) (Hybrid retrieval), [`hung&phong/src/backend/main.py`](https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/main.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_nextgen["NextGen legal assistant"]
  node_ng_ui["Chat UI<br/>[App.jsx]"]
  node_ng_sse["SSE client<br/>[sse.js]"]
  node_ng_api["Demo API<br/>[main.py]"]
  node_ng_service["RAG service<br/>[service.py]"]
  node_ng_orchestrator["Pipeline runner<br/>[main.py]"]
  node_ng_hybrid["Hybrid retrieval"]
  node_ng_bm25["BM25 index<br/>[index_bm25.py]"]
  node_ng_reranker["Cross-encoder ranker<br/>[reranker.py]"]
  node_ng_generator["Answer generation"]
  node_ng_api_generator["API answer generation"]
  node_ng_verifier["Self-verification<br/>[self_verifier.py]"]
  node_ng_post["Reference post-processing<br/>[post_processor.py]"]
  node_ng_settings["Pipeline settings<br/>[settings.py]"]
end

subgraph group_hungphong["Hung&amp;Phong RAG"]
  node_hp_api["Chat API<br/>[main.py]"]
  node_hp_rag["RAG pipeline<br/>[rag.py]"]
  node_hp_analyzer["Query filters<br/>[query_analyzer.py]"]
  node_hp_config["Backend settings<br/>[config.py]"]
end

subgraph group_mscai["mscAI services"]
  node_ms_config["Backend settings<br/>[config.py]"]
  node_ms_legal["Legal API routes<br/>[legal.py]"]
  node_ms_index["Vector index builder<br/>[index_builder.py]"]
  node_ms_mcp_config["MCP settings<br/>[config.py]"]
end

subgraph group_other["Other team submissions"]
  node_nghiem_rerank["LLM reretrieval"]
  node_thanh_config["Agent settings<br/>[config.py]"]
  node_tran_models["Local model settings"]
  node_agentic_corpus["Legal corpus canonicalizer"]
  node_beeit_search["Legal search<br/>[search_v2.py]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_ng_ui
node_ng_ui -->|"streams questions"| node_ng_sse
node_ng_api -->|"delegates to"| node_ng_service
node_ng_service -->|"retrieves with"| node_ng_hybrid
node_ng_service -->|"reranks with"| node_ng_reranker
node_ng_service -->|"generates via"| node_ng_api_generator
node_ng_service -->|"reads settings"| node_ng_settings
node_ng_orchestrator -->|"retrieves with"| node_ng_hybrid
node_ng_orchestrator -->|"reranks with"| node_ng_reranker
node_ng_orchestrator -->|"generates via"| node_ng_generator
node_ng_orchestrator -->|"verifies with"| node_ng_verifier
node_ng_orchestrator -->|"post-processes"| node_ng_post
node_ng_hybrid -->|"uses sparse index"| node_ng_bm25
node_hp_api -->|"calls"| node_hp_rag
node_hp_api -->|"loads settings"| node_hp_config
node_hp_rag -->|"analyzes query"| node_hp_analyzer

click node_ng_ui "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/web/src/App.jsx"
click node_ng_sse "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/web/src/lib/sse.js"
click node_ng_api "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/app/main.py"
click node_ng_service "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/app/service.py"
click node_ng_orchestrator "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/main.py"
click node_ng_hybrid "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/hybrid_retriever.py"
click node_ng_bm25 "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/index_bm25.py"
click node_ng_reranker "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/reranker.py"
click node_ng_generator "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/answer_generator.py"
click node_ng_api_generator "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/api_answer_generator.py"
click node_ng_verifier "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/self_verifier.py"
click node_ng_post "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/post_processor.py"
click node_ng_settings "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/config/settings.py"
click node_hp_api "https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/main.py"
click node_hp_rag "https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/rag.py"
click node_hp_analyzer "https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/query_analyzer.py"
click node_hp_config "https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/config.py"
click node_ms_config "https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/config.py"
click node_ms_legal "https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/routers/legal.py"
click node_ms_index "https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/services/vector_store/index_builder.py"
click node_ms_mcp_config "https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/mcp/src/legal_mcp/config.py"
click node_nghiem_rerank "https://github.com/aigurutinix/r2ai-stage-1/blob/main/nguyenvannghiem/src/code/retrieval_llm_rerank.py"
click node_thanh_config "https://github.com/aigurutinix/r2ai-stage-1/blob/main/thanhkhauson/src/Agents/config.py"
click node_tran_models "https://github.com/aigurutinix/r2ai-stage-1/blob/main/tranthanhtu/src/backend/local_models_config.py"
click node_agentic_corpus "https://github.com/aigurutinix/r2ai-stage-1/blob/main/agentic_builders/src/03_source_code/data_pipeline/canonicalize_legal_corpus.py"
click node_beeit_search "https://github.com/aigurutinix/r2ai-stage-1/blob/main/beeit/src/search_v2.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_ng_ui,node_ng_sse,node_ng_api,node_ng_service,node_ng_orchestrator,node_ng_hybrid,node_ng_bm25,node_ng_reranker,node_ng_generator,node_ng_api_generator,node_ng_verifier,node_ng_post,node_ng_settings toneBlue
class node_hp_api,node_hp_rag,node_hp_analyzer,node_hp_config toneAmber
class node_ms_config,node_ms_legal,node_ms_index,node_ms_mcp_config toneMint
class node_nghiem_rerank,node_thanh_config,node_tran_models,node_agentic_corpus,node_beeit_search toneRose
class node_user toneIndigo
```

## Components

### NextGen legal assistant

- [Chat UI](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/web/src/App.jsx): `nextgen/src/src/web/src/App.jsx`
- [SSE client](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/web/src/lib/sse.js): `nextgen/src/src/web/src/lib/sse.js`
- [Demo API](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/app/main.py): `nextgen/src/src/app/main.py`
- [RAG service](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/app/service.py): `nextgen/src/src/app/service.py`
- [Pipeline runner](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/main.py): `nextgen/src/main.py`
- [Hybrid retrieval](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/hybrid_retriever.py): `nextgen/src/src/hybrid_retriever.py`
- [BM25 index](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/index_bm25.py): `nextgen/src/src/index_bm25.py`
- [Cross-encoder ranker](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/reranker.py): `nextgen/src/src/reranker.py`
- [Answer generation](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/answer_generator.py): `nextgen/src/src/answer_generator.py`
- [API answer generation](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/api_answer_generator.py): `nextgen/src/src/api_answer_generator.py`
- [Self-verification](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/self_verifier.py): `nextgen/src/src/self_verifier.py`
- [Reference post-processing](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/post_processor.py): `nextgen/src/src/post_processor.py`
- [Pipeline settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nextgen/src/src/config/settings.py): `nextgen/src/src/config/settings.py`

### Hung&Phong RAG

- [Chat API](https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/main.py): `hung&phong/src/backend/main.py`
- [RAG pipeline](https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/rag.py): `hung&phong/src/backend/rag.py`
- [Query filters](https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/query_analyzer.py): `hung&phong/src/backend/query_analyzer.py`
- [Backend settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/hung%26phong/src/backend/config.py): `hung&phong/src/backend/config.py`

### mscAI services

- [Backend settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/config.py): `mscai/src/backend/src/config.py`
- [Legal API routes](https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/routers/legal.py): `mscai/src/backend/src/routers/legal.py`
- [Vector index builder](https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/backend/src/services/vector_store/index_builder.py): `mscai/src/backend/src/services/vector_store/index_builder.py`
- [MCP settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/mscai/src/mcp/src/legal_mcp/config.py): `mscai/src/mcp/src/legal_mcp/config.py`

### Other team submissions

- [LLM reretrieval](https://github.com/aigurutinix/r2ai-stage-1/blob/main/nguyenvannghiem/src/code/retrieval_llm_rerank.py): `nguyenvannghiem/src/code/retrieval_llm_rerank.py`
- [Agent settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/thanhkhauson/src/Agents/config.py): `thanhkhauson/src/Agents/config.py`
- [Local model settings](https://github.com/aigurutinix/r2ai-stage-1/blob/main/tranthanhtu/src/backend/local_models_config.py): `tranthanhtu/src/backend/local_models_config.py`
- [Legal corpus canonicalizer](https://github.com/aigurutinix/r2ai-stage-1/blob/main/agentic_builders/src/03_source_code/data_pipeline/canonicalize_legal_corpus.py): `agentic_builders/src/03_source_code/data_pipeline/canonicalize_legal_corpus.py`
- [Legal search](https://github.com/aigurutinix/r2ai-stage-1/blob/main/beeit/src/search_v2.py): `beeit/src/search_v2.py`

### Other components

- **Questioner**

## Connections

- Questioner → Chat UI: asks (evidence: `README.md`)
- Chat UI → SSE client: streams questions (evidence: `nextgen/src/src/web/src/App.jsx`)
- Demo API → RAG service: delegates to (evidence: `nextgen/src/src/app/main.py`)
- RAG service → Hybrid retrieval: retrieves with (evidence: `nextgen/src/src/app/service.py`)
- RAG service → Cross-encoder ranker: reranks with (evidence: `nextgen/src/src/app/service.py`)
- RAG service → API answer generation: generates via (evidence: `nextgen/src/src/app/service.py`)
- RAG service → Pipeline settings: reads settings (evidence: `nextgen/src/src/app/service.py`)
- Pipeline runner → Hybrid retrieval: retrieves with (evidence: `nextgen/src/main.py`)
- Pipeline runner → Cross-encoder ranker: reranks with (evidence: `nextgen/src/main.py`)
- Pipeline runner → Answer generation: generates via (evidence: `nextgen/src/main.py`)
- Pipeline runner → Self-verification: verifies with (evidence: `nextgen/src/main.py`)
- Pipeline runner → Reference post-processing: post-processes (evidence: `nextgen/src/main.py`)
- Hybrid retrieval → BM25 index: uses sparse index (evidence: `nextgen/src/src/hybrid_retriever.py`)
- Chat API → RAG pipeline: calls (evidence: `hung&phong/src/backend/main.py`)
- Chat API → Backend settings: loads settings (evidence: `hung&phong/src/backend/main.py`)
- RAG pipeline → Query filters: analyzes query (evidence: `hung&phong/src/backend/rag.py`)
