# protectai/rebuff architecture

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

- Interactive diagram: https://gitdiagram.com/protectai/rebuff
- Repository: https://github.com/protectai/rebuff

## Overview

##### Project type and purpose
- Rebuff.ai is a full-stack, self-hosting AI security platform and open-source SDK suite for detecting prompt injection attacks.
- It consists of:
– A Next.js-based web UI and serverless API (“server” folder)
– A JavaScript/TypeScript SDK (javascript-sdk folder)
– A Python SDK (python-sdk folder)
– Documentation and CI/CD workflows

##### File structure
- Top-level monorepo with four main “layers”:
– server: Next.js React UI (pages/, components/, styles/) combined with API routes (pages/api/…) implementing detection endpoints, billing, user management
– javascript-sdk: client-side library exposing detectInjections, addCanaryWord, etc. backed by TypeScript interfaces, tests, CI
– python-sdk: pip-installable SDK mirroring TS functionality with detect_pi_heuristics, detect_pi_openai, detect_pi_vectorbase, canary methods
- server contains configuration files for Netlify, TailwindCSS, Supabase (SQL schemas, functions) and Pinecone index integration
- CI workflows: build and publish Python/JS SDKs, run tests

##### Extract architecture insights from README and detection.puml
- Reads as a layered defense pipeline:
1. Heuristic filtering
2. LLM-based detection via OpenAI
3. VectorDB matching in Pinecone/Chroma
4. Canary token injection and leak detection

