# lmnr-ai/lmnr architecture

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

- Interactive diagram: https://gitdiagram.com/lmnr-ai/lmnr
- Repository: https://github.com/lmnr-ai/lmnr

## Overview

##### Project type and purpose
- Laminar is a self-hostable, open-source full-stack platform for tracing and evaluating AI applications.
- Key features from the README:
- OpenTelemetry-based automatic tracing via gRPC
- Parallel evals SDK
- Data export to datasets
- Dashboards for traces, metrics, labels
- Core backend in Rust, agent manager in Python, frontend in Next.js

##### File structure
- Top-level services:
- agent-manager (Python gRPC service & browser agent)
- app-server (Rust core backend, gRPC endpoints, RabbitMQ consumers/producers, Postgres/ClickHouse drivers)
- frontend (Next.js UI + API routes)
- docker-compose files orchestrating Postgres, ClickHouse, RabbitMQ, agent-manager, app-server, frontend
- Recognize patterns:
- Microservices (agent-manager vs. app-server vs. frontend)
- Event-driven, queue-based trace ingestion (RabbitMQ)
- gRPC for high-throughput telemetry ingestion
- REST/Next.js API for UI interactions
- OLAP (ClickHouse) vs. OLTP (Postgres)

##### README for architecture insights
- SDKs/instruments → gRPC → app-server
- RabbitMQ for decoupled trace processing
- Postgres for application state
- ClickHouse for analytics
- Next.js frontend consuming REST API

- Client layer: TS & Python SDKs + instrumented AI frameworks
- agent-manager service (Python gRPC)
- app-server service (Rust gRPC + RabbitMQ producer/consumer + REST API)
- Message broker: RabbitMQ
- Databases: Postgres (OLTP), ClickHouse (OLAP)
- Next.js frontend (UI + API routes)
- External services: AI providers (OpenAI, Anthropic, LangChain, Scrapybara)
- SDK → gRPC → app-server / agent-manager
- agent-manager → RabbitMQ queue → app-server consumer
- app-server → Postgres for metadata & control data
- app-server → write trace batches to ClickHouse
- app-server → consume from RabbitMQ for label/eval events
- Next.js frontend → REST API → app-server
- Frontend static assets served via Docker container
- External AI services called by SDKs/agent-manager
c. Architectural patterns & principles:
- Microservices separation of concerns
- Event-driven / asynchronous processing via message queue
- Use of gRPC for low-latency instrumentation
- CQRS-style separation: Postgres for writes/state, ClickHouse for read/analytics
- API layering: gRPC for ingestion, REST for UI
d. Key technologies & frameworks:
- Rust (app-server)
- Python (agent-manager)
- Next.js / React (frontend)
- gRPC + protobuf
- RabbitMQ
- Postgres
- ClickHouse
- Docker & Docker Compose

