# thelalit/nlweb architecture

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

- Interactive diagram: https://gitdiagram.com/thelalit/nlweb
- Repository: https://github.com/thelalit/nlweb

## Overview

##### Project type and purpose
- NLWeb is an open-source, full-stack Python service that implements a simple “natural language” REST/MCP API for websites.
- It provides:
- A backend pipeline (pre-retrieval → retrieval → embedding/LLM → ranking/generation)
- Connectors to vector stores (Qdrant, Snowflake, Milvus, Azure AI Search) and LLM providers (OpenAI, Azure OAI, Gemini, Anthropic, Inception)
- A lightweight webserver + static JavaScript UI for demos
- Data-loading tools for schema.org, RSS, JSONL ingestion into vector indexes

##### File structure
- Top-level directories:
- code/ – main Python application
– config/ – YAML and Python config loader
– core/ – request router, state machine, handlers, ranking, answer generation
– pre_retrieval/ – query analysis, memory, decontextualization, relevance detection
– retrieval/ – client abstractions for Qdrant, Milvus, Snowflake, Azure Search
– embedding/ – abstraction layer over embedding providers
– llm/ – abstraction over LLM providers
– prompts/ – prompt templates and runner
– webserver/ – HTTP/MCP server entrypoint and static handler
– tools/ – scripts for loading data into vector stores
– utils/ – logging, Snowflake helper, generic utilities
- static/ – JavaScript/HTML chat UI and widgets
- docs/, demo/, data/ – documentation, examples, sample schemas
- Key config files: `.env.template`, `config_*.yaml`
- Entry points: `code/WebServer.py` (server), `code/chatbot_interface.py` (CLI/test harness)

##### README insights
- Two main pieces: the protocol definition (REST/MCP) and a reference implementation
- Encourages community to reuse protocol and swap in production-grade UIs or data sources
- Emphasizes modular connectors for storage/LLMs and a clear “life of a chat query” flow

1. Client Layer
- Web UI (static JS/chat widgets)
- External agents/CLI (MCP clients)
2. Webserver / API Layer
- HTTP / MCP endpoint (`WebServer.py`, `static_file_handler.py`)
- Config loader & environment (.env)
3. Core Pipeline Controller
- Request router (`baseHandler.py`, `mcp_handler.py`)
- State management (`state.py`)
4. Pre-Retrieval Module
- Query analyzer, decontextualizer, memory (`analyze_query.py`, `memory.py`, etc.)
5. Retrieval Module
- Vector store clients (Qdrant, Milvus, Snowflake, Azure Search)
- Retriever orchestration
6. Embedding Module
- Embedding provider abstraction (OpenAI, Gemini, Azure OAI, Snowflake)
7. LLM Module
- LLM provider abstraction (OpenAI, Azure, Anthropic, Inception)
8. Post-Processing
- Ranking (`post_ranking.py`, `ranking.py`), answer generation (`generate_answer.py`)
9. Tools & Data Ingestion
- Scripts for data loading (RSS→schema.org JSONL → vector DB)
10. Observability & Config
- Logging, metrics, `config/*.yaml`, `utils/logger.py`

1. Client → Webserver (HTTP/MCP ask request)
2. Webserver → Core Router
3. Core Router → Pre-Retrieval → Retrieval → Embedding → LLM
4. LLM → Post-Processing → Core Router → Webserver
5. Webserver → Client (JSON + schema.org output)
6. Tools → Data Stores (vector DB / Snowflake) feeding Retrieval

c. Architectural patterns & design principles
- Pipeline pattern: clear, pluggable stages (pre-retrieval, retrieval, embed, LLM, ranking)
- Adapter/plugin architecture: connectors for each LLM and vector store live behind a common interface
- Configuration-driven: YAML + environment variables for swapping providers
- Single code base supports multiple deployment targets (laptop → cloud)

