# krey-yon/cliven architecture

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

- Interactive diagram: https://gitdiagram.com/krey-yon/cliven
- Repository: https://github.com/krey-yon/cliven

## Overview

##### Project type and purpose
- This is a command-line tool (Cliven) implementing a Retrieval-Augmented Generation (RAG) pipeline for chatting with PDF documents using fully local services.
- It orchestrates PDF extraction, text chunking, embedding, vector storage (ChromaDB), and LLM inference (Ollama + Gemma models).

##### File structure
- Top-level:
- `main/` – core CLI application modules
- `utils/` – helper modules for chunking, parsing, embedding, and vector DB operations
- `docker-compose.yml` – orchestration of ChromaDB and Ollama services
- `setup.py`, `requirements.txt` – packaging and dependencies
- Key patterns:
- Layered design: CLI layer (`main/`), processing layer (`utils/`), persistent/external services (Docker).
- RAG pipeline flow from PDF → chunks → embeddings → vector store → query engine → LLM.

##### README for additional insights
- Describes a five-stage architecture: PDF Parser, Text Chunker, Embedder, Vector DB, Chat Engine.
- Enumerates external services: ChromaDB and Ollama (with lightweight/high-performance models).
- Highlights configuration via environment variables and Docker Compose.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Interface\n(main/cliven.py)"]:::cli

    CLI -->|"ingest command"| Parser["PDF Parser\n(utils/parser.py)"]:::processing
    Parser --> Chunker["Text Chunker\n(utils/chunker.py)"]:::processing
    Chunker --> Embedder["Embedder\n(utils/embedder.py)"]:::processing
    Embedder --> VDBClient["Vector DB Client\n(utils/vectordb.py)"]:::processing
    VDBClient --> Chroma[(ChromaDB Service\nlocalhost:8000)]:::service

    CLI -->|"chat command"| ChatEngine["Chat Engine\n(main/chat.py)"]:::cli
    ChatEngine -->|"query request\n(vector search)"| Chroma
    Chroma -->|"results\n(top-N chunks)"| ChatEngine
    ChatEngine -->|"prompt\n(HTTP:11434)"| Ollama["Ollama Service\nlocalhost:11434"]:::service
    Ollama -->|"response"| ChatEngine
    ChatEngine -->|"reply"| CLI

    click CLI "https://github.com/krey-yon/cliven/blob/main/main/cliven.py"
    click ChatEngine "https://github.com/krey-yon/cliven/blob/main/main/chat.py"
    click Parser "https://github.com/krey-yon/cliven/blob/main/utils/parser.py"
    click Chunker "https://github.com/krey-yon/cliven/blob/main/utils/chunker.py"
    click Embedder "https://github.com/krey-yon/cliven/blob/main/utils/embedder.py"
    click VDBClient "https://github.com/krey-yon/cliven/blob/main/utils/vectordb.py"
    click Chroma "https://github.com/krey-yon/cliven/blob/main/docker-compose.yml"
    click Ollama "https://github.com/krey-yon/cliven/blob/main/docker-compose.yml"

    classDef cli fill:#DDEEFF,stroke:#3A7CA5,color:#000;
    classDef processing fill:#EEFFEE,stroke:#2F8F2F,color:#000;
    classDef service fill:#FFFFDD,stroke:#A58300,color:#000;
```
