# tnau94/traffic-law-graphrag architecture

> Architecture diagram of the GitHub repository tnau94/traffic-law-graphrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tnau94/traffic-law-graphrag
- Repository: https://github.com/tnau94/traffic-law-graphrag

## Overview

Traffic Law GraphRAG is a Vietnamese traffic-law assistant with two main workflows: ingest legal documents into a Neo4j knowledge graph and hybrid search index, then answer user queries through direct legal lookup or grounded GraphRAG retrieval. The graph also preserves documented amendment/versioning and graph-browsing capabilities. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled details are not assumed.

Main entry points: [`src/pipeline/pipeline.py`](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/pipeline.py) (GraphRAG pipeline), [`src/rag/indexer.py`](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/indexer.py) (Search indexer), [`src/graph/neo4j/connection.py`](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/graph/neo4j/connection.py) (Neo4j client), [`src/sync.py`](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/sync.py) (Corpus sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and experience"]
  node_api["FastAPI application<br/>[main.py]"]
  node_query_route["Query endpoint<br/>[query.py]"]
  node_query_service["Query service<br/>[query_service.py]"]
  node_graph_service["Graph browsing<br/>[graph_service.py]"]
  node_ingest_route["Ingest endpoint<br/>[ingest.py]"]
  node_ingest_service["Ingest service<br/>[ingest_service.py]"]
end

subgraph group_ingest["Legal data ingestion"]
  node_sync["Corpus sync<br/>[sync.py]"]
  node_parser["Legal parsing"]
  node_amendment["Amendment recording"]
  node_graph_importer["Graph importer<br/>[importer.py]"]
  node_indexer["Search indexer<br/>[indexer.py]"]
end

subgraph group_answer["Query and grounding"]
  node_pipeline["GraphRAG pipeline<br/>[pipeline.py]"]
  node_router["Query router<br/>[router.py]"]
  node_rewriter["Query rewriter<br/>[rewriter.py]"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_validator["Graph validation<br/>[graph_validator.py]"]
  node_evidence["Evidence builder"]
  node_generator["Answer generator<br/>[generator.py]"]
  node_keys["Provider key manager<br/>[key_manager.py]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_embedding["Embedding manager<br/>[embedding.py]"]
  node_neo4j_client["Neo4j client<br/>[connection.py]"]
  node_neo4j[("Neo4j graph and indexes")]
  node_versioning["Legal versioning<br/>[version_builder.py]"]
end

node_user(("User"))
node_response["Grounded answer"]

node_user -->|"asks"| node_query_route
node_api -->|"routes"| node_query_route
node_query_route -->|"calls"| node_query_service
node_query_service -->|"runs"| node_pipeline
node_pipeline -->|"routes query"| node_router
node_pipeline -->|"rewrites query"| node_rewriter
node_pipeline -->|"retrieves candidates"| node_retriever
node_pipeline -->|"validates provisions"| node_validator
node_pipeline -->|"builds evidence"| node_evidence
node_pipeline -->|"generates answer"| node_generator
node_router -->|"gets provider keys"| node_keys
node_rewriter -->|"uses provider keys"| node_keys
node_query_service -->|"returns result"| node_response
node_user -.->|"submits documents"| node_ingest_route
node_ingest_route -->|"starts task"| node_ingest_service
node_ingest_service -.->|"parses file"| node_parser
node_sync -->|"parses corpus"| node_parser
node_parser -.->|"records amendments"| node_amendment
node_sync -->|"imports graph"| node_graph_importer
node_sync -->|"builds indexes"| node_indexer
node_ingest_service -->|"indexes units"| node_indexer
node_indexer -->|"embeds text"| node_embedding
node_indexer -->|"writes through"| node_neo4j_client
node_graph_importer -->|"imports through"| node_neo4j_client
node_retriever -->|"embeds query"| node_embedding
node_retriever -->|"searches through"| node_neo4j_client
node_neo4j_client -->|"connects"| node_neo4j
node_graph_service -.->|"browses graph"| node_neo4j
node_graph_importer -->|"builds versions"| node_versioning
node_versioning -.->|"stores legal history"| node_neo4j

click node_api "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/main.py"
click node_query_route "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/routes/query.py"
click node_query_service "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/query_service.py"
click node_graph_service "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/graph_service.py"
click node_ingest_route "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/routes/ingest.py"
click node_ingest_service "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/ingest_service.py"
click node_sync "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/sync.py"
click node_parser "https://github.com/tnau94/traffic-law-graphrag/tree/main/src/parser"
click node_amendment "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/parser/amendment_recorder.py"
click node_graph_importer "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/graph/neo4j/importer.py"
click node_indexer "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/indexer.py"
click node_pipeline "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/pipeline.py"
click node_router "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/router.py"
click node_rewriter "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/rewriter.py"
click node_retriever "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/retriever.py"
click node_validator "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/graph_validator.py"
click node_evidence "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/evidence_builder.py"
click node_generator "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/generator.py"
click node_keys "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/extraction/key_manager.py"
click node_embedding "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/embedding.py"
click node_neo4j_client "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/graph/neo4j/connection.py"
click node_versioning "https://github.com/tnau94/traffic-law-graphrag/blob/main/src/versioning/version_builder.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_api,node_query_route,node_query_service,node_graph_service,node_ingest_route,node_ingest_service,node_user toneBlue
class node_sync,node_parser,node_amendment,node_graph_importer,node_indexer toneAmber
class node_pipeline,node_router,node_rewriter,node_retriever,node_validator,node_evidence,node_generator,node_keys toneMint
class node_embedding,node_neo4j_client,node_neo4j,node_versioning toneRose
class node_response toneIndigo
```

## Components

### API and experience

- [FastAPI application](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/main.py): `src/api/main.py`
- [Query endpoint](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/routes/query.py): `src/api/routes/query.py`
- [Query service](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/query_service.py): `src/api/services/query_service.py`
- [Graph browsing](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/graph_service.py): `src/api/services/graph_service.py`
- [Ingest endpoint](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/routes/ingest.py): `src/api/routes/ingest.py`
- [Ingest service](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/api/services/ingest_service.py): `src/api/services/ingest_service.py`

### Legal data ingestion

- [Corpus sync](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/sync.py): `src/sync.py`
- [Legal parsing](https://github.com/tnau94/traffic-law-graphrag/tree/main/src/parser): `src/parser`
- [Amendment recording](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/parser/amendment_recorder.py): `src/parser/amendment_recorder.py`
- [Graph importer](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/graph/neo4j/importer.py): `src/graph/neo4j/importer.py`
- [Search indexer](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/indexer.py): `src/rag/indexer.py`

### Query and grounding

- [GraphRAG pipeline](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/pipeline.py): `src/pipeline/pipeline.py`
- [Query router](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/router.py): `src/pipeline/router.py`
- [Query rewriter](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/rewriter.py): `src/pipeline/rewriter.py`
- [Hybrid retriever](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/retriever.py): `src/rag/retriever.py`
- [Graph validation](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/graph_validator.py): `src/pipeline/graph_validator.py`
- [Evidence builder](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/evidence_builder.py): `src/pipeline/evidence_builder.py`
- [Answer generator](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/pipeline/generator.py): `src/pipeline/generator.py`
- [Provider key manager](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/extraction/key_manager.py): `src/extraction/key_manager.py`

### Knowledge and retrieval

- [Embedding manager](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/rag/embedding.py): `src/rag/embedding.py`
- [Neo4j client](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/graph/neo4j/connection.py): `src/graph/neo4j/connection.py`
- **Neo4j graph and indexes**
- [Legal versioning](https://github.com/tnau94/traffic-law-graphrag/blob/main/src/versioning/version_builder.py): `src/versioning/version_builder.py`

### Other components

- **User**
- **Grounded answer**

## Connections

- User → Query endpoint: asks (evidence: `README.md`)
- FastAPI application → Query endpoint: routes (evidence: `src/api/main.py`)
- Query endpoint → Query service: calls (evidence: `src/api/routes/query.py`)
- Query service → GraphRAG pipeline: runs (evidence: `src/api/services/query_service.py`)
- GraphRAG pipeline → Query router: routes query (evidence: `src/pipeline/pipeline.py`)
- GraphRAG pipeline → Query rewriter: rewrites query (evidence: `src/pipeline/pipeline.py`)
- GraphRAG pipeline → Hybrid retriever: retrieves candidates (evidence: `src/pipeline/pipeline.py`)
- GraphRAG pipeline → Graph validation: validates provisions (evidence: `src/pipeline/pipeline.py`)
- GraphRAG pipeline → Evidence builder: builds evidence (evidence: `src/pipeline/pipeline.py`)
- GraphRAG pipeline → Answer generator: generates answer (evidence: `src/pipeline/pipeline.py`)
- Query router → Provider key manager: gets provider keys (evidence: `src/pipeline/router.py`)
- Query rewriter → Provider key manager: uses provider keys (evidence: `src/pipeline/rewriter.py`)
- Query service → Grounded answer: returns result (evidence: `src/api/services/query_service.py`)
- User → Ingest endpoint: submits documents (evidence: `README.md`)
- Ingest endpoint → Ingest service: starts task (evidence: `src/api/routes/ingest.py`)
- Ingest service → Legal parsing: parses file
- Corpus sync → Legal parsing: parses corpus (evidence: `README.md`)
- Legal parsing → Amendment recording: records amendments (evidence: `src/parser/amendment_recorder.py`)
- Corpus sync → Graph importer: imports graph (evidence: `README.md`)
- Corpus sync → Search indexer: builds indexes (evidence: `README.md`)
- Ingest service → Search indexer: indexes units (evidence: `src/api/services/ingest_service.py`)
- Search indexer → Embedding manager: embeds text (evidence: `src/rag/indexer.py`)
- Search indexer → Neo4j client: writes through (evidence: `src/rag/indexer.py`)
- Graph importer → Neo4j client: imports through (evidence: `src/graph/neo4j/importer.py`)
- Hybrid retriever → Embedding manager: embeds query (evidence: `src/rag/retriever.py`)
- Hybrid retriever → Neo4j client: searches through (evidence: `src/rag/retriever.py`)
- Neo4j client → Neo4j graph and indexes: connects (evidence: `src/graph/neo4j/connection.py`)
- Graph browsing → Neo4j graph and indexes: browses graph
- Graph importer → Legal versioning: builds versions (evidence: `src/graph/neo4j/importer.py`)
- Legal versioning → Neo4j graph and indexes: stores legal history
