# work4ai/rebuff architecture

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

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

## Overview

##### Project Type and Purpose
- This is a monorepo for Rebuff.ai, a self-hardening prompt-injection detector.
- It provides two SDKs (JavaScript/TypeScript and Python) for client-side integration and a Next.js-based server offering a playground UI, API endpoints, and orchestration of detection logic.
- Key functionality: multi-layered defense (heuristics, LLM-based detection, VectorDB signature matching, canary tokens), user/account management, billing, and logging.

##### File Structure Analysis
- Top-level directories:
- javascript-sdk – client library with modules for tactics (Heuristic, OpenAI, Vector), API/config, SDK entrypoint, tests, build config.
- python-sdk – analogous client library in Python with `rebuff` package, detection implementations, SDK class, examples, tests.
- server – Next.js application containing:
– pages/api/** – serverless routes (detect, log, account management, playground docs).
– components/** – React UI for the playground, stats, login, etc.
– lib/** – business logic (openai wrapper, Pinecone/Supabase clients, detect helpers, billing, schema).
– sql_setup/** – Supabase/PostgreSQL tables and functions for accounts, attempts, leakage logs, rate/billing.
– config files (next.config.js, netlify.toml, env, styles).
- Root contains docs, GitHub workflows (CI/CD for building/testing/publishing SDKs), a PlantUML sequence (detection.puml), Makefile.

##### README Insights
- Emphasizes a four-layer defense pipeline invoked by SDKs or via direct API calls to the Next.js server.

##### Diagramming Conventions
- From SDK to `/api/detect` endpoint (label: “POST user prompt”)
- From Server to OpenAI API (label: “LLM analysis request/response”)
- From Server to Pinecone (label: “Vector query/store”)
- From Server to Supabase (label: “SQL function calls: log, billing, stats”)
- Blue for client-side (SDKs, UI)
- Green for server/runtime (API routes, orchestrator)
- Orange for data stores (Supabase, Pinecone)
- Gray for external services (OpenAI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        JS_SDK["javascript-sdk/src/index.ts"]:::frontend
        JS_API["javascript-sdk/src/api.ts"]:::frontend
        JS_Config["javascript-sdk/src/config.ts"]:::frontend
        JS_Heu["javascript-sdk/src/tactics/Heuristic.ts"]:::frontend
        JS_OAI["javascript-sdk/src/tactics/OpenAI.ts"]:::frontend
        JS_Vec["javascript-sdk/src/tactics/Vector.ts"]:::frontend
        JS_VDB["javascript-sdk/src/lib/vectordb.ts"]:::frontend

        PY_SDK["python-sdk/rebuff/sdk.py"]:::frontend
        PY_Heu["python-sdk/rebuff/detect_pi_heuristics.py"]:::frontend
        PY_OAI["python-sdk/rebuff/detect_pi_openai.py"]:::frontend
        PY_Vec["python-sdk/rebuff/detect_pi_vectorbase.py"]:::frontend
        PY_Core["python-sdk/rebuff/rebuff.py"]:::frontend
        PY_Version["python-sdk/rebuff/_version.py"]:::frontend

        PlaygroundUI["Playground UI (browser)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API_Detect["server/pages/api/detect.ts"]:::server
        API_Log["server/pages/api/log.ts"]:::server
        API_Account["server/pages/api/account/index.ts"]:::server
        API_APIKey["server/pages/api/account/apikey.ts"]:::server
        API_Stats["server/pages/api/account/stats.ts"]:::server
        API_Playground["server/pages/api/playground.ts"]:::server
        API_Docs["server/pages/docs/index.tsx"]:::server
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Orchestrator["server/lib/detect-helpers.ts"]:::server
        OAI_Wrapper["server/lib/openai.ts"]:::server
        Vec_Client["server/lib/pinecone-client.ts"]:::server
        Supabase_Client["server/lib/supabase.ts"]:::server
        Schema["server/lib/schema.ts"]:::server
        Account_Help["server/lib/account-helpers.ts"]:::server
        General_Help["server/lib/general-helpers.ts"]:::server
        RebuffAPI["server/lib/rebuff-api.ts"]:::server
        Templates["server/lib/templates.ts"]:::server
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SupabaseDB["Supabase/PostgreSQL"]:::datastore
        PineconeDB["Pinecone (VectorDB)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Supabase_Auth["Supabase Auth"]:::external
    end

    %% Connections
    JS_SDK -->|"POST user prompt"| API_Detect
    JS_API --> API_Detect
    JS_Config --> API_Detect
    PY_SDK -->|"POST user prompt"| API_Detect

    PlaygroundUI -->|"GET stats/docs"| API_Stats
    PlaygroundUI -->|"GET playground data"| API_Playground
    PlaygroundUI -->|"GET docs UI"| API_Docs

    API_Detect -->|"invoke pipeline"| Orchestrator
    API_Log -->|"log verdict"| SupabaseDB
    API_Account -->|"manage account"| SupabaseDB
    API_APIKey -->|"manage apikey"| SupabaseDB
    API_Stats -->|"fetch stats"| SupabaseDB

    Orchestrator -->|"LLM analysis request/response"| OAI_Wrapper
    Orchestrator -->|"Vector query/store"| Vec_Client
    Orchestrator -->|"SQL calls: log, billing, stats"| Supabase_Client
    Orchestrator -->|"apply schema"| Schema
    Orchestrator -->|"account logic"| Account_Help
    Orchestrator -->|"general utilities"| General_Help
    Orchestrator -->|"internal API"| RebuffAPI
    Orchestrator -->|"templates"| Templates

    OAI_Wrapper -->|"call"| OpenAI
    Vec_Client -->|"query"| PineconeDB
    Supabase_Client -->|"auth & functions"| Supabase_Auth
    Supabase_Client -->|"db operations"| SupabaseDB

    %% Click Events - JavaScript SDK
    click JS_SDK "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/index.ts"
    click JS_API "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/api.ts"
    click JS_Config "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/config.ts"
    click JS_Heu "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/tactics/Heuristic.ts"
    click JS_OAI "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/tactics/OpenAI.ts"
    click JS_Vec "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/tactics/Vector.ts"
    click JS_VDB "https://github.com/work4ai/rebuff/blob/main/javascript-sdk/src/lib/vectordb.ts"

    %% Click Events - Python SDK
    click PY_SDK "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/sdk.py"
    click PY_Heu "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/detect_pi_heuristics.py"
    click PY_OAI "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/detect_pi_openai.py"
    click PY_Vec "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/detect_pi_vectorbase.py"
    click PY_Core "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/rebuff.py"
    click PY_Version "https://github.com/work4ai/rebuff/blob/main/python-sdk/rebuff/_version.py"

    %% Click Events - API Layer
    click API_Detect "https://github.com/work4ai/rebuff/blob/main/server/pages/api/detect.ts"
    click API_Log "https://github.com/work4ai/rebuff/blob/main/server/pages/api/log.ts"
    click API_Account "https://github.com/work4ai/rebuff/blob/main/server/pages/api/account/index.ts"
    click API_APIKey "https://github.com/work4ai/rebuff/blob/main/server/pages/api/account/apikey.ts"
    click API_Stats "https://github.com/work4ai/rebuff/blob/main/server/pages/api/account/stats.ts"
    click API_Playground "https://github.com/work4ai/rebuff/blob/main/server/pages/api/playground.ts"
    click API_Docs "https://github.com/work4ai/rebuff/blob/main/server/pages/docs/index.tsx"

    %% Click Events - Business Logic
    click Orchestrator "https://github.com/work4ai/rebuff/blob/main/server/lib/detect-helpers.ts"
    click OAI_Wrapper "https://github.com/work4ai/rebuff/blob/main/server/lib/openai.ts"
    click Vec_Client "https://github.com/work4ai/rebuff/blob/main/server/lib/pinecone-client.ts"
    click Supabase_Client "https://github.com/work4ai/rebuff/blob/main/server/lib/supabase.ts"
    click Schema "https://github.com/work4ai/rebuff/blob/main/server/lib/schema.ts"
    click Account_Help "https://github.com/work4ai/rebuff/blob/main/server/lib/account-helpers.ts"
    click General_Help "https://github.com/work4ai/rebuff/blob/main/server/lib/general-helpers.ts"
    click RebuffAPI "https://github.com/work4ai/rebuff/blob/main/server/lib/rebuff-api.ts"
    click Templates "https://github.com/work4ai/rebuff/blob/main/server/lib/templates.ts"

    %% Click Events - Data Layer SQL
    click SupabaseDB "https://github.com/work4ai/rebuff/blob/main/server/sql_setup/tables/accounts.sql"
    click PineconeDB "https://github.com/work4ai/rebuff/blob/main/server/sql_setup/functions/deduct_rate.sql"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0284C7,color:#000
    classDef server fill:#D1F7C4,stroke:#2A9D34,color:#000
    classDef datastore fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef external fill:#E0E0E0,stroke:#757575,color:#000
```
