# abhishek-mallick/decision-hub architecture

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

- Interactive diagram: https://gitdiagram.com/abhishek-mallick/decision-hub
- Repository: https://github.com/abhishek-mallick/decision-hub

## Overview

##### Project Type and Purpose
- Decision-Hub is a full-stack, web-based rule-building application.
- Purpose: Enable business analysts to author, manage, debug, and execute decision strategies via no-code, English-like rules underpinned by an LLM (Code Llama 2) and vector‐based storage (FAISS).

##### File Structure
- Top-level Python Backend
- app.py, model.py, ingest.py – Flask application entrypoints and data ingestion
- requirements.txt – Python dependencies (Flask, SQLAlchemy, FAISS, OpenAI/Code Llama client, etc.)
- instance/database.db & database.db – SQLite databases for persistence
- vectorstore/db_faiss – FAISS index files for storing embeddings
- templates/ – Jinja2 HTML templates for server-rendered pages (login, dashboard, rule tester, etc.)
- static/ – Compiled CSS/JS and images served to clients
- Frontend Components
- query-builder/ – React/Redux single-page app for rule creation, management, and debugging
- Advanced-Logic-Builder/ – Reusable logic-builder widget (vanilla JS/React mix) bundled by Vite
- Configuration & Build
- package.json & lock files in each frontend – NPM dependencies
- webpack.config.js, vite.config.ts – Build pipelines for bundling frontend assets
- Auxiliary Files
- vectorstore/ – FAISS index artifacts
- data/ – Reference documents (not part of runtime)
- Hackathon Details/ – Documentation and presentation files

##### README for Additional Insights
- Architectural goals:
- No-code, English-like rule input converted to SQL/JSON/XML via LLM
- Real-time debugging with breakpoints, error messages, execution trace
- Dynamic rule modification via drag-n-drop
- System uses:
- Flask REST and server-rendered routes
- React frontends served either as static SPAs or injected into templates
- SQLite for relational storage, FAISS for vector search

a. Components
- User Browser
- React SPA (query-builder)
- Advanced Logic Builder widget
- Server-rendered pages (Jinja2 templates)
- Web Server / API Layer
- Flask application with REST endpoints and template routes
- Business Logic & Rule Engine
- model.py, ingest.py, LLM interface module
- Code Llama 2 (local or remote inference)
- Datastores
- SQLite relational database
- FAISS-based vectorstore for embeddings
- External Services (optional)
- LLM provider endpoint (if not local)
- Analytics or logging systems
b. Relationships / Data Flow
1. User interacts with front-end UI → triggers HTTP request (REST API or form POST)
2. Flask API receives request → calls rule-engine services in model.py
3. For NLP to Query: invokes LLM interface → returns SQL/JSON rules
4. Query execution: backend runs generated query against SQLite or JSON stores
5. For similarity search or contextual schemas: backend queries FAISS index
6. Results & execution trace sent back → UI displays debug info or visualizations
c. Architectural Patterns & Principles
- Modular separation of frontends (React SPAs) and backend (Flask monolith)
- RESTful API design for rule CRUD, execution, debugging
- Adapter pattern for LLM service (easily swap models)
- Repository pattern for database and vectorstore abstractions
d. Key Technologies
- Python, Flask, SQLAlchemy, FAISS
- React, Redux, Webpack, Vite
- Code Llama 2 (LLM)
- SQLite

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser UI"
        QSPA["React SPA\n(query-builder)"]:::frontend
        ALB["Advanced Logic Builder\nWidget"]:::frontend
        SRP["Server-Rendered Pages\n(Jinja2 templates)"]:::frontend
        Static["Static Assets\n(CSS/JS/Images)"]:::frontend
    end

    subgraph "Backend Services"
        API["Flask API & Template Routes\n(app.py)"]:::backend
        Model["Business Logic & Rule Engine\n(model.py)"]:::backend
        Ingest["Data Ingestion & Store Population\n(ingest.py)"]:::backend
        Req["Requirements\n(requirements.txt)"]:::backend
    end

    subgraph "Build & Config"
        QC["Query Builder Config\n(webpack.config.js)"]:::backend
        VC["Advanced Logic Builder Config\n(vite.config.ts)"]:::backend
        QPkg["query-builder/package.json"]:::backend
        ALPkg["Advanced-Logic-Builder/package.json"]:::backend
    end

    subgraph "Data Stores"
        SQLite["SQLite DB\n(database.db)"]:::datastore
        InstanceDB["Instance SQLite DB\n(instance/database.db)"]:::datastore
        FAISS["FAISS Vectorstore\n(vectorstore/db_faiss/)"]:::datastore
    end

    LLM["LLM Service\n(Code Llama 2)"]:::external

    QSPA -->|HTTP REST| API
    ALB -->|HTTP REST| API
    SRP -->|Form POST / Template| API
    API -->|serves assets| Static
    API -->|invokes| Model
    API -->|triggers ingest| Ingest
    Req -->|defines deps| API

    Model -->|SQL/CRUD| SQLite
    Model -->|SQL/CRUD| InstanceDB
    Model -->|vector queries| FAISS
    Model -->|calls| LLM
    LLM -->|returns rule outputs| Model

    Ingest -->|populates| SQLite
    Ingest -->|populates| FAISS

    API -->|response| QSPA
    API -->|response| SRP

    QC -->|build pipeline| QSPA
    QPkg -->|defines deps| QSPA
    VC -->|build pipeline| ALB
    ALPkg -->|defines deps| ALB

    click QSPA "https://github.com/abhishek-mallick/decision-hub/tree/master/query-builder/"
    click ALB "https://github.com/abhishek-mallick/decision-hub/tree/master/Advanced-Logic-Builder/"
    click SRP "https://github.com/abhishek-mallick/decision-hub/tree/master/templates/"
    click Static "https://github.com/abhishek-mallick/decision-hub/tree/master/static/"
    click API "https://github.com/abhishek-mallick/decision-hub/blob/master/app.py"
    click Model "https://github.com/abhishek-mallick/decision-hub/blob/master/model.py"
    click Ingest "https://github.com/abhishek-mallick/decision-hub/blob/master/ingest.py"
    click Req "https://github.com/abhishek-mallick/decision-hub/blob/master/requirements.txt"
    click SQLite "https://github.com/abhishek-mallick/decision-hub/blob/master/database.db"
    click InstanceDB "https://github.com/abhishek-mallick/decision-hub/blob/master/instance/database.db"
    click FAISS "https://github.com/abhishek-mallick/decision-hub/tree/master/vectorstore/db_faiss/"
    click QC "https://github.com/abhishek-mallick/decision-hub/blob/master/query-builder/webpack.config.js"
    click VC "https://github.com/abhishek-mallick/decision-hub/blob/master/Advanced-Logic-Builder/vite.config.ts"
    click QPkg "https://github.com/abhishek-mallick/decision-hub/blob/master/query-builder/package.json"
    click ALPkg "https://github.com/abhishek-mallick/decision-hub/blob/master/Advanced-Logic-Builder/package.json"

    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#E6FFE6,stroke:#228B22,color:#228B22;
    classDef datastore fill:#FFF4E6,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F3E6FF,stroke:#8A2BE2,color:#8A2BE2;
```
