# work4ai/guardrails architecture

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

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

## Overview

##### Project type and purpose
- Project type: A Python framework/library with a CLI and optional Flask-based server component.
- Purpose:
– Provide “Guardrails” (validation layers) around LLM calls to detect and mitigate risks (via input/output validators).
– Enable generation of structured data from LLMs (via Pydantic schemas or function-calling).
– Offer a standalone server mode (Flask) for remote guardrail validation via REST.
– Include a plugin-style “Hub” for pre-built validators and support custom validators.

##### File structure
– Top-level:
- guardrails/  ← core library package
- server_ci/   ← Docker + config for the Flask server
- docs/ + docusaurus/  ← documentation site
- tests/      ← unit and integration tests
- CLI entrypoints: Makefile, package.json (JS wrappers), pyproject.toml
– Within guardrails/:
- cli/                ← Typer/Click-based commands (configure, hub install, start server, validate)
- api_client.py       ← abstraction over LLM API calls
- run/                ← sync, async, streaming runners that orchestrate LLM + validation
- prompt/             ← prompt builders & templates
- schema/             ← rail schema parser, Pydantic schema generator
- validator_service/  ← sync/async validator orchestration
- hub/ & hub_telemetry/← integration with remote Hub service for validator packages
- integrations/       ← adapters for LangChain, LlamaIndex, Databricks, FAISS vectordb
- telemetry/ & call_tracing/ ← OpenTelemetry & custom tracing handlers
- document_store.py   ← persistence for prompt & validation history
- vectordb/           ← local vector store (FAISS) for retrieval-based validators
- types/, classes/, utils/ ← core data types, history & log classes, helper utilities

##### Insights from README
– Describes two workflows:
a) Running local Guards in Python (Guard().use(...).validate(...))
b) Running a standalone Guardrails Server (Flask + REST) for remote calls
– Mentions two modes of structured-data output: function calling vs prompt optimization
– Illustrates Hub CLI usage: install validators, create Guards

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Server Layer
    subgraph "CLI & Server"
        CLI["CLI"]:::cli
        click CLI "https://github.com/work4ai/guardrails/tree/main/guardrails/cli/"
        Server["Flask Server"]:::server
        click Server "https://github.com/work4ai/guardrails/tree/main/server_ci/"
    end

    %% Core Library Modules
    subgraph "Core Library" 
        direction TB
        Prompt["Prompt Builder"]:::core
        click Prompt "https://github.com/work4ai/guardrails/tree/main/guardrails/prompt/"
        APIClient["API Client"]:::core
        click APIClient "https://github.com/work4ai/guardrails/blob/main/guardrails/api_client.py"
        Run["Validator Runner\n(sync/async/stream)"]:::core
        click Run "https://github.com/work4ai/guardrails/tree/main/guardrails/run/"
        Schema["Schema Processor"]:::core
        click Schema "https://github.com/work4ai/guardrails/tree/main/guardrails/schema/"
        ValidatorService["Validator Service\n(sync & async)"]:::core
        click ValidatorService "https://github.com/work4ai/guardrails/tree/main/guardrails/validator_service/"
        HubLocal["Hub Integration"]:::core
        click HubLocal "https://github.com/work4ai/guardrails/tree/main/guardrails/hub/"
        click HubLocal "https://github.com/work4ai/guardrails/tree/main/guardrails/hub_telemetry/"
        Tracing["Call Tracing"]:::core
        click Tracing "https://github.com/work4ai/guardrails/tree/main/guardrails/call_tracing/"
        Telemetry["Telemetry"]:::core
        click Telemetry "https://github.com/work4ai/guardrails/tree/main/guardrails/telemetry/"
        DocStore["Document Store & History"]:::core
        click DocStore "https://github.com/work4ai/guardrails/blob/main/guardrails/document_store.py"
        click DocStore "https://github.com/work4ai/guardrails/tree/main/guardrails/classes/history/"
        LangChain["LangChain Integration"]:::core
        click LangChain "https://github.com/work4ai/guardrails/tree/main/guardrails/integrations/langchain/"
        LlamaIndex["LlamaIndex Integration"]:::core
        click LlamaIndex "https://github.com/work4ai/guardrails/tree/main/guardrails/integrations/llama_index/"
        Databricks["Databricks Integration"]:::core
        click Databricks "https://github.com/work4ai/guardrails/tree/main/guardrails/integrations/databricks/"
        FAISSInt["FAISS Integration (vectordb/faiss.py)"]:::core
        click FAISSInt "https://github.com/work4ai/guardrails/blob/main/guardrails/vectordb/faiss.py"
    end

    %% Persistence Layer
    subgraph "Persistence" 
        direction TB
        FAISSStore["FAISS Vector Store"]:::persistence
        click FAISSStore "https://github.com/work4ai/guardrails/tree/main/guardrails/vectordb/"
        Stores["Context Store"]:::persistence
        click Stores "https://github.com/work4ai/guardrails/tree/main/guardrails/stores/"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Providers["LLM Providers\n(OpenAI & local)"]:::ext
        click Providers "https://github.com/work4ai/guardrails/blob/main/guardrails/llm_providers.py"
        click Providers "https://github.com/work4ai/guardrails/tree/main/guardrails/utils/openai_utils/"
        ValidatorsHub["Validators Hub\n(remote registry)"]:::ext
        OTEL["OpenTelemetry Collector"]:::ext
    end

    %% Connections
    CLI -->|"configure/validate/start"| Run
    CLI -->|"start server"| Server
    Server -->|"HTTP request"| Run

    Run -->|"build prompt"| Prompt
    Prompt -->|"calls"| APIClient
    APIClient -->|"LLM call"| Providers
    Providers -->|"raw response"| APIClient
    APIClient -->|"response"| Run

    Run -->|"process schema"| Schema
    Schema -->|"validated output"| Run

    Run -->|"apply validators"| ValidatorService
    ValidatorService -->|"fetch rules"| ValidatorsHub
    ValidatorService -->|"use local hub"| HubLocal

    Run -->|"trace events"| Tracing
    Run -->|"emit metrics"| Telemetry
    Tracing -->|"send traces"| OTEL
    Telemetry -->|"send metrics"| OTEL

    Run -->|"log history"| DocStore

    ValidatorService -->|"use FAISS store"| FAISSStore
    ValidatorService -->|"use context store"| Stores

    LangChain -->|"wrap calls"| Run
    LlamaIndex -->|"wrap calls"| Run
    Databricks -->|"wrap calls"| Run
    FAISSInt -->|"vector queries"| ValidatorService

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064
    classDef ext fill:#e8f5e9,stroke:#1b5e20
    classDef cli fill:#fff3e0,stroke:#e65100
    classDef server fill:#ffe0b2,stroke:#e65100
    classDef persistence fill:#eceff1,stroke:#37474f
```
