# ldlinglingling/rag-of-law architecture

> Architecture diagram of the GitHub repository ldlinglingling/rag-of-law, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ldlinglingling/rag-of-law
- Repository: https://github.com/ldlinglingling/rag-of-law

## Overview

##### Project Type and Purpose
- This is an ML-centric “full‐stack” service for legal question answering built on a Retrieval‐Augmented Fine-Tuning (RAFT) framework.
- It comprises offline training pipelines, an inference pipeline, a lightweight web service, and backing data stores (legal clause library, embeddings, BM25 index).

##### File Structure
Top‐level files:
- README.md           → project overview, architecture summary
- fatiao.json         → raw legal clause library
- training_data.json  → Q&A training set
- training_data_sample.tsv.gz → sample training data
Training/inference scripts:
- data_proc.py            → preprocessing pipeline (tokenization, indexing)
- bert_cls.py             → BERT‐based two‐level classification model (12 categories + 115 subcategories)
- train_data_extractor.py → supervised fine-tuning script for answer extraction
- train_bi_encoder.py     → contrastive training for semantic retrieval encoder
- extract_law_embs.py     → generate & store law‐clause embeddings
- sample_run.py           → simple end-to-end demo
- infer.py                → core inference pipeline (classification → retrieval → generation)
- web_main.py             → web server entrypoint (API endpoints)

##### README Insights
- The logical flow is:
User question
↓ Classification model (bert_cls.py)
↓ Law category → Semantic retrieval (BM25 + bi-encoder embeddings)
↓ LLM generation → Final answer
- Core components: classification, retrieval, generation.
- Data: legal clause library and Q&A dataset.

##### Main Components & Their Relationships
A. Frontend/API Layer
- web_main.py exposes REST or HTTP endpoints.
- Receives user questions; returns professional answers.
B. Classification Service
- bert_cls.py loaded by infer.py
- Determines broad/sub‐category
C. Retrieval Service
- BM25 index (from data_proc.py + inverted index)
- Vector index (embeddings from extract_law_embs.py)
- Bi‐encoder model (train_bi_encoder.py) for semantic scoring
D. Generation Service
- LLM (external API or local model) called by infer.py
- Uses retrieved clauses + question as prompt
E. Data Stores
- Raw clauses (fatiao.json)
- Precomputed embeddings (file‐based or vector DB)
- BM25 inverted index
- Training datasets
F. Offline Training Pipelines
- Preprocessing (data_proc.py) → cleaned JSON/TSV
- Classification training (bert_cls.py)
- Retrieval encoder training (train_bi_encoder.py)
- Fine-tuning generator (train_data_extractor.py)

##### Architectural Patterns & Design Principles
- Pipeline pattern: sequential stages (classify → retrieve → generate)
- Separation of concerns: offline training modules vs. online inference modules
- Modular ML microservices: each core function can be containerized
- Data‐driven: indexes and embeddings persisted externally for fast lookup

##### Essential Elements
- Clear component names

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Online Inference Flow
    subgraph "Online Inference"
        direction TB
        UI["User"]:::external
        API["Web Service\n(web_main.py)"]:::runtime
        Classifier["Classification Service\n(bert_cls.py)"]:::runtime
        Retriever["Retrieval Engine\n(BM25 + Vector)"]:::runtime
        Generator["LLM Generation\n(infer.py)"]:::runtime
    end

    UI -->|Ask Question| API
    API -->|Forward Request| Classifier
    Classifier -->|Category| Retriever
    Retriever -->|Top Clauses| Generator
    Generator -->|Answer| API
    API -->|Respond| UI

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Clauses[(Legal Clause Library\nfatiao.json)]:::data
        BM25Index[(BM25 Inverted Index)]:::data
        Embeddings[(Precomputed Embeddings)]:::data
        QnA[(Q&A Training Data\ntraining_data.json)]:::data
        SampleData[(Sample Training Data\ntraining_data_sample.tsv.gz)]:::data
        README[(README & Architecture\nREADME.md)]:::data
    end

    %% Offline Training Pipelines
    subgraph "Offline Training"
        direction TB
        Preproc["Preprocessing & Indexing\n(data_proc.py)"]:::offline
        EmbGen["Embedding Generation\n(extract_law_embs.py)"]:::offline
        BiEncTrain["Bi-Encoder Training\n(train_bi_encoder.py)"]:::offline
        AnsExt["Answer Extraction FT\n(train_data_extractor.py)"]:::offline
        Demo["Demo End-to-End Run\n(sample_run.py)"]:::offline
    end

    %% Offline to Data Stores (dashed)
    Preproc -.-> Clauses
    Preproc -.-> BM25Index
    EmbGen -.-> Embeddings
    BiEncTrain -.-> Embeddings
    AnsExt -.-> QnA
    Demo -.->|Uses| Clauses
    Demo -.->|Uses| QnA
    Demo -.->|Uses| SampleData

    %% Classifier & Retriever lookup
    Retriever --> BM25Index
    Retriever --> Embeddings

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#005B99,color:#003366,stroke-width:1px;
    classDef offline fill:#FFE8CC,stroke:#994C00,color:#663300,stroke-width:1px;
    classDef data fill:#E8FFE8,stroke:#009900,color:#006600,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333,stroke-width:1px;

    %% Click Events
    click API "https://github.com/ldlinglingling/rag-of-law/blob/main/web_main.py"
    click Classifier "https://github.com/ldlinglingling/rag-of-law/blob/main/bert_cls.py"
    click Retriever "https://github.com/ldlinglingling/rag-of-law/blob/main/data_proc.py"
    click EmbGen "https://github.com/ldlinglingling/rag-of-law/blob/main/extract_law_embs.py"
    click BiEncTrain "https://github.com/ldlinglingling/rag-of-law/blob/main/train_bi_encoder.py"
    click AnsExt "https://github.com/ldlinglingling/rag-of-law/blob/main/train_data_extractor.py"
    click Demo "https://github.com/ldlinglingling/rag-of-law/blob/main/sample_run.py"
    click Generator "https://github.com/ldlinglingling/rag-of-law/blob/main/infer.py"
    click Clauses "https://github.com/ldlinglingling/rag-of-law/blob/main/fatiao.json"
    click QnA "https://github.com/ldlinglingling/rag-of-law/blob/main/training_data.json"
    click SampleData "https://github.com/ldlinglingling/rag-of-law/blob/main/training_data_sample.tsv.gz"
    click README "https://github.com/ldlinglingling/rag-of-law/blob/main/README.md"
```