##### Detail without overcomplicating
- Distinct service and its role.
- Data stores separately (Postgres vs. ClickHouse).
- External dependencies (AI providers, browser agent manager).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Instrumentation Layer
    subgraph "Client Instrumentation Layer"
        direction TB
        SDK_TS["TypeScript SDK"]:::sdk
        SDK_PY["Python SDK"]:::sdk
        EXT_AI["External AI Providers"]:::external
    end

    %% Agent Manager Service
    subgraph "Agent Manager Service" 
        direction TB
        AM_PROTO["gRPC Protos"]:::backend
        AM_SERVER["Server (main.py)"]:::backend
    end

    %% App Server Service
    subgraph "App Server Service"
        direction TB
        AS_GRPC["gRPC & Instrumentation Protos"]:::backend
        AS_GRPC_IMPL["gRPC Service impl"]:::backend
        AS_MQ["RabbitMQ Integration"]:::backend
        AS_REST["REST API Routes"]:::backend
        AS_DB["Postgres Models & Queries"]:::data
        AS_CH["ClickHouse Modules"]:::data
        AS_AG["Agent Manager Client"]:::backend
        AS_LM["Language Model Integrations"]:::backend
        AS_MM["Machine Manager gRPC"]:::backend
    end

    %% Message Broker
    RabbitMQ["RabbitMQ"]:::broker

    %% Datastores
    subgraph "Datastores"
        direction TB
        Postgres[(Postgres)]:::data
        ClickHouse[(ClickHouse)]:::data
    end

    %% Frontend Layer
    subgraph "Next.js Frontend"
        direction TB
        FE_APP["Application (frontend/)"]:::frontend
        FE_API["API Routes"]:::frontend
        FE_COMP["React Components"]:::frontend
        FE_LIB["Data Access & SDK Utils"]:::frontend
        FE_DB_MIG["DB Migrations"]:::data
        FE_CH["ClickHouse Client & Migrations"]:::data
        FE_AUTH["Auth & Session"]:::frontend
        FE_INS["Instrumentation SDK Stub"]:::sdk
    end

    %% Connections
    SDK_TS -->|gRPC| AS_GRPC
    SDK_PY -->|gRPC| AS_GRPC
    SDK_TS -->|REST| FE_API
    EXT_AI -->|calls| SDK_TS
    EXT_AI -->|calls| SDK_PY

    AS_GRPC -->|ingest traces| AS_GRPC_IMPL
    AM_SERVER -->|gRPC ingestion| AS_AG
    SDK_TS -->|browser traces| AM_SERVER
    AM_SERVER -->|AM queue| RabbitMQ
    RabbitMQ -->|consume events| AS_MQ
    AS_MQ -->|enqueue batch| AS_CH
    AS_GRPC_IMPL -->|write metadata| AS_DB
    AS_CH -->|store trace batches| ClickHouse
    AS_DB -->|store control data| Postgres

    FE_API -->|REST API| AS_REST
    FE_APP -->|UI data| FE_API

    %% Click events for component mapping
    click AM_PROTO "https://github.com/lmnr-ai/lmnr/blob/main/agent-manager/proto/agent_manager_grpc.proto"
    click AM_SERVER "https://github.com/lmnr-ai/lmnr/blob/main/agent-manager/src/main.py"
    click AgentManager "https://github.com/lmnr-ai/lmnr/tree/main/agent-manager/"
    click AS_GRPC "https://github.com/lmnr-ai/lmnr/tree/main/app-server/proto/"
    click AS_GRPC_IMPL "https://github.com/lmnr-ai/lmnr/blob/main/app-server/src/traces/grpc_service.rs"
    click AS_MQ "https://github.com/lmnr-ai/lmnr/blob/main/app-server/src/mq/rabbit.rs"
    click AS_REST "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/routes/"
    click AS_DB "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/db/"
    click AS_CH "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/ch/"
    click AS_AG "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/agent_manager/"
    click AS_LM "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/language_model/"
    click AS_MM "https://github.com/lmnr-ai/lmnr/tree/main/app-server/src/machine_manager/"
    click AppServer "https://github.com/lmnr-ai/lmnr/tree/main/app-server/"
    click Cargo "https://github.com/lmnr-ai/lmnr/blob/main/app-server/Cargo.toml"
    click FE_APP "https://github.com/lmnr-ai/lmnr/tree/main/frontend/"
    click FE_API "https://github.com/lmnr-ai/lmnr/tree/main/frontend/app/api/"
    click FE_COMP "https://github.com/lmnr-ai/lmnr/tree/main/frontend/components/"
    click FE_LIB "https://github.com/lmnr-ai/lmnr/tree/main/frontend/lib/"
    click FE_DB_MIG "https://github.com/lmnr-ai/lmnr/tree/main/frontend/lib/db/migrations/"
    click FE_CH "https://github.com/lmnr-ai/lmnr/tree/main/frontend/lib/clickhouse/"
    click FE_AUTH "https://github.com/lmnr-ai/lmnr/blob/main/frontend/app/api/auth/[...nextauth]/route.ts"
    click FE_INS "https://github.com/lmnr-ai/lmnr/blob/main/frontend/instrumentation.ts"
    click DockerCompose "https://github.com/lmnr-ai/lmnr/blob/main/docker-compose.yml"

    %% Styles
    classDef sdk fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#ccf,stroke:#333,stroke-width:1px
    classDef frontend fill:#fcf,stroke:#333,stroke-width:1px
    classDef data fill:#cfc,stroke:#333,stroke-width:1px
    classDef broker fill:#fcc,stroke:#333,stroke-width:1px
    classDef external fill:#eef,stroke:#333,stroke-width:1px
```
