# ctu-lingutechies/vn-law-advisor architecture

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

- Interactive diagram: https://gitdiagram.com/ctu-lingutechies/vn-law-advisor
- Repository: https://github.com/ctu-lingutechies/vn-law-advisor

## Overview

VN-Law-Advisor is a Vietnamese legal-information product for asking questions and finding, reading, and summarizing codified law and legal documents. Users enter through the Next.js web app; its major experiences include chat, authentication, codification browsing, and document search. The backend separates identity, law-data APIs, and RAG question answering; a crawler imports codification data. The README also documents keyword-based document recommendations and user feedback, though their runtime wiring is not sampled. RAG retrieval and generation follow the README and app excerpt; some service-to-service links remain unverified.

Main entry points: [`web/services`](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/web/services) (Web API clients), [`backend/rag/app.py`](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/app.py) (RAG question API), [`backend/auth-service/controllers/AuthController.js`](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/controllers/AuthController.js) (Auth API), [`backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice`](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice) (Law-data API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Next.js web app"]
  node_webservices["Web API clients"]
end

subgraph group_identity["Identity"]
  node_authapi["Auth API<br/>[AuthController.js]"]
  node_authdb[("User database")]
  node_redis[("Refresh-token cache<br/>[redisService.js]")]
end

subgraph group_legal["Legal data"]
  node_lawapi["Law-data API"]
  node_codification[("Codification hierarchy<br/>[PDDieu.java]")]
  node_lawdocs[("Legal documents<br/>[VBPL.java]")]
  node_recommendations["Document recommendations"]
end

subgraph group_qa["Question answering"]
  node_ragapi["RAG question API<br/>[app.py]"]
  node_vectorstore[("Legal embeddings")]
  node_llm["Answer generation service"]
  node_qahistory[("Question history<br/>[models.py]")]
end

subgraph group_ingestion["Data ingestion"]
  node_crawler["Codification crawler<br/>[main.py]"]
  node_crawlerdb[("Crawler data models<br/>[models.py]")]
end

node_user(("Legal information seeker"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_webservices
node_webservices -.->|"authenticates"| node_authapi
node_webservices -.->|"retrieves law"| node_lawapi
node_webservices -.->|"asks questions"| node_ragapi
node_webservices -.->|"requests suggestions"| node_recommendations
node_authapi -->|"reads and writes"| node_authdb
node_authapi -->|"stores tokens"| node_redis
node_lawapi -.->|"serves codification"| node_codification
node_lawapi -.->|"serves documents"| node_lawdocs
node_ragapi -->|"retrieves context"| node_vectorstore
node_ragapi -->|"sends prompt"| node_llm
node_ragapi -->|"stores answers"| node_qahistory
node_crawler -->|"imports models"| node_crawlerdb
node_crawler -.->|"loads law data"| node_codification

click node_webapp "https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/web/src/app"
click node_webservices "https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/web/services"
click node_authapi "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/controllers/AuthController.js"
click node_authdb "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/services/sequelizeService.js"
click node_redis "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/services/redisService.js"
click node_lawapi "https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice"
click node_codification "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/PDDieu/PDDieu.java"
click node_lawdocs "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/VBPL/VBPL.java"
click node_ragapi "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/app.py"
click node_vectorstore "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/vectorize_corpus.py"
click node_qahistory "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/models.py"
click node_crawler "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/law-crawler/main.py"
click node_crawlerdb "https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/law-crawler/models/models.py"
click node_recommendations "https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/backend/recommendation"

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_webapp,node_webservices toneBlue
class node_authapi,node_authdb,node_redis toneAmber
class node_lawapi,node_codification,node_lawdocs,node_recommendations toneMint
class node_ragapi,node_vectorstore,node_llm,node_qahistory toneRose
class node_crawler,node_crawlerdb,node_user toneIndigo
```

## Components

### Web experience

- [Next.js web app](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/web/src/app): `web/src/app`
- [Web API clients](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/web/services): `web/services`

### Identity

- [Auth API](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/controllers/AuthController.js): `backend/auth-service/controllers/AuthController.js`
- [User database](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/services/sequelizeService.js): `backend/auth-service/services/sequelizeService.js`
- [Refresh-token cache](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/auth-service/services/redisService.js): `backend/auth-service/services/redisService.js`

### Legal data

- [Law-data API](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice): `backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice`
- [Codification hierarchy](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/PDDieu/PDDieu.java): `backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/PDDieu/PDDieu.java`
- [Legal documents](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/VBPL/VBPL.java): `backend/law-service/src/main/java/lingutechies/vnlawadvisor/lawservice/VBPL/VBPL.java`
- [Document recommendations](https://github.com/ctu-lingutechies/vn-law-advisor/tree/main/backend/recommendation): `backend/recommendation`

### Question answering

- [RAG question API](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/app.py): `backend/rag/app.py`
- [Legal embeddings](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/vectorize_corpus.py): `backend/rag/vectorize_corpus.py`
- **Answer generation service**
- [Question history](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/backend/rag/models.py): `backend/rag/models.py`

### Data ingestion

- [Codification crawler](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/law-crawler/main.py): `law-crawler/main.py`
- [Crawler data models](https://github.com/ctu-lingutechies/vn-law-advisor/blob/main/law-crawler/models/models.py): `law-crawler/models/models.py`

### Other components

- **Legal information seeker**

## Connections

- Legal information seeker → Next.js web app: uses (evidence: `README.md`)
- Next.js web app → Web API clients: requests data
- Web API clients → Auth API: authenticates
- Web API clients → Law-data API: retrieves law
- Web API clients → RAG question API: asks questions
- Web API clients → Document recommendations: requests suggestions
- Auth API → User database: reads and writes (evidence: `backend/auth-service/controllers/AuthController.js`)
- Auth API → Refresh-token cache: stores tokens (evidence: `backend/auth-service/controllers/AuthController.js`)
- Law-data API → Codification hierarchy: serves codification (evidence: `README.md`)
- Law-data API → Legal documents: serves documents (evidence: `README.md`)
- RAG question API → Legal embeddings: retrieves context (evidence: `backend/rag/app.py`)
- RAG question API → Answer generation service: sends prompt (evidence: `backend/rag/app.py`)
- RAG question API → Question history: stores answers (evidence: `backend/rag/app.py`)
- Codification crawler → Crawler data models: imports models (evidence: `law-crawler/main.py`)
- Codification crawler → Codification hierarchy: loads law data (evidence: `README.md`)
