# thu-keg/diakop architecture

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

- Interactive diagram: https://gitdiagram.com/thu-keg/diakop
- Repository: https://github.com/thu-keg/diakop

## Overview

##### Project Type and Purpose
- DiaKoP is a full-stack, microservice-style system for multi-turn Knowledge-Base Question Answering (KBQA).
- Frontend: two interactive interfaces
- A Gradio-based chat UI for dialogue with the KBQA engine
- A Vue.js “KoPL-vis” program-editing visualizer to inspect/correct parsed logic forms
- Backend: distributed workers handling LLM inference, a semantic-parser service, a dialogue manager, and integration with a KoPL execution engine.

##### High-Level Components
a. Frontend Cluster
- Gradio Web Server (scripts_bash/launch_gradio.sh + frontend-scripts/chat_*). Provides the chat UI.
- KoPL-vis (frontend-src/KoPL-vis/vis): Vue.js SPA for program visualization and editing.
b. Backend Cluster
- Controller Service (launch_controller.sh): orchestrates model workers.
- Model Worker Pool (launch_worker_vllm.sh): each is a Uvicorn-hosted vLLM Llama-3 inference service.
- Semantic Parser Service (launch_semantic_parser.sh): exposes semantic_parser.py via an HTTP/gRPC endpoint.
- Dialogue Manager (scripts/conv_state.py, conversation.py, chat_controllers.py, dialogue policy/history tracker).
- KoPL Execution Engine (external service to execute parsed programs).
c. Data & Knowledge
- Predefined Knowledge Base (external DB or graph store, referenced by the backend).
- Model artifacts: Llama-3 weights, KOPL semantic-parser checkpoint.
d. DevOps & Deployment
- Bash launch scripts for each microservice.
- requirements.txt, .env for API keys.
- Vue config & package.json for KoPL-vis.

##### Relationships & Interactions
- User → Gradio UI: inputs question or program corrections.
- Gradio UI → Controller Service: submits inference requests (via REST/gRPC).
- Controller → Model Workers: load-balanced routing of LLM inference tasks.
- Controller → Semantic Parser Service: logic-form parsing calls.
- Dialogue Manager → Knowledge Base: queries to fetch factual data.
- Backend → KoPL Execution Engine API: to run or validate edited logic forms.

##### Key Architectural Patterns & Principles
- Microservices with a master/worker pattern for scalable LLM inference.
- Clear separation between chat interface and program visualization UI.
- Stateless workers behind a controller for elasticity.
- Single-page app (SPA) frontend using Vue (MVVM pattern).
- Bash script–based orchestration for easy local/demo deployment.

##### Detailed Breakdown
Layer 1 (Presentation):
- User Browser → Gradio Web Server (Python + Flask/Starlette)
- User Browser → KoPL-vis SPA (Vue.js)
Layer 2 (API & Orchestration):
- Gradio → Controller (REST/gRPC)
- KoPL-vis → Semantic Parser / Execution Engine
Layer 3 (Compute & ML):
- Controller → Model Worker Pool (LLM inference)
- Controller → Semantic Parser Service
Layer 4 (Data & External Systems):
- Dialogue Manager → Knowledge Base (DB/Graph)
- Logic Forms → KoPL Execution Engine API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        User(["User"]):::external
        Gradio["Gradio Web UI"]:::frontend
        Vis["KoPL-vis SPA"]:::frontend
    end

    %% API & Orchestration Layer
    subgraph "API & Orchestration Layer"
        Controller["Controller Service\n(launch_controller.sh)"]:::service
        SemParser["Semantic Parser Service"]:::service
        DM["Dialogue Manager"]:::service
    end

    %% Compute & ML Layer
    subgraph "Compute & ML Layer"
        Workers["Model Worker Pool\n(vLLM Llama-3)"]:::service
    end

    %% Data & External Systems Layer
    subgraph "Data & External Systems Layer"
        KB[(Knowledge Base)]:::datastore
        ExecEngine[(KoPL Execution Engine)]:::datastore
    end

    %% Interactions
    User -->|"asks question"| Gradio
    User -->|"edits logic form"| Vis

    Gradio -->|"REST/gRPC /infer"| Controller
    Controller -->|"gRPC /infer"| Workers
    Controller -->|"HTTP /parse"| SemParser
    Controller -->|"manage dialogue"| DM

    Vis -->|"HTTP /parse"| SemParser
    Vis -->|"HTTP /execute"| ExecEngine

    DM -->|"queries"| KB

    %% Click Events
    click Gradio "https://github.com/thu-keg/diakop/blob/main/scripts_bash/launch_gradio.sh"
    click Gradio "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/gradio_web_server.py"
    click Gradio "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/chat_components.py"
    click Gradio "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/chat_controllers.py"

    click Vis "https://github.com/thu-keg/diakop/tree/main/frontend-src/KoPL-vis/vis/"

    click Controller "https://github.com/thu-keg/diakop/blob/main/scripts_bash/launch_controller.sh"

    click Workers "https://github.com/thu-keg/diakop/blob/main/scripts_bash/launch_worker_vllm.sh"
    click Workers "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/model_adapter.py"

    click SemParser "https://github.com/thu-keg/diakop/blob/main/scripts_bash/launch_semantic_parser.sh"
    click SemParser "https://github.com/thu-keg/diakop/blob/main/backend-src/semantic_parser.py"
    click SemParser "https://github.com/thu-keg/diakop/blob/main/backend-src/utils.py"
    click SemParser "https://github.com/thu-keg/diakop/blob/main/backend-src/test_semantic_parser.py"

    click DM "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/conv_state.py"
    click DM "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/conversation.py"
    click DM "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/chat_controllers.py"
    click DM "https://github.com/thu-keg/diakop/blob/main/frontend-src/scripts/utils.py"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef datastore fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef frontend fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#EEE,stroke:#000,stroke-width:1px;
```