d. Key technologies/frameworks
- Python 3
- HTTP/MCP interface (custom server in `WebServer.py`)
- Vector stores: Qdrant, Milvus, Snowflake, Azure Search
- LLM APIs: OpenAI, Azure OAI, Gemini, Anthropic, Inception
- Static JS UI (vanilla JS + HTML)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
      direction TB
      WebUI["Web UI"]:::client
      CLI["External Agents / CLI"]:::client
    end
    click WebUI "https://github.com/thelalit/nlweb/blob/main/static/index.html"
    click CLI "https://github.com/thelalit/nlweb/blob/main/code/chatbot_interface.py"

    %% Webserver / API Layer
    subgraph "Webserver / API Layer"
      direction TB
      WebServer["WebServer"]:::api
      StaticHandler["Static File Handler"]:::api
      StreamingWrapper["Streaming Wrapper"]:::api
      ConfigLoader["Config Loader & Env"]:::tools
    end
    click WebServer "https://github.com/thelalit/nlweb/blob/main/code/webserver/WebServer.py"
    click StaticHandler "https://github.com/thelalit/nlweb/blob/main/code/webserver/static_file_handler.py"
    click StreamingWrapper "https://github.com/thelalit/nlweb/blob/main/code/webserver/StreamingWrapper.py"
    click ConfigLoader "https://github.com/thelalit/nlweb/blob/main/code/config/config.py"

    %% Core Pipeline Controller
    subgraph "Core Pipeline Controller"
      direction TB
      BaseHandler["BaseHandler"]:::core
      MCPHandler["MCPHandler"]:::core
      State["State"]:::core
      FastTrack["FastTrack"]:::core
      WhoHandler["WhoHandler"]:::core
    end
    click BaseHandler "https://github.com/thelalit/nlweb/blob/main/code/core/baseHandler.py"
    click MCPHandler "https://github.com/thelalit/nlweb/blob/main/code/core/mcp_handler.py"
    click State "https://github.com/thelalit/nlweb/blob/main/code/core/state.py"
    click FastTrack "https://github.com/thelalit/nlweb/blob/main/code/core/fastTrack.py"
    click WhoHandler "https://github.com/thelalit/nlweb/blob/main/code/core/whoHandler.py"

    %% Modules
    subgraph "Pre-Retrieval Module"
      direction TB
      PreModule["Pre-Retrieval"]:::core
    end
    click PreModule "https://github.com/thelalit/nlweb/tree/main/code/pre_retrieval"

    subgraph "Retrieval Module"
      direction TB
      RetrievalModule["Retrieval"]:::core
    end
    click RetrievalModule "https://github.com/thelalit/nlweb/tree/main/code/retrieval"

    subgraph "Embedding Module"
      direction TB
      EmbeddingModule["Embedding"]:::core
    end
    click EmbeddingModule "https://github.com/thelalit/nlweb/tree/main/code/embedding"

    subgraph "LLM Module"
      direction TB
      LLMModule["LLM"]:::core
    end
    click LLMModule "https://github.com/thelalit/nlweb/tree/main/code/llm"

    subgraph "Post-Processing"
      direction TB
      PostProcessing["Ranking & Generation"]:::core
    end
    click PostProcessing "https://github.com/thelalit/nlweb/blob/main/code/core/generate_answer.py"

    %% Tools & Ingestion
    subgraph "Tools & Data Ingestion"
      direction TB
      ToolsModule["Tools & Ingestion"]:::tools
    end
    click ToolsModule "https://github.com/thelalit/nlweb/tree/main/code/tools"

    %% Observability & Utilities
    subgraph "Observability & Utilities"
      direction TB
      Observability["Logging & Config"]:::tools
    end
    click Observability "https://github.com/thelalit/nlweb/blob/main/code/utils/logger.py"

    %% External Services
    subgraph "External Services"
      direction TB
      VectorDBs["Vector Stores"]:::external
      LLMAPIs["LLM APIs"]:::external
    end

    %% Data Flow
    WebUI -->|"1: HTTP/MCP Request"| WebServer
    CLI -->|"1: MCP Request"| WebServer
    WebServer -->|"2: Load Config"| ConfigLoader
    WebServer -->|"3: Route Request"| BaseHandler
    BaseHandler -->|"4: Pre-Retrieval"| PreModule
    PreModule -->|"5: Retrieval"| RetrievalModule
    RetrievalModule -->|"6: Embedding"| EmbeddingModule
    EmbeddingModule -->|"7: LLM Call"| LLMModule
    LLMModule -->|"8: Post-Processing"| PostProcessing
    PostProcessing -->|"9: Return to Core"| BaseHandler
    BaseHandler -->|"10: Respond"| WebServer
    WebServer -->|"11: JSON Response"| WebUI
    ToolsModule -->|"Ingest Data"| VectorDBs
    ConfigLoader -->|"Setup Logging"| Observability

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef tools fill:#D3D3D3,stroke:#333,stroke-width:1px
```
