# ngz91/eunomia architecture

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

- Interactive diagram: https://gitdiagram.com/ngz91/eunomia
- Repository: https://github.com/ngz91/eunomia

## Overview

##### Project Type and Purpose
- Eunomia is a Python‐based CLI tool for **locally analyzing code via a GPT4All LLM**.
- It leverages Langchain for chunking and embeddings, Chroma as a local vector store, and a GPT4All or LlamaCpp model for query answering.
- Key use cases: ingest a target codebase into a vector database, then interactively query it without any internet.

##### High‐Level Architectural Components
a. **CLI Entry Point** (Eunomia.py)
- Parses commands (`ingest`, `start`).
- Loads environment variables from `.env`.
b. **Configuration Module** (`src/constants.py`)
- Reads and validates settings: `PERSIST_DIRECTORY`, `LLM`, `BACKEND`, embedding model name, chunk sizes, ignore list.
c. **Ingestion Pipeline** (`src/ingest.py`)
- File System Scanner: reads files in working directory, honoring `IGNORE_FOLDERS`.
- Text Splitter: splits each document into chunks (via Langchain code splitter).
- Embedding Generator: uses SentenceTransformers to embed each chunk.
- Vector Store Writer: writes embeddings + metadata into a local Chroma store.
d. **Query/Interaction Pipeline** (handled in Eunomia.py under `start`)
- Vector Store Loader: re‐loads Chroma store from `PERSIST_DIRECTORY`.
- Retriever: Langchain Retriever that takes user query, finds top‐N relevant chunks.
- LLM Model Loader: loads GPT4All / LlamaCpp model via the specified backend and model file.
- Q&A Chain: feeds retrieved chunks + user question into the LLM, streams or returns the answer.
e. **Persistent Storage**
- Local file system for: vector store files (Chroma), downloaded embeddings models (SentenceTransformers), downloaded GPT4All model binaries.
f. **External Dependencies**
- Langchain, Chroma (vector DB), SentenceTransformers, GPT4All / LlamaCpp C++ backend.

##### Relationships & Data Flows
- User runs `eunomia ingest` → CLI → Config → Ingestion Pipeline → produces Vector Store in FS.
- User runs `eunomia start` → CLI → Config → loads Vector Store + LLM Model → on each query: Retriever → Q&A Chain → LLM → reply.
- CLI → Config
- CLI → Ingest Module → File System → Text Splitter → Embeddings → Vector Store
- CLI → Query Module → Vector Store → Retriever → LLM Model → Output

##### Architectural Patterns
- **Pipeline Pattern** for the ingest workflow (sequential stages: load → split → embed → store).
- **Layered/Modular** separation: configuration, ingestion, retrieval, model inference.
- CLI-driven orchestration: a single‐process, script-based architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI and Configuration
    CLI["CLI Entrypoint\n(Eunomia.py)"]:::internal
    click CLI "https://github.com/ngz91/eunomia/blob/master/Eunomia.py"
    Config["Config Loader\n(src/constants.py)"]:::internal
    click Config "https://github.com/ngz91/eunomia/blob/master/src/constants.py"
    CLI --> Config

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        IngestMod["Ingestion Pipeline\n(src/ingest.py)"]:::internal
        click IngestMod "https://github.com/ngz91/eunomia/blob/master/src/ingest.py"
        FS["1. File System Scanner"]:::internal
        TS["2. Text Splitter"]:::internal
        ES["3. Embedding Service"]:::internal
        VW["4. Vector Store Writer"]:::internal
        IngestMod --> FS --> TS --> ES --> VW --> Chroma["Local Vector Store\n(Chroma)"]:::external
    end
    Config --> IngestMod

    %% Query Pipeline
    subgraph "Query Pipeline"
        QueryMod["Query & Start\n(Eunomia.py)"]:::internal
        click QueryMod "https://github.com/ngz91/eunomia/blob/master/Eunomia.py"
        VS["Vector Store Loader"]:::internal
        RET["Retriever"]:::internal
        LLM["LLM Model & Inference"]:::external
        Answer["Answer to User"]:::internal
        QueryMod --> VS --> RET --> LLM --> Answer
    end
    Config --> QueryMod

    %% Persistent Storage
    FSStore["Local FS\n(models & store)"]:::fs
    VW --> FSStore
    FSStore --> VS
    FSStore --> LLM

    %% Project Files
    subgraph "Project Files"
        Env["Environment Config\n(example.env)"]:::fs
        click Env "https://github.com/ngz91/eunomia/blob/master/example.env"
        Req["Dependencies\n(requirements.txt)"]:::fs
        click Req "https://github.com/ngz91/eunomia/blob/master/requirements.txt"
        Readme["Documentation\n(README.md)"]:::fs
        click Readme "https://github.com/ngz91/eunomia/blob/master/README.md"
        License["License\n(LICENSE)"]:::fs
        click License "https://github.com/ngz91/eunomia/tree/master/LICENSE"
        GitIgnore["Git Ignore\n(.gitignore)"]:::fs
        click GitIgnore "https://github.com/ngz91/eunomia/blob/master/.gitignore"
    end

    %% Legend
    subgraph "Legend"
        A["Internal Modules"]:::internal
        B["External Services"]:::external
        C["File System / Persistence"]:::fs
    end

    classDef internal fill:#b2f2bb,stroke:#2f8f34,color:#000;
    classDef external fill:#bee3f8,stroke:#1f5f8a,color:#000;
    classDef fs fill:#e0e0e0,stroke:#888888,color:#000;
```
