# truera/trulens architecture

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

- Interactive diagram: https://gitdiagram.com/truera/trulens
- Repository: https://github.com/truera/trulens

## Overview

##### Primary Components
- Core Evaluation Engine – This is the heart of TruLens and is implemented in the “src/core/trulens” directory. It includes modules for instrumentation, feedback collection, database management (including migrations and ORM), session management, and utility functions.
- Application Integrations – TruLens includes multiple “apps” integrations (e.g., “src/apps/langchain”, “src/apps/llamaindex”, “src/apps/nemo”) which are built to work with various frameworks. These add instrumentation around specific LLM libraries or techniques.
- Connectors & Providers – There are dedicated modules for integrating with external systems and providers (e.g., “src/connectors/snowflake” and “src/providers/…” for bedrock, cortex, huggingface, openai, etc.). They support external data storage, API calls, or even model feedback endpoints.
- Benchmarking & Evaluation – The “src/benchmark” and “src/trulens_eval” directories house tooling for running experiments, generating test cases, and evaluating model performance. These enable end-to-end testing and comparative analysis.
- Auxiliary and Support Systems – Additional utility components include the “docs” for user guidance, “docker” configurations for containerized environments, “tests” covering unit, integration, and e2e test cases, and several tooling scripts (e.g., the Makefile, pre-commit hooks, and CI pipelines under .azure_pipelines).

##### Out the Data Flow and Relationships
- User Application/LLM App → Instrumented via TruLens – Your LLM application (or experimental prototype) interfaces with TruLens instrumentation. The wrapper “apps” intercepts calls or actions and forwards both inputs (prompts, models, responses) and feedback into the system.
- Core Engine → Feedback and Guardrails – Once instrumentation is in place, the core engine processes the collected data. This includes running feedback functions, applying guardrails, and potentially aggregating results on aspects like “Honest, Harmless and Helpful Evals” or the “RAG Triad.”
- Storage & Database Layer – The core engine uses internal database modules for logging events and storing evaluation results. This layer is maintained with migration scripts (located in “src/core/trulens/core/database/migrations”) and ORM utilities.
- External Connectors/Providers – Depending on your LLM framework and desired monitoring endpoints, TruLens integrates with external systems (e.g., Snowflake for logs/aggregation, various cloud LLM providers) through its connectors and providers components.
- Dashboard UI – The front-end dashboard (with React components and Python/Streamlit based backends in “src/dashboard/trulens/dashboard”) retrieves evaluation metrics and logs from the core engine or database, then displays them to the end user.

##### Architectural Patterns and Design Principles
- Modularization & Separation of Concerns – The file tree is organized into distinct modules (apps, core, dashboard, connectors, providers, benchmarks) that encapsulate each major concern.
- Extensibility – By separating connectors and providers into their own modules, TruLens is designed for easy integration with additional external services as needed.
- Instrumentation and Feedback Pipeline – The core processing pipeline manages the flow from instrumentation (embedded in various LLM libraries) to feedback handling and logging, then up to a UI dashboard for visualization.
- Testing & Benchmarking Emphasis – The extensive “tests” and “benchmark” directories confirm that quality assurance, performance evaluation, and experimental comparisons are a central design focus.

##### Specific Technologies and Frameworks
- Python Packaging with Pyproject.toml for most modules.
- React (with Vite, ESLint, Prettier) for the dashboard’s frontend.
- Deployment configurations (Docker, Azure pipelines) to support CI/CD.
- Support for multiple LLM frameworks such as LangChain, LlamaIndex, Nemo, and various provider APIs (e.g., Bedrock, Cortex, Huggingface).

##### Specific Elements to Embed
- Clear and Descriptive Labels – Each component (such as “Core Feedback Processing”, “Connector: Snowflake”, “Dashboard React Components”) should be explicitly labeled.
- Modular Boundaries – Show how the “apps”, “providers”, “dashboard”, “benchmark”, and “core” modules interrelate but remain distinct.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    A["LLM Application"]:::external

    %% Application Integrations
    subgraph "Application Integrations"
        B["LangChain Integration"]:::python
        C["LlamaIndex Integration"]:::python
        D["Nemo Integration"]:::python
    end

    %% Core Engine
    E["Core Evaluation Engine"]:::python

    %% Dashboard UI
    subgraph "Dashboard UI"
        F["Dashboard UI - Backend"]:::python
        G["Dashboard UI - React Frontend"]:::js
    end

    %% External Connectors & Providers
    subgraph "Connectors & Providers"
        H["Snowflake Connector"]:::python
        I["Bedrock Provider"]:::python
        J["Cortex Provider"]:::python
        K["Huggingface Provider"]:::python
        L["LangChain Provider"]:::python
        M["Litellm Provider"]:::python
        N["OpenAI Provider"]:::python
    end

    %% Benchmarking & Evaluation
    subgraph "Benchmarking & Evaluation"
        O["Benchmarking Tools"]:::python
        P["Extended Evaluation Tools"]:::python
    end

    %% Auxiliary & Support Systems
    subgraph "Auxiliary & Support"
        Q["Documentation"]:::aux
        R["Container & Deployment"]:::aux
        S["Testing Suites"]:::aux
        T["CI/CD Pipelines"]:::aux
    end

    %% Data Flow
    A --> B
    A --> C
    A --> D
    B --> E
    C --> E
    D --> E
    E --> F
    F --> G
    E --> H
    E --> I
    E --> J
    E --> K
    E --> L
    E --> M
    E --> N
    E --> O
    E --> P
    E --> Q
    E --> R
    E --> S
    E --> T

    %% Click Events
    click E "https://github.com/truera/trulens/tree/main/src/core/trulens"
    click B "https://github.com/truera/trulens/tree/main/src/apps/langchain"
    click C "https://github.com/truera/trulens/tree/main/src/apps/llamaindex"
    click D "https://github.com/truera/trulens/tree/main/src/apps/nemo"
    click H "https://github.com/truera/trulens/tree/main/src/connectors/snowflake"
    click I "https://github.com/truera/trulens/tree/main/src/providers/bedrock"
    click J "https://github.com/truera/trulens/tree/main/src/providers/cortex"
    click K "https://github.com/truera/trulens/tree/main/src/providers/huggingface"
    click L "https://github.com/truera/trulens/tree/main/src/providers/langchain"
    click M "https://github.com/truera/trulens/tree/main/src/providers/litellm"
    click N "https://github.com/truera/trulens/tree/main/src/providers/openai"
    click F "https://github.com/truera/trulens/tree/main/src/dashboard"
    click G "https://github.com/truera/trulens/tree/main/src/dashboard/react_components"
    click O "https://github.com/truera/trulens/tree/main/src/benchmark"
    click P "https://github.com/truera/trulens/tree/main/src/trulens_eval"
    click Q "https://github.com/truera/trulens/tree/main/docs"
    click R "https://github.com/truera/trulens/tree/main/docker"
    click S "https://github.com/truera/trulens/tree/main/tests"
    click T "https://github.com/truera/trulens/blob/main/.azure_pipelines"

    %% Styles
    classDef python fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef js fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef aux fill:#F5CBA7,stroke:#CA6F1E,stroke-width:2px;
```
