# scale3-labs/langtrace architecture

> Architecture diagram of the GitHub repository scale3-labs/langtrace, 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/scale3-labs/langtrace
- Repository: https://github.com/scale3-labs/langtrace

## Overview

##### Main Components
- Frontend Application (Next.js UI): Includes the “app” folder (pages, layouts, and protected/auth routes) and “components” (UI elements, charts, datasets, project and trace related views). This layer represents the user interface that developers and administrators interact with.
- Backend API Routes: Located under app/api, this includes endpoints for authentication, chat integrations, evaluations, projects, datasets, metrics, and more.
- Middleware, Services & Utilities: These reside in the “lib” directory and contain authentication mechanisms, middleware configuration, query builders, and tracing utilities used by the API routes.
- Database Layer:
- Postgres: Acts as the metadata store (managed by Prisma with migrations and schema definitions in the “prisma” directory).
- ClickHouse: Handles high-volume trace, metric, and log data.
- External & External Integration Points:
- Open Telemetry & SDKs: As stated in the README, Langtrace supports OTEL standards and integrates with various LLM providers and vector database systems.
- SDK Clients (TypeScript & Python): This is how external applications instrument and send traces to the Langtrace system.

##### Relationships and Interactions
- The Frontend (next.js pages and components) calls the Backend API endpoints for creating projects, handling authentication, initiating evaluations, and retrieving trace/metric data.
- API endpoints leverage internal libraries (middleware, query builders, and trace services) to process requests and interact with the databases.
- The databases are accessed by API endpoints:
- Postgres for metadata (project configuration, user, and settings data).
- ClickHouse for ingesting and querying high-performance trace and metrics data.
- External interactions include:
- SDK integrations where external applications call the Langtrace APIs via the respective SDKs.
- Integration with external LLM providers and services (e.g., OpenAI, Anthropic, etc.), evidenced by the dedicated API routes for chat and evaluation.
- Deployment components include Docker, Docker Compose, and environment configuration (with the .env file and Dockerfile) for self-hosting the entire stack.

##### Architectural Patterns & Relevant Technologies
- You’re looking at a monolithic Next.js design that integrates API routing with page rendering and uses the file-based routing system.
- The project showcases a layered architecture (UI layer, API/business logic layer, data access layer) with clear separation between public and protected routes (as seen by the “(auth)” and “(protected)” directories).
- Use of standard protocols and conventions (Open Telemetry for tracing) and separation of concerns using Express-like middleware patterns via Next.js.
- The use of Prisma ORM with Postgres, coupled with a high-performance ClickHouse setup, emphasizes performance and observability in handling high volumes of trace data.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F1["Next.js App (pages, layouts, auth)"]:::frontend
        F2["UI Components"]:::frontend
    end

    %% Backend & Middleware Layer
    subgraph "Backend & Middleware Layer"
        B["Backend API Routes"]:::backend
        M["Middleware & Services"]:::middleware
    end

    %% Database Layer
    subgraph "Database Layer"
        D1["Postgres (Metadata Store)"]:::db1
        D2["ClickHouse (Trace & Metrics Storage)"]:::db2
    end

    %% External Integrations
    subgraph "External Integrations"
        E1["SDK Clients (TypeScript & Python)"]:::external
        E2["LLM Providers & External Services"]:::external
    end

    %% Protocol Buffers
    P["Protocol Buffers"]:::proto

    %% Relationships
    F1 -->|"calls"| B
    F2 -->|"renders"| F1
    B -->|"utilizes"| M
    M -->|"reads/writes"| D1
    M -->|"reads/writes"| D2
    B -->|"communicates via"| P
    E1 -->|"calls"| B
    E2 -->|"integrates with"| B

    %% Click Events
    click F1 "https://github.com/scale3-labs/langtrace/tree/main/app"
    click F2 "https://github.com/scale3-labs/langtrace/tree/main/components"
    click B "https://github.com/scale3-labs/langtrace/tree/main/app/api"
    click M "https://github.com/scale3-labs/langtrace/tree/main/lib"
    click D1 "https://github.com/scale3-labs/langtrace/tree/main/prisma"
    click D2 "https://github.com/scale3-labs/langtrace/tree/main/lib/clients/scale3_clickhouse"
    click P "https://github.com/scale3-labs/langtrace/tree/main/proto"

    %% Styles
    classDef frontend fill:#A8DADC,stroke:#457B9D,stroke-width:2px;
    classDef backend fill:#F4A261,stroke:#E76F51,stroke-width:2px;
    classDef middleware fill:#FFB703,stroke:#FB8500,stroke-width:2px;
    classDef db1 fill:#1D3557,stroke:#457B9D,stroke-width:2px,color:#ffffff;
    classDef db2 fill:#E63946,stroke:#D62828,stroke-width:2px,color:#ffffff;
    classDef external fill:#2A9D8F,stroke:#264653,stroke-width:2px,color:#ffffff;
    classDef proto fill:#903749,stroke:#720026,stroke-width:2px,color:#ffffff;
```
