# duembi/silsilsils architecture

> Architecture diagram of the GitHub repository duembi/silsilsils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duembi/silsilsils
- Repository: https://github.com/duembi/silsilsils

## Overview

#### Purpose and shape
This is a small, script-oriented chatbot/RAG repository. The numbered Python files appear to represent progressive stages: basic chat, data preparation, vector storage, retrieval/querying, context assembly, RAG chat, optimization, and conversation-history UI. The README provides no additional implementation detail.

#### Entry points
Likely runnable entry points are the top-level scripts rather than a package or service launcher:
- Basic chatbot: `002.Chatbot.py`
- Data/vector/RAG stages: `003.DataPreparation.py`, `004.VectorDB.py`, `006.Query.py`, `007.Context.py`, `008. RAGChatbot.py`
- Optimization and history experiences: `010.RAGOptimization.py`, `011.ConversationHistory.py`, `012.WebUI_ConversationHistory.py`
- `005.py` is an unlabeled intermediate stage and should be inspected before treating it as a stable entry point.

#### Chat and RAG pipeline
The core architecture is likely a retrieval-augmented generation flow:
1. Prepare source data in `003.DataPreparation.py`.
2. Create or populate vector storage in `004.VectorDB.py`.
3. Accept/search a user query in `006.Query.py`.
4. Convert retrieved material into model context in `007.Context.py`.
5. Generate a grounded chat response in `008. RAGChatbot.py`.

The major boundary is between offline/ingestion-oriented work (`003.DataPreparation.py`, `004.VectorDB.py`) and interactive request-time retrieval/generation (`006.Query.py`, `007.Context.py`, `008. RAGChatbot.py`).

#### Conversation interfaces and state
`002.Chatbot.py` likely provides a non-RAG chatbot baseline, useful for separating direct model interaction from retrieval-backed responses. Conversation persistence or turn handling is introduced separately in `011.ConversationHistory.py`. `012.WebUI_ConversationHistory.py` appears to expose that stateful behavior through a web UI, making it the most likely user-facing interactive application entry point.

#### Optimization layer
`010.RAGOptimization.py` is the likely evaluation/tuning stage around the RAG pipeline. It should own choices such as retrieval quality, context size, prompt behavior, or response-quality tradeoffs, rather than duplicating ingestion or UI concerns. Its dependencies should flow toward the data/vector/query/context stages: `004.VectorDB.py`, `006.Query.py`, and `007.Context.py`.

#### Runtime and external boundaries
All visible implementation is top-level Python scripts; there is no package layout, deployment manifest, dependency file, or infrastructure definition in the supplied tree. External services cannot be confirmed from the repository metadata, but the architecture implies two material integrations that must be verified in code: an LLM/chat provider and a vector database or embedding/search backend. The web runtime/framework, if any, is most likely used by `012.WebUI_ConversationHistory.py`.

