# pezzolabs/pezzo architecture

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

- Interactive diagram: https://gitdiagram.com/pezzolabs/pezzo
- Repository: https://github.com/pezzolabs/pezzo

## Overview

Based on our analysis of the file tree and README, Pezzo is an open‐source, cloud-native LLMOps platform that combines a web console for managing prompts and monitoring AI operations with a backend server and a proxy layer. The system offers full-stack functionality with separate concerns for frontend, backend, and middleware layers, and it integrates with several infrastructure dependencies (PostgreSQL, ClickHouse, Redis, Supertokens) as well as external LLM providers.

##### Main Components
- Console (Frontend): Located under apps/console. This is the user interface built with React (note use of TypeScript, .tsx files) and styled using TailwindCSS and UI libraries from libs/ui. It handles visual components (layouts, dashboards, prompt editors, etc.) and interacts with backend APIs.
- Proxy: Found under apps/proxy. Acts as an intermediate gateway/middleware to facilitate or route requests to external LLM providers and possibly perform necessary transformations.
- Server (Backend): Under apps/server, this is the core of the application. It includes GraphQL endpoints, REST controllers, business logic (authentication, metrics, identity, prompt management, caching, analytics, reporting), and Prisma-based data access to a PostgreSQL database.
- Shared Libraries: In libs/ (client, common, kafka, types, ui) – these libraries encapsulate reusable code. For example, the client (in libs/client) is used by supported Node.js and Python SDKs to communicate with the platform.
- Infrastructure Components: Although not part of the source code tree, include PostgreSQL, ClickHouse, Redis, and Supertokens (as depicted in the README and Docker Compose files). These systems are critical for persistence, analytics, caching, authentication, and more.
- External Dependencies: Other cloud-native integrations include LLM providers (like OpenAI) as referenced in the proxy and provider API key modules.

##### Relationships and Data Flows
- The Server handles authentication (integrated with Supertokens) and interacts with the Postgres database via Prisma. It also communicates with Redis for caching, ClickHouse for analytical queries, and uses Kafka (libs/kafka) for asynchronous messaging if needed.

##### Architectural Patterns and Principles
- The separation of concerns is clearly delineated between frontend (Console), middleware (Proxy), and backend (Server).
- Use of GraphQL and REST endpoints on the server side, and the integration of external messaging systems (Kafka) denote a scalable and event-driven approach.
- That the project leverages containerization (Dockerfiles in each component and docker-compose scripts for infra), which implies a cloud-native microservices deployment.

##### Relevant Technologies and Frameworks
- Frontend: React with TypeScript, TailwindCSS, Storybook for UI components.
- Backend: Node.js with TypeScript, NestJS-like module organization (if applicable), Prisma for ORM, GraphQL resolvers, and REST endpoints.
- Proxy: Node.js with Express/Koa-like middleware (as indicated by router definitions), custom middleware for handling OpenAI request routing.
- Infrastructure: PostgreSQL, ClickHouse, Redis, Supertokens, Kafka.
- Tooling: Docker, NX monorepo structure, ESLint, Prettier, and various configuration files.

##### Instructing
- Use clear labels for each component; for example, “Pezzo Console (React Frontend)”, “Pezzo Server (GraphQL/REST API)”, “Pezzo Proxy (Middleware for LLM integrations)”, “PostgreSQL (Data Persistence)”, “ClickHouse (Analytics)”, “Redis (Caching)”, and “Supertokens (Authentication)” along with any external LLM provider services.
- Annotations on significant patterns such as “Microservices Architecture”, “Modular Design (via NX monorepo)”, or “GraphQL Schema Driven Development” to capture design decisions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Console["Pezzo Console (React Frontend)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        Server["Pezzo Server (GraphQL/REST API)"]:::backend
        Proxy["Pezzo Proxy (Middleware for LLM integrations)"]:::middleware
        subgraph "Business Modules"
            Auth["Authentication Module"]:::module
            Prompts["Prompt Management Module"]:::module
            Metrics["Metrics & Analytics Module"]:::module
        end
        Server --> Auth
        Server --> Prompts
        Server --> Metrics
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        UI["Shared UI Library"]:::library
        Client["Shared Client Library"]:::library
        Common["Shared Common Library"]:::library
        Kafka["Shared Kafka Library"]:::library
        Types["Shared Types Library"]:::library
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        PG["PostgreSQL (Data Persistence)"]:::db
        ClickHouse["ClickHouse (Analytics)"]:::db
        Redis["Redis (Caching)"]:::cache
        Supertokens["Supertokens (Authentication)"]:::authInfra
        ExternalLLM["External LLM Providers"]:::external
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        Docker1["Docker Compose Config"]:::deployment
        Docker2["Infra Compose Config"]:::deployment
    end

    %% Data Flows
    Console -->|"HTTP/GraphQL"| Server
    Console -->|"API-calls"| Proxy
    Server -->|"Routes"| Proxy
    Server -->|"Data-access (Prisma)"| PG
    Server -->|"Caching"| Redis
    Server -->|"Analytics Queries"| ClickHouse
    Server -->|"Auth calls"| Supertokens
    Server -->|"Messaging"| Kafka
    Proxy -->|"Request-routing"| ExternalLLM

    %% Shared Libraries integration
    UI --- Console
    Client --- Server
    Common --- Server
    Types --- Server

    %% Deployment relationships
    Docker1 -.-> PG
    Docker1 -.-> ClickHouse
    Docker1 -.-> Redis
    Docker1 -.-> Supertokens
    Docker2 -.-> PG
    Docker2 -.-> ClickHouse
    Docker2 -.-> Redis
    Docker2 -.-> Supertokens

    %% Styles
    classDef frontend fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef backend fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef middleware fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef library fill:#577590,stroke:#333,stroke-width:2px;
    classDef db fill:#277da1,stroke:#333,stroke-width:2px;
    classDef cache fill:#66c2a5,stroke:#333,stroke-width:2px;
    classDef authInfra fill:#f94144,stroke:#333,stroke-width:2px;
    classDef external fill:#a9def9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#c984f8,stroke:#333,stroke-width:2px;
    classDef module fill:#f3722c,stroke:#333,stroke-width:2px;

    %% Click Events
    click Console "https://github.com/pezzolabs/pezzo/tree/main/apps/console"
    click Proxy "https://github.com/pezzolabs/pezzo/tree/main/apps/proxy"
    click Server "https://github.com/pezzolabs/pezzo/tree/main/apps/server"
    click UI "https://github.com/pezzolabs/pezzo/tree/main/libs/ui"
    click Client "https://github.com/pezzolabs/pezzo/tree/main/libs/client"
    click Common "https://github.com/pezzolabs/pezzo/tree/main/libs/common"
    click Kafka "https://github.com/pezzolabs/pezzo/tree/main/libs/kafka"
    click Types "https://github.com/pezzolabs/pezzo/tree/main/libs/types"
    click Docker1 "https://github.com/pezzolabs/pezzo/blob/main/docker-compose.yaml"
    click Docker2 "https://github.com/pezzolabs/pezzo/blob/main/docker-compose.infra.yaml"
    click ClickHouse "https://github.com/pezzolabs/pezzo/tree/main/clickhouse"
```
