# maitamdev/labor-law-chatbot architecture

> Architecture diagram of the GitHub repository maitamdev/labor-law-chatbot, 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/maitamdev/labor-law-chatbot
- Repository: https://github.com/maitamdev/labor-law-chatbot

## Overview

VietLabor AI is a Vietnamese labor-law assistant. Its main workflow runs from a user question in the Streamlit interface through the chat adapter and legal reasoning pipeline, then returns a validated, evidence-backed answer with citations. The README documents the retrieval, decomposition, clarification, citation safeguards, and account privacy features. Several pipeline modules are unsampled, so their placement reflects documented capabilities; optional graph retrieval is distinguished from the lexical/vector fusion path.

Main entry points: [`rag/chain.py`](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/chain.py) (RAG answer chain), [`rag/hybrid_retriever.py`](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/hybrid_retriever.py) (Hybrid retrieval), [`app/chat_service.py`](https://github.com/maitamdev/labor-law-chatbot/blob/main/app/chat_service.py) (Chat service), [`ui/streamlit_app.py`](https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/streamlit_app.py) (Streamlit interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_ui["Streamlit interface<br/>[streamlit_app.py]"]
  node_layout["Chat and citations<br/>[approved_layout.py]"]
  node_chat["Chat service<br/>[chat_service.py]"]
end

subgraph group_reasoning["Legal reasoning"]
  node_router["Query router<br/>[query_router.py]"]
  node_decomposer["Issue decomposition"]
  node_parser["Legal issue parser"]
  node_chain["RAG answer chain<br/>[chain.py]"]
  node_selector["Evidence selector"]
  node_validator["Output validator"]
  node_llm["Local Ollama LLM<br/>[local_llm.py]"]
end

subgraph group_retrieval["Evidence retrieval"]
  node_retriever["Hybrid retrieval"]
  node_bm25["BM25 search<br/>[bm25_retriever.py]"]
  node_dense["Dense search<br/>[dense_retriever.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_graphretriever["Graph retrieval<br/>[retriever.py]"]
end

subgraph group_knowledge["Legal knowledge"]
  node_vectorstore[("Vector index<br/>[vectorstore.py]")]
  node_graphdb[("Neo4j graph<br/>[connector.py]")]
  node_corpus["Legal corpus<br/>[parser.py]"]
  node_crawler["Law crawler<br/>[vbpl_crawler.py]"]
end

subgraph group_accounts["Accounts and administration"]
  node_accountsui["Account portal<br/>[account_portal.py]"]
  node_accountcontroller["Account controller"]
  node_accounts["Account services<br/>[accounts.py]"]
  node_admin["Admin operations<br/>[admin_service.py]"]
  node_supabase[("Supabase storage<br/>[supabase.py]")]
end

node_user(("User"))

node_user -->|"asks"| node_ui
node_ui -.->|"submits query"| node_chat
node_chat -->|"runs pipeline"| node_chain
node_chain -->|"routes query"| node_router
node_chain -->|"decomposes issues"| node_decomposer
node_decomposer -.->|"parses issues"| node_parser
node_chain -->|"retrieves candidates"| node_retriever
node_retriever -->|"searches lexical"| node_bm25
node_retriever -->|"searches semantic"| node_dense
node_retriever -->|"reranks results"| node_reranker
node_retriever -.->|"expands by graph"| node_graphretriever
node_dense -.->|"queries index"| node_vectorstore
node_graphretriever -->|"queries graph"| node_graphdb
node_chain -->|"selects evidence"| node_selector
node_chain -->|"generates answer"| node_llm
node_chain -->|"validates output"| node_validator
node_validator -->|"returns answer"| node_chat
node_chat -.->|"formats citations"| node_layout
node_layout -.->|"renders response"| node_ui
node_crawler -.->|"collects legal texts"| node_corpus
node_accountsui -->|"dispatches actions"| node_accountcontroller
node_accountcontroller -->|"authenticates"| node_accounts
node_accountsui -->|"shows admin data"| node_admin
node_admin -->|"reads account data"| node_accounts
node_accounts -->|"uses backend"| node_supabase

click node_ui "https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/streamlit_app.py"
click node_layout "https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/components/approved_layout.py"
click node_chat "https://github.com/maitamdev/labor-law-chatbot/blob/main/app/chat_service.py"
click node_router "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/query_router.py"
click node_decomposer "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/issue_decomposer.py"
click node_parser "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/legal_issue_parser.py"
click node_chain "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/chain.py"
click node_selector "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/evidence_selector.py"
click node_validator "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/output_validator.py"
click node_retriever "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/hybrid_retriever.py"
click node_bm25 "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/bm25_retriever.py"
click node_dense "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/dense_retriever.py"
click node_reranker "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/reranker.py"
click node_graphretriever "https://github.com/maitamdev/labor-law-chatbot/blob/main/graph/retriever.py"
click node_vectorstore "https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/vectorstore.py"
click node_graphdb "https://github.com/maitamdev/labor-law-chatbot/blob/main/graph/connector.py"
click node_corpus "https://github.com/maitamdev/labor-law-chatbot/blob/main/ingestion/parser.py"
click node_crawler "https://github.com/maitamdev/labor-law-chatbot/blob/main/law_crawler/vbpl_crawler.py"
click node_llm "https://github.com/maitamdev/labor-law-chatbot/blob/main/models/local_llm.py"
click node_accountsui "https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/components/account_portal.py"
click node_accountcontroller "https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/account_controller.py"
click node_accounts "https://github.com/maitamdev/labor-law-chatbot/blob/main/app/accounts.py"
click node_admin "https://github.com/maitamdev/labor-law-chatbot/blob/main/app/admin_service.py"
click node_supabase "https://github.com/maitamdev/labor-law-chatbot/blob/main/config/supabase.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_ui,node_layout,node_chat,node_user toneBlue
class node_router,node_decomposer,node_parser,node_chain,node_selector,node_validator,node_llm toneAmber
class node_retriever,node_bm25,node_dense,node_reranker,node_graphretriever toneMint
class node_vectorstore,node_graphdb,node_corpus,node_crawler toneRose
class node_accountsui,node_accountcontroller,node_accounts,node_admin,node_supabase toneIndigo
```

## Components

### Chat experience

- [Streamlit interface](https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`
- [Chat and citations](https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/components/approved_layout.py): `ui/components/approved_layout.py`
- [Chat service](https://github.com/maitamdev/labor-law-chatbot/blob/main/app/chat_service.py): `app/chat_service.py`

### Legal reasoning

- [Query router](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/query_router.py): `rag/query_router.py`
- [Issue decomposition](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/issue_decomposer.py): `rag/issue_decomposer.py`
- [Legal issue parser](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/legal_issue_parser.py): `rag/legal_issue_parser.py`
- [RAG answer chain](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/chain.py): `rag/chain.py`
- [Evidence selector](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/evidence_selector.py): `rag/evidence_selector.py`
- [Output validator](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/output_validator.py): `rag/output_validator.py`
- [Local Ollama LLM](https://github.com/maitamdev/labor-law-chatbot/blob/main/models/local_llm.py): `models/local_llm.py`

### Evidence retrieval

- [Hybrid retrieval](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/hybrid_retriever.py): `rag/hybrid_retriever.py`
- [BM25 search](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/bm25_retriever.py): `rag/bm25_retriever.py`
- [Dense search](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/dense_retriever.py): `rag/dense_retriever.py`
- [Cross-encoder reranker](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/reranker.py): `rag/reranker.py`
- [Graph retrieval](https://github.com/maitamdev/labor-law-chatbot/blob/main/graph/retriever.py): `graph/retriever.py`

### Legal knowledge

- [Vector index](https://github.com/maitamdev/labor-law-chatbot/blob/main/rag/vectorstore.py): `rag/vectorstore.py`
- [Neo4j graph](https://github.com/maitamdev/labor-law-chatbot/blob/main/graph/connector.py): `graph/connector.py`
- [Legal corpus](https://github.com/maitamdev/labor-law-chatbot/blob/main/ingestion/parser.py): `ingestion/parser.py`
- [Law crawler](https://github.com/maitamdev/labor-law-chatbot/blob/main/law_crawler/vbpl_crawler.py): `law_crawler/vbpl_crawler.py`

### Accounts and administration

- [Account portal](https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/components/account_portal.py): `ui/components/account_portal.py`
- [Account controller](https://github.com/maitamdev/labor-law-chatbot/blob/main/ui/account_controller.py): `ui/account_controller.py`
- [Account services](https://github.com/maitamdev/labor-law-chatbot/blob/main/app/accounts.py): `app/accounts.py`
- [Admin operations](https://github.com/maitamdev/labor-law-chatbot/blob/main/app/admin_service.py): `app/admin_service.py`
- [Supabase storage](https://github.com/maitamdev/labor-law-chatbot/blob/main/config/supabase.py): `config/supabase.py`

### Other components

- **User**

## Connections

- User → Streamlit interface: asks
- Streamlit interface → Chat service: submits query
- Chat service → RAG answer chain: runs pipeline (evidence: `app/chat_service.py`)
- RAG answer chain → Query router: routes query
- RAG answer chain → Issue decomposition: decomposes issues
- Issue decomposition → Legal issue parser: parses issues
- RAG answer chain → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → BM25 search: searches lexical (evidence: `rag/hybrid_retriever.py`)
- Hybrid retrieval → Dense search: searches semantic (evidence: `rag/hybrid_retriever.py`)
- Hybrid retrieval → Cross-encoder reranker: reranks results (evidence: `rag/hybrid_retriever.py`)
- Hybrid retrieval → Graph retrieval: expands by graph
- Dense search → Vector index: queries index
- Graph retrieval → Neo4j graph: queries graph (evidence: `graph/retriever.py`)
- RAG answer chain → Evidence selector: selects evidence
- RAG answer chain → Local Ollama LLM: generates answer
- RAG answer chain → Output validator: validates output (evidence: `app/chat_service.py`)
- Output validator → Chat service: returns answer (evidence: `app/chat_service.py`)
- Chat service → Chat and citations: formats citations
- Chat and citations → Streamlit interface: renders response
- Law crawler → Legal corpus: collects legal texts
- Account portal → Account controller: dispatches actions (evidence: `ui/account_controller.py`)
- Account controller → Account services: authenticates (evidence: `app/accounts.py`)
- Account portal → Admin operations: shows admin data (evidence: `app/admin_service.py`)
- Admin operations → Account services: reads account data (evidence: `app/admin_service.py`)
- Account services → Supabase storage: uses backend (evidence: `app/accounts.py`)