Main entry points: [`010.RAGOptimization.py`](https://github.com/duembi/silsilsils/blob/main/010.RAGOptimization.py) (RAG Optimization), [`006.Query.py`](https://github.com/duembi/silsilsils/blob/main/006.Query.py) (Query Retrieval), [`004.VectorDB.py`](https://github.com/duembi/silsilsils/blob/main/004.VectorDB.py) (Vector Storage), [`007.Context.py`](https://github.com/duembi/silsilsils/blob/main/007.Context.py) (Context Assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline ingestion"]
  node_data_prep["Data Preparation<br/>Python script"]
  node_vector_db[("Vector Storage<br/>Python script<br/>[004.VectorDB.py]")]
end

subgraph group_rag["RAG runtime"]
  node_query["Query Retrieval<br/>Python script<br/>[006.Query.py]"]
  node_context["Context Assembly<br/>Python script<br/>[007.Context.py]"]
  node_rag_chat["RAG Chatbot<br/>Python script<br/>[008. RAGChatbot.py]"]
  node_optimization["RAG Optimization<br/>Python script"]
end

subgraph group_interfaces["Chat interfaces"]
  node_basic_chat["Basic Chatbot<br/>Python script<br/>[002.Chatbot.py]"]
  node_history["Conversation History<br/>Python script"]
  node_web_ui["Web UI with History<br/>Python script"]
end

node_intermediate["Intermediate Stage<br/>Python script<br/>[005.py]"]
node_vector_backend[("Vector / Embedding Backend<br/>External integration")]
node_llm_provider{{"LLM / Chat Provider<br/>External integration"}}

node_data_prep -->|"prepared data"| node_vector_db
node_vector_db -->|"populate"| node_vector_backend
node_query -->|"search"| node_vector_backend
node_query -->|"retrieved material"| node_context
node_context -->|"grounding context"| node_rag_chat
node_rag_chat -->|"generation"| node_llm_provider
node_basic_chat -->|"direct chat"| node_llm_provider
node_optimization -.->|"retrieval tuning"| node_vector_db
node_optimization -.->|"evaluate retrieval"| node_query
node_optimization -.->|"tune context"| node_context
node_history -->|"conversation turns"| node_rag_chat
node_web_ui -->|"stateful interaction"| node_history

click node_basic_chat "https://github.com/duembi/silsilsils/blob/main/002.Chatbot.py"
click node_data_prep "https://github.com/duembi/silsilsils/blob/main/003.DataPreparation.py"
click node_vector_db "https://github.com/duembi/silsilsils/blob/main/004.VectorDB.py"
click node_intermediate "https://github.com/duembi/silsilsils/blob/main/005.py"
click node_query "https://github.com/duembi/silsilsils/blob/main/006.Query.py"
click node_context "https://github.com/duembi/silsilsils/blob/main/007.Context.py"
click node_rag_chat "https://github.com/duembi/silsilsils/blob/main/008.%20RAGChatbot.py"
click node_optimization "https://github.com/duembi/silsilsils/blob/main/010.RAGOptimization.py"
click node_history "https://github.com/duembi/silsilsils/blob/main/011.ConversationHistory.py"
click node_web_ui "https://github.com/duembi/silsilsils/blob/main/012.WebUI_ConversationHistory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_prep,node_vector_db toneBlue
class node_query,node_context,node_rag_chat,node_optimization toneAmber
class node_basic_chat,node_history,node_web_ui toneMint
class node_intermediate,node_vector_backend,node_llm_provider toneNeutral
```

## Components

### Offline ingestion

Prepares data and populates retrieval storage.

- [Data Preparation](https://github.com/duembi/silsilsils/blob/main/003.DataPreparation.py): Python script · Prepares source material for indexing. · `003.DataPreparation.py`
- [Vector Storage](https://github.com/duembi/silsilsils/blob/main/004.VectorDB.py): Python script · Creates or populates vector retrieval storage. · `004.VectorDB.py`

### RAG runtime

Retrieves evidence, builds context, and generates answers.

- [Query Retrieval](https://github.com/duembi/silsilsils/blob/main/006.Query.py): Python script · Accepts a query and searches indexed material. · `006.Query.py`
- [Context Assembly](https://github.com/duembi/silsilsils/blob/main/007.Context.py): Python script · Converts retrieved material into model context. · `007.Context.py`
- [RAG Chatbot](https://github.com/duembi/silsilsils/blob/main/008.%20RAGChatbot.py): Python script · Generates grounded responses using retrieval context. · `008. RAGChatbot.py`
- [RAG Optimization](https://github.com/duembi/silsilsils/blob/main/010.RAGOptimization.py): Python script · Tunes retrieval, context, and response-quality tradeoffs. · `010.RAGOptimization.py`

### Chat interfaces

Baseline and stateful user interaction scripts.

- [Basic Chatbot](https://github.com/duembi/silsilsils/blob/main/002.Chatbot.py): Python script · Direct, non-RAG chat baseline. · `002.Chatbot.py`
- [Conversation History](https://github.com/duembi/silsilsils/blob/main/011.ConversationHistory.py): Python script · Introduces conversation turn handling or persistence. · `011.ConversationHistory.py`
- [Web UI with History](https://github.com/duembi/silsilsils/blob/main/012.WebUI_ConversationHistory.py): Python script · Likely user-facing stateful chat entry point. · `012.WebUI_ConversationHistory.py`

### Other components

- [Intermediate Stage](https://github.com/duembi/silsilsils/blob/main/005.py): Python script · Unlabeled stage requiring inspection. · `005.py`
- **Vector / Embedding Backend**: External integration · Implied backend; implementation must be verified.
- **LLM / Chat Provider**: External integration · Implied model provider; implementation must be verified.

## Connections

- Data Preparation → Vector Storage: prepared data
- Vector Storage → Vector / Embedding Backend: populate
- Query Retrieval → Vector / Embedding Backend: search
- Query Retrieval → Context Assembly: retrieved material
- Context Assembly → RAG Chatbot: grounding context
- RAG Chatbot → LLM / Chat Provider: generation
- Basic Chatbot → LLM / Chat Provider: direct chat
- RAG Optimization → Vector Storage: retrieval tuning
- RAG Optimization → Query Retrieval: evaluate retrieval
- RAG Optimization → Context Assembly: tune context
- Conversation History → RAG Chatbot: conversation turns
- Web UI with History → Conversation History: stateful interaction
