# bigdatawirtz/semanticsearch architecture

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

- Interactive diagram: https://gitdiagram.com/bigdatawirtz/semanticsearch
- Repository: https://github.com/bigdatawirtz/semanticsearch

## Overview

This repo is a **single-process Python web app** that provides:
- **Document ingestion**: upload **JSON documents** via a **Gradio** UI
- **Vector indexing + retrieval**: store embeddings in **ChromaDB (in-memory)**
- **Semantic search**: query → retrieve most relevant document(s)
- **Optional RAG QA**: send the **question + retrieved JSON** to a **local Ollama server** (`http://localhost:11434`) to generate an answer

Key architectural implication called out by the README: **everything is in RAM and disappears when the app stops** (no persistent DB volume unless you add one).

##### File structure to architectural components
From the tree:

- `semanticsearch.py`
The entire app: Gradio UI + upload handling + validation + embedding + ChromaDB indexing + retrieval + (optional) Ollama call.

- `samples/*.json`

- `requirements.txt`

- `Dockerfile`
Deployment mode: app can run **locally** or inside a **container**, exposing **7860**.

##### Gradio Web Server / UI Layer
- Tabs: upload + search (per README)
- Accepts files and queries, displays results

##### Upload & JSON Validation
- Ensures JSON is valid (explicit feature)
- Parses JSON into a canonical text/string representation used for embeddings + display

##### Embedding / Vectorization Component
- Takes JSON (or extracted text) and produces embeddings

##### ChromaDB (In-Memory Vector Store)
- Stores document embeddings + metadata
- Supports similarity search
- Important annotation: **ephemeral / RAM-only**

##### Retrieval / Ranking
- Executes semantic query against ChromaDB
- Returns top-k document(s) (README implies “most relevant document” for RAG)

##### RAG Prompt Builder (Context Assembler)
- Builds a context payload: question + retrieved JSON doc
- This is a distinct logical step even if it’s just a few lines in code

##### Ollama Client
- HTTP call to Ollama server (`http://localhost:11434`)
- Default model per README: `llama3.3` (include as a label/annotation)

##### External service boundary
- **Ollama Server (Local LLM Runtime)**
- Exposes HTTP API on **11434**
- Generates answer conditioned on provided context

##### Deployment boundary (optional but recommended)
- **Docker Container** running the Python app, exposing **7860**
- In Docker mode, Ollama may be:
- **Outside** the container on the host (common), requiring host networking or `host.docker.internal`-style access

##### UI / app
- **Browser → Gradio App**: `HTTP :7860`
(Upload JSON, submit search query, ask QA)

##### Ollama Server → Ollama Client → Gradio UI: answer text

- **Single-process, modular internal components**: UI + indexing + retrieval + LLM call all in one Python runtime.
- **Ephemeral state**: ChromaDB in-memory store; no persistence.
- **RAG pattern**: retrieve → augment prompt → generate.
- **Local-first / offline-ish**: relies on local Ollama, not a hosted LLM (important boundary condition).

Explicit annotations:
- “Vector DB = RAM-only; reset on restart”
- “Ollama dependency: must be running at `localhost:11434`”
- “App exposed at `localhost:7860`”

Show:
- User browser
- Docker container OR local Python process (two variants or a note)
- Ollama server
- Ports 7860 and 11434
This answers: “What runs where and how does it connect?”

- Gradio UI
- Validation/Parser
- Embedding
- ChromaDB
- Retrieval
- Prompt Builder
- Ollama client
This answers: “What are the main responsibilities and boundaries inside `semanticsearch.py`?”

Two sequences are enough:
- Upload → index
- Ask question → retrieve → (optional) Ollama generation
This answers: “In what order do calls happen and what data moves?”

##### Diagramming conventions (make it “principal-engineer grade”)
Elements explicitly:

##### Clear labels
- component name
- key tech (e.g., “Gradio”, “ChromaDB”)
- statefulness (“in-memory”)

- Ports/protocol where relevant: `HTTP :7860`, `HTTP :11434`

