# avg-team/vn-law architecture

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

- Interactive diagram: https://gitdiagram.com/avg-team/vn-law
- Repository: https://github.com/avg-team/vn-law

## Overview

##### Project type and purpose
- This is a full-stack, microservice-based legal knowledge search and Q&A application (“VN LAW”) built on a monorepo layout.
- It serves user-facing front-ends (website, mobile, docs) and a suite of back-end microservices (Java Spring Boot, Python) behind a Kong API Gateway.
- It features: secure authentication/authorization, law document ingestion and indexing, generative‐AI-driven NLP (embeddings and Q&A), real-time chat, and crawl pipelines.

##### High-level file structure and architectural patterns
- Top level:
- api-gateway (Kong router + routing rules)
- auth-service, base-service, customer-service, law-service (Spring Boot microservices, each with its own Dockerfile, DB configs, caches, Kafka producers/consumers)
- chat-service (Python inference and training with Chroma DB embeddings)
- crawl (Python Flask + Celery ingestion pipeline)
- front-end:
– website (React/Vite)
– mobile (Flutter multi-platform)
– docs (Docusaurus)
- docker-compose.yml, pom.xml, prometheus.yml
- Architectural patterns:
- Microservice decomposition by domain (auth, law, customer, base library)
- API Gateway for request routing, SSL termination, rate-limiting (Kong)
- Event-driven flows via Kafka (document sync, notifications)
- Caching (Redis via Spring configs)
- Search indexing (Elasticsearch in law-service + ChromaDB in chat)
- Async task queue (Celery in crawl service)
- DevOps: Docker-Compose, Kubernetes (ArgoCD, Helm), Pulumi IaC, Observability (Prometheus, Grafana, Zipkin, Fluentd)

##### Main components
- Front-ends:
- Website (React)
- Mobile app (Flutter)
- Documentation portal (Docusaurus)
- API Gateway: Kong (kong.yml)
- Back-end microservices:
- auth-service: JWT, API-key filters, OAuth2, MySQL DB
- base-service: common entities, swagger, Redis-cache
- customer-service: domain logic, WebSocket chat, Kafka producers/consumers, MySQL
- law-service: document controllers, Kafka, Elasticsearch, Redis, MySQL
- crawl: Flask API, Celery workers, SQL ingestion, raw file processor
- chat-service: model inference server, embedding pipeline, Chroma DB storage
- Data stores and middleware:
- MySQL clusters (one per service or shared multi-schema)
- Redis for cache and Celery broker
- Kafka cluster for event streaming
- Elasticsearch for full-text law search
- ChromaDB for embedding vector search
- Observability & infra:
- Prometheus (prometheus.yml)
- Grafana, Zipkin, Fluentd
- CI/CD (Jenkins, ArgoCD), Pulumi IaC

##### Relationships and data flows
- User → [Website / Mobile] → API Gateway → appropriate microservice
- auth-service ↔ MySQL, issue JWT → gateways and other services
- law-service: CRUD & sync data → publish events to Kafka → Index to Elasticsearch
- customer-service: push notifications via Kafka → clients via WebSocket
- crawl: scheduled tasks (Celery) → ingest raw documents → store in MySQL → send sync events
- chat-service: user question → embed with model → query ChromaDB → return answer
- base-service: shared DTOs/entities → consumed by other services

##### Architectural patterns & design principles
- Single responsibility microservices
- API-first design behind a unified gateway
- Event-driven asynchronous communication (Kafka)
- CQRS style for search/indexing (law-service writes to ES, search reads from ES)
- Cache-aside pattern (Redis) for heavy read operations
- Separation of concerns: front-end vs back-end vs data layers vs integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Front-end Layer"
        Website["Website (React/Vite)"]:::frontend
        Mobile["Mobile App (Flutter)"]:::frontend
        Docs["Documentation Portal (Docusaurus)"]:::frontend
    end

    Gateway["API Gateway (Kong)"]:::gateway

    subgraph "Back-end Services"
        Auth["auth-service\nSpring Boot\nJWT, OAuth2"]:::service
        Base["base-service\nCommon Entities\nRedis-cache"]:::service
        Customer["customer-service\nWebSocket, Kafka"]:::service
        Law["law-service\nElasticsearch, Kafka, Redis"]:::service
        Crawl["crawl-service\nFlask, Celery"]:::service
        Chat["chat-service\nInference, ChromaDB"]:::ai
    end

    subgraph "Data Stores & Middleware"
        MySQL["MySQL Clusters"]:::db
        Redis["Redis (Cache & Broker)"]:::middleware
        Kafka["Kafka Cluster"]:::middleware
        ES["Elasticsearch"]:::db
        Chroma["ChromaDB"]:::db
    end

    subgraph "Infra & Observability"
        Prom["Prometheus"]:::infra
        Graf["Grafana"]:::infra
        Zip["Zipkin"]:::infra
        Fluent["Fluentd"]:::infra
    end

    %% User request flow
    Website -->|"HTTP/REST"| Gateway
    Mobile -->|"HTTP/REST"| Gateway
    Docs -->|"HTTP/REST"| Gateway

    %% Gateway routing
    Gateway -->|"Route to Auth"| Auth
    Gateway -->|"Route to Base"| Base
    Gateway -->|"Route to Customer"| Customer
    Gateway -->|"Route to Law"| Law
    Gateway -->|"Route to Crawl"| Crawl
    Gateway -->|"Route to Chat"| Chat

    %% Service to Data Stores
    Auth -->|"JDBC/MySQL"| MySQL
    Base -->|"Cache aside"| Redis
    Customer -->|"JDBC/MySQL"| MySQL
    Customer -->|"Kafka produce/consume"| Kafka
    Law -->|"JDBC/MySQL"| MySQL
    Law -->|"Kafka produce"| Kafka
    Law -->|"Index/Query"| ES
    Law -->|"Cache aside"| Redis
    Crawl -->|"JDBC/MySQL"| MySQL
    Crawl -->|"Kafka produce"| Kafka
    Chat -->|"Vector Query"| Chroma

    %% WebSocket push
    Customer -->|"WebSocket"| Website
    Customer -->|"WebSocket"| Mobile

    %% Event-driven flows
    Kafka -->|"Event stream"| Law
    Kafka -->|"Event stream"| Customer

    %% Observability
    Auth --> Prom
    Base --> Prom
    Customer --> Prom
    Law --> Prom
    Crawl --> Prom
    Chat --> Prom

    %% Click Events
    click Gateway "https://github.com/avg-team/vn-law/blob/main/api-gateway/kong.yml"
    click Auth "https://github.com/avg-team/vn-law/tree/main/auth-service/"
    click Base "https://github.com/avg-team/vn-law/tree/main/base-service/"
    click Customer "https://github.com/avg-team/vn-law/tree/main/customer-service/"
    click Law "https://github.com/avg-team/vn-law/tree/main/law-service/"
    click Crawl "https://github.com/avg-team/vn-law/tree/main/crawl/"
    click Chat "https://github.com/avg-team/vn-law/tree/main/chat-service/"
    click Website "https://github.com/avg-team/vn-law/tree/main/front-end/website/"
    click Mobile "https://github.com/avg-team/vn-law/tree/main/front-end/mobile/"
    click Docs "https://github.com/avg-team/vn-law/tree/main/front-end/docs/"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef gateway fill:#FFA500,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#FF6347,stroke:#000,stroke-width:1px
    classDef middleware fill:#FFD700,stroke:#000,stroke-width:1px
    classDef ai fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
