# kev2010/book-llm architecture

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

- Interactive diagram: https://gitdiagram.com/kev2010/book-llm
- Repository: https://github.com/kev2010/book-llm

## Overview

##### Project Overview
- BookLLM is a full-stack answer engine that brings an autobiography to life using Retrieval-Augmented Generation (RAG). Its main goal is to allow users to chat with an AI that leverages the text of the book (with contextual retrieval) to produce intelligent responses.
- The architecture is split into a frontend (client) built with Next.js and a backend (server) written in Python, which implements various RAG and LLM-related services.

##### Main Components
a. Client/Frontend Component:
- “client” directory as the UI layer.
- Next.js framework (files such as client/src/pages/_app.js, _document.js, and index.js) that bootstrap and render the user interface.
- Static assets and styling (Tailwind config, globals.css, fonts) that support the presentation layer.
- Existence of client-side API endpoints (client/src/pages/api/getAIResponse.js) that are used to forward or translate UI interactions into backend calls.

b. Server/Backend Component:
- “server” directory as the primary processing and business logic layer.
- Main entry point (server/main.py) which likely starts the server application.
- Modules in the services folder as separate but related components that manage:
- LLM interactions (llm_service.py)
- Retrieval (rag_service.py, rag_bm25.py)
- Chunking of the book text (rag_chunker.py)
- Generating or handling embeddings (rag_embeddings.py)

##### Relationships and Data Flow
- Within the backend, show interactions among the services. For instance:
- The rag_service likely orchestrates the retrieval process by calling rag_chunker, rag_bm25, and rag_embeddings to fetch and format the relevant book content.
- The llm_service then uses this contextual data to generate a conversation response that is returned through the API call.

##### Architectural Patterns & Design Principles
- Modularity: Separate components (e.g., UI, API layer, backend services) are individually responsible for well-defined tasks.
- Separation of concerns: The Next.js client is only responsible for view rendering and user interactions (enhanced by custom hooks such as auto scroll and multiline handling), while the Python backend handles the heavy-lifting for LLM and RAG functions.
- Integration patterns: The client and server communicate (likely via REST or HTTP endpoints) whereby the UI is decoupled from the backend logic.
- Marking key technologies and libraries (Next.js, Tailwind, Python, and any LLM/RAG libraries used in the server).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Client)"
        NextUI["Next.js UI"]:::frontend
        UIComp["UI Subcomponents"]:::frontend
        APIEndpoint["API Endpoint (getAIResponse.js)"]:::frontend
        Assets["Static Assets & Styling"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Server)"
        MainEntry["Server Main Entry"]:::backend
        LLMService["LLM Service"]:::backend
        RAGOrch["RAG Orchestrator (rag_service)"]:::backend
        RAG_BM25["RAG BM25"]:::backend
        RAG_Chunker["RAG Chunker"]:::backend
        RAG_Embeddings["RAG Embeddings"]:::backend
    end

    %% Data Flow in Frontend
    NextUI -->|"Initiates Chat"| UIComp
    UIComp -->|"Sends Request"| APIEndpoint

    %% Communication from Frontend to Backend
    APIEndpoint -->|"API Call"| MainEntry

    %% Backend Processing Flow
    MainEntry -->|"Invokes"| LLMService
    LLMService -->|"Requests Retrieval"| RAGOrch
    RAGOrch -->|"BM25 Processing"| RAG_BM25
    RAGOrch -->|"Chunking"| RAG_Chunker
    RAGOrch -->|"Embedding Generation"| RAG_Embeddings
    LLMService -->|"Generates Response"| MainEntry

    %% Response Flow back to Frontend
    MainEntry -->|"Returns Response"| APIEndpoint
    APIEndpoint -->|"Displays Reply"| NextUI

    %% Styling for Frontend and Backend
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend Components
    click NextUI "https://github.com/kev2010/book-llm/tree/main/client/src/pages"
    click UIComp "https://github.com/kev2010/book-llm/tree/main/client/src/components"
    click APIEndpoint "https://github.com/kev2010/book-llm/blob/main/client/src/pages/api/getAIResponse.js"
    click Assets "https://github.com/kev2010/book-llm/tree/main/client/public/assets"

    %% Click Events for Backend Components
    click MainEntry "https://github.com/kev2010/book-llm/blob/main/server/main.py"
    click LLMService "https://github.com/kev2010/book-llm/blob/main/server/services/llm_service.py"
    click RAGOrch "https://github.com/kev2010/book-llm/blob/main/server/services/rag_service.py"
    click RAG_BM25 "https://github.com/kev2010/book-llm/blob/main/server/services/rag_bm25.py"
    click RAG_Chunker "https://github.com/kev2010/book-llm/blob/main/server/services/rag_chunker.py"
    click RAG_Embeddings "https://github.com/kev2010/book-llm/blob/main/server/services/rag_embeddings.py"
```