##### Don’t overthink granularity—split aggressively
Even if `semanticsearch.py` is one file, represent each responsibility as a separate component. This matches the project’s real conceptual architecture and makes future refactors obvious (e.g., extracting retrieval, storage, LLM client into modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — Deployment / Context
  %% =========================
  subgraph D1["Diagram 1 — Deployment / Context (C4 L1-ish)"]
    direction TB

    U["User Browser\n(Upload JSON / Search / QA)"]:::external

    subgraph L["Option A: Local Run"]
      direction TB
      P["Semanticsearch App\n(Python 3.11 single process)"]:::app
      O["Ollama Server\n(Local LLM runtime)\nHTTP :11434"]:::external
    end

    subgraph C["Option B: Docker Run (recommended)"]
      direction TB
      subgraph DC["Docker Container\n(exposes :7860)"]
        direction TB
        P2["Semanticsearch App\n(Python 3.11 single process)"]:::app
      end
      O2["Ollama Server\n(usually on host or separate container)\nHTTP :11434"]:::external
    end

    N1["Note: App UI served by Gradio\nHTTP :7860"]:::note
    N2["Note: Vector DB is RAM-only\nresets on restart"]:::note
    N3["Note: Ollama must be reachable\nat localhost:11434 (or host.docker.internal)"]:::note

    U -->|"HTTP_:7860"| P
    P -.->|"HTTP_:11434 (optional_RAG)"| O

    U -->|"HTTP_:7860"| P2
    P2 -.->|"HTTP_:11434 (optional_RAG)"| O2

    P --> N1
    P --> N2
    O --> N3
  end

  %% =========================
  %% Diagram 2 — Container/Component (inside semanticsearch.py)
  %% =========================
  subgraph D2["Diagram 2 — App Component View (C4 L2/3-ish)"]
    direction TB

    B2["User Browser"]:::external

    subgraph APP["Semanticsearch App (Python 3.11)\nSingle process: UI + indexing + retrieval + optional RAG"]
      direction TB

      G["Gradio Web Server / UI Layer\n(Upload tab + Search/QA tab)\nHTTP :7860"]:::ui

      subgraph ING["Ingestion / Indexing Flow"]
        direction TB
        UP["Upload Handling\n(receive JSON file)"]:::component
        JV["JSON Validation / Parser\n(validate + canonicalize JSON→text)"]:::component
        E["Embedding Function / Encoder\n(embed documents + queries)"]:::component
        V[("ChromaDB Vector Store\n(in-memory / ephemeral)")]:::datastore
      end

      subgraph RET["Search + Retrieval Flow"]
        direction TB
        R["Retrieval / Ranking\n(embed query + similarity search + top-k docs)"]:::component
      end

      subgraph RAG["Optional RAG QA Flow"]
        direction TB
        PB["RAG Prompt Builder\n(question + retrieved JSON context)"]:::component
        OC["Ollama Client\nHTTP caller (model=llama3.3)"]:::component
      end
    end

    OLL["Ollama Server\n(Local LLM runtime)\nHTTP :11434"]:::external
    SAMP["Sample JSON Documents\n(samples/*.json)"]:::data
    REQ["Python Dependencies\n(requirements.txt)"]:::meta
    DOC["Docs / Usage Notes\n(README: ports, Ollama URL/model)"]:::meta
    DKR["Container Build\n(Dockerfile: expose 7860)"]:::meta

    %% UI boundary
    B2 -->|"HTTP_:7860"| G

    %% Ingestion / indexing
    G -->|"upload_JSON"| UP
    UP -->|"parse_validate"| JV
    JV -->|"canonical_text"| E
    E -->|"upsert_vectors+metadata"| V

    %% Search
    G -->|"semantic_search_query"| R
    R -->|"embed_query"| E
    R -->|"similarity_search"| V
    V -->|"top-k_docs+scores"| R
    R -->|"results_to_UI"| G

    %% Optional RAG
    G -->|"QA_question (optional)"| R
    R -->|"top_doc_for_context"| PB
    PB -->|"build_prompt"| OC
    OC -.->|"HTTP_:11434 generate (llama3.3)"| OLL
    OLL -.->|"answer_text"| OC
    OC -->|"answer_to_UI"| G

    %% Supporting repo artifacts
    SAMP -.->|"example_payloads"| UP
    REQ -.->|"declares_deps"| APP
    DOC -.->|"explains_ports+Ollama"| APP
    DKR -.->|"containerizes"| APP
  end

  %% =========================
  %% Diagram 3 — Sequence (runtime behavior)
  %% =========================
  subgraph D3["Diagram 3 — Runtime Sequence (Upload/Index + QA/RAG)"]
    direction TB

    subgraph S1["Sequence A: Upload → Index"]
      direction TB
      sU["Browser"]:::external
      sG["Gradio UI / Server"]:::ui
      sJV["JSON Validation / Parser"]:::component
      sE["Embedding Function"]:::component
      sV[("ChromaDB (in-memory)")]:::datastore

      sU -->|"upload_JSON (HTTP_:7860)"| sG
      sG -->|"validate_parse"| sJV
      sJV -->|"canonical_text"| sE
      sE -->|"upsert_vectors+metadata"| sV
      sG -->|"status/result"| sU
    end

    subgraph S2["Sequence B: Ask → Retrieve → (Optional) Generate"]
      direction TB
      qU["Browser"]:::external
      qG["Gradio UI / Server"]:::ui
      qR["Retrieval / Ranking"]:::component
      qE["Embedding Function"]:::component
      qV[("ChromaDB (in-memory)")]:::datastore
      qPB["Prompt Builder"]:::component
      qOC["Ollama Client"]:::component
      qOLL["Ollama Server (HTTP_:11434)"]:::external

      qU -->|"ask_question / search (HTTP_:7860)"| qG
      qG -->|"query"| qR
      qR -->|"embed_query"| qE
      qR -->|"similarity_search"| qV
      qV -->|"top-k_docs"| qR
      qR -->|"retrieved_docs+scores"| qG

      qR -->|"top_doc_as_context (optional_RAG)"| qPB
      qPB -->|"prompt: question+JSON"| qOC
      qOC -.->|"generate (model=llama3.3)"| qOLL
      qOLL -.->|"answer_text"| qOC
      qOC -->|"answer"| qG
      qG -->|"render_results"| qU
    end
  end

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click APP "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click P "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click P2 "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click G "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click UP "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click JV "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click E "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click V "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click R "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click PB "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click OC "https://github.com/bigdatawirtz/semanticsearch/blob/main/semanticsearch.py"
  click SAMP "https://github.com/bigdatawirtz/semanticsearch/tree/main/samples/"
  click REQ "https://github.com/bigdatawirtz/semanticsearch/blob/main/requirements.txt"
  click DKR "https://github.com/bigdatawirtz/semanticsearch/tree/main/Dockerfile"
  click DOC "https://github.com/bigdatawirtz/semanticsearch/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffe6cc,stroke:#b26b00,stroke-width:1.5px,color:#1f1f1f
  classDef app fill:#e6f0ff,stroke:#1f5fbf,stroke-width:1.8px,color:#0b1a33
  classDef ui fill:#e8fff3,stroke:#1f7a4d,stroke-width:1.6px,color:#0b2b1a
  classDef component fill:#f2f2ff,stroke:#5a55d6,stroke-width:1.2px,color:#16143a
  classDef datastore fill:#fff2f2,stroke:#c23b3b,stroke-width:1.8px,color:#3a0f0f
  classDef note fill:#fffbd6,stroke:#b59b00,stroke-dasharray: 4 3,stroke-width:1.2px,color:#3a3300
  classDef meta fill:#f5f5f5,stroke:#666,stroke-dasharray: 3 3,stroke-width:1.1px,color:#222
  classDef data fill:#f0fff9,stroke:#2a8c6a,stroke-width:1.2px,color:#0b2b1a
```