##### Main components
- Client applications:
– Web UI (Next.js front-end)
– JavaScript SDK (npm package)
– Python SDK (pip package)
- API Gateway / Server: Next.js serverless functions (account management, detect endpoint, logging, billing)
- Business logic layer: detection pipeline library (server/lib/*) implementing the four defense layers
- Data stores:
– Relational DB (Supabase/PostgreSQL) for user accounts, API keys, stats, logs
– VectorDB (Pinecone or Chroma) for storing attack embeddings
- External services:
– OpenAI (LLM calls)
– Supabase Auth & Compute
– Pinecone (vector similarity queries)
- Infrastructure & CI/CD: GitHub Actions, Netlify (or Vercel), Makefile for init

##### Relationships and data flows
- User (or SDK) → HTTP(S) → Next.js API route (/api/detect)
- API route → Heuristic module → Pass/fail →
– If pass, call OpenAI detection model → label
– Insert embeddings in Pinecone (vector DB) → similarity checks
– Canary token insertion and leak check → update vault
- Each stage logs results to Supabase/Postgres via SQL functions or direct queries
- Billing function deducts credits per call (SQL UDF on Supabase)
- UI reads/writes account, stats, prompt history via protected API routes
- SDKs wrap the HTTP API for embedding in external apps

##### Architectural patterns & design principles
- Layered pipeline: sequence of filters and detectors
- Monorepo modularization: separate SDKs vs. server code
- Serverless functions (Next.js API routes) for scalable endpoints
- Event-driven logging: functions and SQL triggers for billing and metrics
- SDK abstraction: clients never call OpenAI or Pinecone directly; they go through Rebuff API

##### Technologies, frameworks, and libraries
- Frontend/UI: Next.js, React, TypeScript, Tailwind CSS
- Backend: Node.js, Next.js API routes, serverless
- Databases: Supabase (Postgres + SQL functions), Pinecone (vector similarity)
- LLM: OpenAI GPT-3.5 Turbo (configurable)
- SDKs: TypeScript (axios/fetch), Python (httpx/requests, dataclasses)
- CI/CD: GitHub Actions, Makefile
- Testing: Mocha/Chai for JS, pytest for Python

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        JS_SDK["JavaScript SDK"]:::sdk
        PY_SDK["Python SDK"]:::sdk
        Web_UI["Web UI (Next.js)"]:::ui
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        subgraph "UI Layer"
            direction TB
            NextJS["Next.js Front-end"]:::ui
        end
        subgraph "API Layer"
            direction TB
            DetectEP["Detect Endpoint"]:::api
            AccountIDX["Account Routes"]:::api
            APIKeyEP["API Key Route"]:::api
            StatsEP["Stats Route"]:::api
            LogEP["Log Endpoint"]:::api
            PlaygroundEP["Playground Endpoint"]:::api
        end
        subgraph "Pipeline Library"
            direction TB
            Heuristics["Heuristics Module"]:::module
            OpenAIMod["OpenAI Detector"]:::module
            VectorClient["VectorDB Client"]:::module
            Orchestrator["Pipeline Orchestrator"]:::module
            APIBoundary["API Boundary Logic"]:::module
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["Supabase/Postgres"]:::datastore
        SQLTables["SQL Tables"]:::datastore
        SQLFuncs["SQL Functions (UDFs)"]:::datastore
        PineconeDB["Pinecone VectorDB"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI Service"]:::external
        SupabaseAuth["Supabase Auth & Compute"]:::external
        PineconeService["Pinecone Service"]:::external
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        direction TB
        CI["GitHub Actions"]:::infra
        Hosting["Netlify/Vercel"]:::infra
        Makefile["Makefile"]:::infra
    end

    %% Connections
    Web_UI -->|HTTPS| DetectEP
    JS_SDK -->|HTTP| DetectEP
    PY_SDK -->|HTTP| DetectEP

    DetectEP -->|calls| Heuristics
    Heuristics -->|pass| OpenAIMod
    OpenAIMod -->|embed| VectorClient
    VectorClient -->|check| PineconeDB
    OpenAIMod -->|calls| OpenAI
    VectorClient -->|queries| PineconeService
    Heuristics -->|fallback| Orchestrator
    Orchestrator -->|log results| Postgres
    Orchestrator -->|invoke| SQLFuncs
    Orchestrator -->|invoke| SQLTables
    DetectEP -->|auth & billing| SupabaseAuth
    SupabaseAuth -->|logs| Postgres
    AccountIDX -->|CRUD| Postgres
    APIKeyEP -->|CRUD| Postgres
    StatsEP -->|read| Postgres
    LogEP -->|write| Postgres
    PlaygroundEP -->|simulate| Orchestrator

    NextJS -->|renders| Web_UI
    Hosting -->|deploys| NextJS
    CI -->|build & publish| JS_SDK
    CI -->|build & publish| PY_SDK

    %% Click Events
    click JS_SDK "https://github.com/protectai/rebuff/tree/main/javascript-sdk/src/"
    click PY_SDK "https://github.com/protectai/rebuff/tree/main/python-sdk/rebuff/"
    click Web_UI "https://github.com/protectai/rebuff/tree/main/server/pages/"
    click Web_UI "https://github.com/protectai/rebuff/tree/main/server/components/"
    click Web_UI "https://github.com/protectai/rebuff/tree/main/server/styles/"
    click Web_UI "https://github.com/protectai/rebuff/tree/main/server/public/"
    click DetectEP "https://github.com/protectai/rebuff/blob/main/server/pages/api/detect.ts"
    click AccountIDX "https://github.com/protectai/rebuff/blob/main/server/pages/api/account/index.ts"
    click APIKeyEP "https://github.com/protectai/rebuff/blob/main/server/pages/api/account/apikey.ts"
    click StatsEP "https://github.com/protectai/rebuff/blob/main/server/pages/api/account/stats.ts"
    click LogEP "https://github.com/protectai/rebuff/blob/main/server/pages/api/log.ts"
    click PlaygroundEP "https://github.com/protectai/rebuff/blob/main/server/pages/api/playground.ts"
    click Heuristics "https://github.com/protectai/rebuff/blob/main/server/lib/detect-helpers.ts"
    click OpenAIMod "https://github.com/protectai/rebuff/blob/main/server/lib/openai.ts"
    click VectorClient "https://github.com/protectai/rebuff/blob/main/server/lib/pinecone-client.ts"
    click Orchestrator "https://github.com/protectai/rebuff/blob/main/server/lib/rebuff.ts"
    click APIBoundary "https://github.com/protectai/rebuff/blob/main/server/lib/rebuff-api.ts"
    click SQLTables "https://github.com/protectai/rebuff/blob/main/server/sql_setup/tables/accounts.sql"
    click SQLTables "https://github.com/protectai/rebuff/blob/main/server/sql_setup/tables/attempts.sql"
    click SQLTables "https://github.com/protectai/rebuff/blob/main/server/sql_setup/tables/leak_logs.sql"
    click SQLFuncs "https://github.com/protectai/rebuff/blob/main/server/sql_setup/functions/deduct_rate.sql"
    click SQLFuncs "https://github.com/protectai/rebuff/blob/main/server/sql_setup/functions/get_attempt_aggregates.sql"
    click PineconeDB "https://github.com/protectai/rebuff/blob/main/server/lib/pinecone-client.ts"
    click PineconeDB "https://github.com/protectai/rebuff/blob/main/server/lib/schema.ts"
    click CI "https://github.com/protectai/rebuff/tree/main/.github/workflows/"
    click Makefile "https://github.com/protectai/rebuff/tree/main/Makefile"
    click Hosting "https://github.com/protectai/rebuff/blob/main/server/netlify.toml"
    click Hosting "https://github.com/protectai/rebuff/blob/main/server/next.config.js"
    click Hosting "https://github.com/protectai/rebuff/blob/main/server/tailwind.config.js"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#03396c,color:#03396c
    classDef sdk fill:#b3cde0,stroke:#03396c,color:#03396c
    classDef api fill:#d5ead1,stroke:#006400,color:#006400
    classDef module fill:#c4def6,stroke:#011f4b,color:#011f4b
    classDef datastore fill:#e6e6e6,stroke:#666,color:#333
    classDef external fill:#fcd5ce,stroke:#9d0208,color:#9d0208
    classDef infra fill:#fdfd96,stroke:#9a8700,color:#9a8700
```
