# decisionsdev/rule-based-llms architecture

> Architecture diagram of the GitHub repository decisionsdev/rule-based-llms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/decisionsdev/rule-based-llms
- Repository: https://github.com/decisionsdev/rule-based-llms

## Overview

Based on our review of the file tree and README, this project is a demonstration of integrating large language models (LLMs) with rule-based decision services. Its purpose is to allow a chatbot, built as a React web application (chatbot-frontend), to leverage a Python-based backend (rule-agent) that combines LLM reasoning (via Langchain) with the precise business logic provided by rule-based decision services (IBM ODM and IBM ADS implementations in decision_services). In addition, the project includes sample HR service decision cases defined in the data folder (e.g., tool descriptors and business documents) and a variety of configuration environments (using .env files for ADS, Ollama, WatsonX, etc.).

- Frontend: This is the chatbot-frontend project (React/TypeScript UI) that provides the user interface. It includes the user’s browser interactions, API calls, and display components.
- Backend/API Layer: The rule-agent subproject (Python services using Langchain) forms the core chatbot engine. It processes incoming requests from the UI, interacts with the LLM(s), and routes decisions to the rule-based services.
- Decision Services: The decision_services directory contains IBM ODM and ADS implementations (packaged as zip files, ruleapps, and XOM source code) that encapsulate business policies (e.g., HR Service rules for vacation days calculation).
- Data & Configuration: The data directory holds necessary descriptors (e.g., JSON tool descriptors, PDFs) and configuration files that are used by the decision services to drive the business logic.
- Containerization Layer: The Docker Compose setup (docker-compose.yml) orchestrates the containerized environment, gluing together the different components for a seamless demo.

##### Relationships and Interactions
- The Chatbot-frontend (React UI) communicates with the backend service (rule-agent) using API calls to send user queries and receive responses.
- The rule-agent serves as the orchestration layer where LLM outputs are either directly provided back as answers or augmented by querying decision services for business rule validation (e.g., in HR Service use-case).
- The rule-agent invokes decision services (either via REST, if exposed that way, or via service binaries/script interactions) to fetch precise business decisions.
- The decision services retrieve necessary input data (via the tool descriptors in the data folder) and return computed results (e.g., the correct number of vacation days).

##### Architectural Patterns and Technologies
- Separation of Concerns: The system splits responsibilities among the frontend (UI), backend (LLM and decision logic mediator), and decision services (business rule engines).
- Containerization and Deployment: The use of Docker and docker-compose to bundle the services indicates a microservice-like orchestration, even if the services are tightly coupled.
- Extensibility: The “Extending the demonstration” and additional README files hint that the architecture is designed to be modular (e.g., additional decision services or use-cases can be plugged in).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Containerization Layer
    DC["Docker Compose Orchestration"]:::orchestration

    %% Containerized Services Subgraph
    subgraph "Containerized Services"
        F["Chatbot Frontend (React)"]:::frontend
        B["Rule Agent Backend (Python/Langchain)"]:::backend
        D["Decision Services (IBM ODM/ADS)"]:::decision
        C["Data & Configuration"]:::data
    end

    %% Connections between container orchestration and services
    DC --> F
    DC --> B
    DC --> D
    DC --> C

    %% Inter-service communications
    F -->|"API-request"| B
    B -->|"Decision-request"| D
    D -->|"UsesData"| C
    B -->|"LLM-response"| F

    %% Click Events for Component Mapping
    click F "https://github.com/decisionsdev/rule-based-llms/tree/main/chatbot-frontend"
    click B "https://github.com/decisionsdev/rule-based-llms/tree/main/rule-agent"
    click D "https://github.com/decisionsdev/rule-based-llms/tree/main/decision_services"
    click C "https://github.com/decisionsdev/rule-based-llms/tree/main/data"
    click DC "https://github.com/decisionsdev/rule-based-llms/blob/main/docker-compose.yml"

    %% Style Definitions
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#186A3B,stroke-width:2px;
    classDef decision fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef data fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef orchestration fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
