# guardrails-ai/guardrails architecture

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

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

## Overview

Based on our analysis of the Guardrails project’s file tree and README, the project is a Python framework that provides a robust set of tools for “guarding” against risks with LLM inputs/outputs by using validators (or “guardrails”) and for generating structured output from LLMs. In short, its purpose is twofold: to validate and mitigate risks in AI applications and to enforce structured data output using intelligent prompt designs and/or function call techniques.

##### Main Components
- Core Library (Guardrails Engine): This is the heart of the system. It includes the main modules and submodules under the “guardrails” package (for example, guardrails/guard.py, guardrails/cli, guardrails/prompt, guardrails/actions, guardrails/types, etc.). These components handle schema validations, prompt templating, execution flows, and apply the guardrail logic.
- Validators and Hub Integration: Components like guardrails/hub, guardrails/validator_service, and the “validators” directory encapsulate the external (or internal) pre-built measures (validators) that run validations and manage “on fail” actions. They also cover integrations with remote validators from Guardrails Hub.
- CLI & Server Application: The guardrails/cli modules (including hub CLI commands and the server subcomponent) enable command-line interaction and also provide an API endpoint using frameworks (Flask is mentioned) so that Guardrails can run as a standalone REST service. The server_ci folder and related Dockerfiles/support scripts are part of deployment and serve as the containerized production-ready server.
- Integration Subsystem: Under guardrails/integrations and related directories there are modules built for integration with external LLMs (OpenAI, Langchain, LlamaIndex, etc.), telemetry (trace handlers), and remote inference. This layer abstracts interactions with different LLM providers and ensures proper formatting and routing.
- Telemetry and Logging: Modules like guardrails/telemetry are responsible for monitoring, tracing, and logging system behaviors, which is critical for debugging and performance monitoring.
- Testing & Documentation: Although not part of the runtime, the “tests” directory (with unit and integration tests) and “docs” (and docusaurus) directories are essential for quality assurance and system documentation.

##### Architectural Relationships & Data Flow
- The CLI layer acts as the entry point for users and administrators, launching the core library’s functions (such as validate, prompt management, and instantiating guard instances).
- The core library’s “Engine” uses modular classes (for validation, prompt templating, and parsing outputs) and easy extensibility (via plugins from the Guardrails Hub). It interacts bidirectionally with external LLM APIs.
- The Validator subsystem intercepts inputs or outputs and uses on-fail policies to trigger actions (e.g., exceptions, reasks), with their own dedicated classes for various types of validations.
- The integration layer sits between the Guardrails Engine and external services – for LLM API calls, telemetry reporting, and even embedding extraction (e.g., from provider-specific utilities).
- Telemetry pieces and logging utilities are integrated into every layer to enable end-to-end traceability.

##### Architectural Patterns & Design Principles
- Modular and Layered Architecture: The project is separated into modules (CLI, core, validators, integrations, telemetry) which allows them to be developed, tested, and deployed or replaced independently.
- Plugin & Extensibility Model: The use of "Hub" for external validators and custom actions indicates a plug-and-play design, where users can add or substitute new validators without touching the core.
- Separation of Concerns: Different directories and modules clearly isolate concerns (e.g., guardrails/prompt for prompting, guardrails/utils for helper functions, guardrails/cli for command line interfaces).
- Emphasis on Testing and Continuous Integration: Extensive inclusion of unit and integration tests and GitHub workflows shows that quality and stability are integral to the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client (CLI/REST)"):::client

    subgraph "CLI & Server Application"
        CLI("CLI"):::cli
        Server("Server"):::cli
    end

    subgraph "Core Guardrails Engine"
        Guard("Guard (guard.py)"):::core
        Prompt("Prompt Management"):::core
        Utils("Utilities"):::core
    end

    subgraph "Validators and Hub Integration"
        Hub("Hub"):::validator
        ValidatorService("Validator Service"):::validator
        Validators("Validators"):::validator
    end

    subgraph "Integration Subsystem"
        Langchain("Langchain Integration"):::integration
        LlamaIndex("LlamaIndex Integration"):::integration
    end

    Telemetry("Telemetry & Logging"):::telemetry
    External("External LLM APIs"):::external

    subgraph "Testing & Documentation"
        Tests("Tests"):::testing
        Docs("Documentation"):::testing
    end

    %% Data Flow Connections
    Client --> CLI
    Client --> Server

    CLI -->|"invoke"| Guard
    Server -->|"API call"| Guard

    %% Internal Engine Modules
    Guard -->|"manage"| Prompt
    Guard -->|"use"| Utils

    %% Interaction with Validators and Hub
    Guard -->|"validate"| Hub
    Hub -->|"orchestrate"| ValidatorService
    Hub -->|"coordinate"| Validators

    %% Integration with External LLMs
    Guard -->|"integrate"| Langchain
    Guard -->|"integrate"| LlamaIndex
    Langchain -->|"callLLM"| External
    LlamaIndex -->|"callLLM"| External

    %% Telemetry Hooks
    Guard --> Telemetry
    Hub --> Telemetry
    Langchain --> Telemetry
    LlamaIndex --> Telemetry

    %% Styling
    classDef client fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef cli fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef validator fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef integration fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef telemetry fill:#B0E0E6,stroke:#333,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#333,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click Guard "https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py"
    click Prompt "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/prompt"
    click Utils "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/utils"
    click Hub "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/hub"
    click ValidatorService "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/validator_service"
    click Validators "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/validators"
    click CLI "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/cli"
    click Server "https://github.com/guardrails-ai/guardrails/tree/main/server_ci"
    click Langchain "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/integrations/langchain"
    click LlamaIndex "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/integrations/llama_index"
    click Telemetry "https://github.com/guardrails-ai/guardrails/tree/main/guardrails/telemetry"
    click Tests "https://github.com/guardrails-ai/guardrails/tree/main/tests/"
    click Docs "https://github.com/guardrails-ai/guardrails/tree/main/docs/"
```
