Lev/diagrams

diagrams/01-system-overview.md

@@ -0,0 +1,63 @@
+# System Overview
+
+High-level view of Agent Protect architecture showing the main components and how they interact.
+
+## Component Architecture
+
+```mermaid
+flowchart TB
+    subgraph client["Client Application"]
+        agent["AI Agent<br/>(LangChain, LangGraph, etc.)"]
+        sdk["Agent Control SDK"]
+    end
+
+    subgraph server["Agent Control Server"]
+        api["REST API<br/>(FastAPI)"]
+        engine["Control Engine"]
+        db[(PostgreSQL)]
+    end
+
+    subgraph external["External Services"]
+        luna["Luna-2"]
+        guardrails["Guardrails AI"]
+        custom["Custom Plugins"]
+    end
+
+    agent <--> sdk
+    sdk <-->|HTTP/JSON| api
+    api <--> engine
+    api <--> db
+    engine -.->|plugin calls| luna
+    engine -.->|plugin calls| guardrails
+    engine -.->|plugin calls| custom
+```
+
+## Package Structure
+
+```mermaid
+flowchart LR
+    subgraph packages["Python Packages"]
+        models["agent-control-models<br/>━━━━━━━━━━━━━━━<br/>Shared Pydantic models<br/>for API contracts"]
+
+        engine["agent-control-engine<br/>━━━━━━━━━━━━━━━<br/>Control evaluation logic<br/>Evaluators & Selectors"]
+
+        sdk["agent-control<br/>━━━━━━━━━━━━━━━<br/>Python SDK client<br/>@protect decorator"]
+
+        server["agent-control-server<br/>━━━━━━━━━━━━━━━<br/>FastAPI server<br/>Database layer"]
+    end
+
+    models --> engine
+    models --> sdk
+    models --> server
+    engine --> server
+    sdk -.->|HTTP| server
+```
+
+## Key Interactions
+
+| From | To | Protocol | Purpose |
+|------|-----|----------|---------|
+| AI Agent | SDK | In-process | Wrap agent calls with protection |
+| SDK | Server | HTTP/JSON | Register agents, evaluate requests |
+| Server | Database | SQL | Persist agents, policies, controls |
+| Engine | Plugins | In-process | Delegate to external evaluators |

diagrams/02-deployment-architecture.md

@@ -0,0 +1,97 @@
+# Deployment Architecture
+
+How Agent Protect components are deployed in a production environment.
+
+## Kubernetes Deployment
+
+```mermaid
+flowchart TB
+    subgraph k8s["Kubernetes Cluster"]
+        subgraph ns["agent-control namespace"]
+            subgraph deploy["Deployment: agent-control-server"]
+                pod1["Pod"]
+                pod2["Pod"]
+                pod3["Pod"]
+            end
+
+            svc["Service<br/>agent-control-server"]
+            hpa["HPA<br/>Auto-scaling"]
+
+            subgraph db["StatefulSet or Managed"]
+                pg[(PostgreSQL)]
+            end
+        end
+
+        ing["Ingress Controller"]
+    end
+
+    subgraph apps["Client Applications"]
+        app1["Agent App 1"]
+        app2["Agent App 2"]
+        app3["Agent App N"]
+    end
+
+    apps --> ing
+    ing --> svc
+    svc --> deploy
+    deploy --> pg
+    hpa -.->|scales| deploy
+```
+
+## Service Communication
+
+```mermaid
+flowchart LR
+    subgraph external["External"]
+        client["SDK Client"]
+    end
+
+    subgraph cluster["Kubernetes"]
+        ingress["Ingress<br/>:443"]
+        service["Service<br/>:8000"]
+
+        subgraph pods["Pods"]
+            uvicorn1["Uvicorn<br/>:8000"]
+            uvicorn2["Uvicorn<br/>:8000"]
+        end
+
+        postgres[(PostgreSQL<br/>:5432)]
+    end
+
+    client -->|HTTPS| ingress
+    ingress -->|HTTP| service
+    service -->|Round Robin| pods
+    pods -->|TCP| postgres
+```
+
+## Configuration
+
+```mermaid
+flowchart TD
+    subgraph config["Configuration Sources"]
+        env["Environment Variables<br/>━━━━━━━━━━━━━━━<br/>DATABASE_URL<br/>API_PREFIX<br/>DEBUG"]
+
+        secrets["Kubernetes Secrets<br/>━━━━━━━━━━━━━━━<br/>DB credentials<br/>API keys"]
+
+        configmap["ConfigMap<br/>━━━━━━━━━━━━━━━<br/>Feature flags<br/>Plugin configs"]
+    end
+
+    subgraph server["Server Pod"]
+        app["Agent Control Server"]
+    end
+
+    env --> app
+    secrets --> app
+    configmap --> app
+```
+
+## Endpoints
+
+| Path | Method | Description |
+|------|--------|-------------|
+| `/health` | GET | Liveness/readiness probe |
+| `/api/v1/agents/*` | * | Agent management |
+| `/api/v1/policies/*` | * | Policy management |
+| `/api/v1/control-sets/*` | * | Control set management |
+| `/api/v1/controls/*` | * | Control management |
+| `/api/v1/evaluation` | POST | Control evaluation |

diagrams/03-entity-relationships.md

@@ -0,0 +1,123 @@
+# Entity Relationships
+
+Database schema showing the hierarchical relationship between Agents, Policies, Control Sets, and Controls.
+
+## Entity Hierarchy
+
+```mermaid
+flowchart TD
+    agent["🤖 Agent"]
+    policy["📋 Policy"]
+    controlset["📦 Control Set"]
+    control["⚙️ Control"]
+
+    agent -->|"has one (optional)"| policy
+    policy -->|"has many"| controlset
+    controlset -->|"has many"| control
+```
+
+## Database Schema (ERD)
+
+```mermaid
+erDiagram
+    agents {
+        UUID agent_uuid PK "Primary key"
+        VARCHAR name UK "Unique agent name"
+        JSONB data "Agent metadata & tools"
+        INT policy_id FK "Optional policy reference"
+        TIMESTAMP created_at "Creation timestamp"
+    }
+
+    policies {
+        INT id PK "Auto-increment"
+        VARCHAR name UK "Unique policy name"
+    }
+
+    control_sets {
+        INT id PK "Auto-increment"
+        VARCHAR name UK "Unique control set name"
+    }
+
+    controls {
+        INT id PK "Auto-increment"
+        VARCHAR name UK "Unique control name"
+        JSONB data "ControlDefinition JSON"
+    }
+
+    policy_control_sets {
+        INT policy_id PK,FK
+        INT control_set_id PK,FK
+    }
+
+    control_set_controls {
+        INT control_set_id PK,FK
+        INT control_id PK,FK
+    }
+
+    agents ||--o| policies : "belongs to"
+    policies ||--o{ policy_control_sets : "has"
+    policy_control_sets }o--|| control_sets : "contains"
+    control_sets ||--o{ control_set_controls : "has"
+    control_set_controls }o--|| controls : "contains"
+```
+
+## Relationship Details
+
+### Agent → Policy (Many-to-One)
+- An Agent can optionally have one Policy assigned
+- A Policy can be shared across multiple Agents
+- When an Agent has no Policy, it has no active controls
+
+### Policy ↔ Control Set (Many-to-Many)
+- A Policy groups multiple Control Sets together
+- A Control Set can be reused across multiple Policies
+- Association managed via `policy_control_sets` junction table
+
+### Control Set ↔ Control (Many-to-Many)  
+- A Control Set groups multiple atomic Controls
+- A Control can be reused across multiple Control Sets
+- Association managed via `control_set_controls` junction table
+
+## Example Configuration
+
+```mermaid
+flowchart LR
+    subgraph agents["Agents"]
+        a1["customer-service-bot"]
+        a2["sales-assistant"]
+    end
+
+    subgraph policies["Policies"]
+        p1["production-policy"]
+    end
+
+    subgraph controlsets["Control Sets"]
+        cs1["pii-protection"]
+        cs2["content-safety"]
+    end
+
+    subgraph controls["Controls"]
+        c1["ssn-detector"]
+        c2["email-detector"]
+        c3["profanity-filter"]
+        c4["toxicity-check"]
+    end
+
+    a1 --> p1
+    a2 --> p1
+    p1 --> cs1
+    p1 --> cs2
+    cs1 --> c1
+    cs1 --> c2
+    cs2 --> c3
+    cs2 --> c4
+```
+
+## Data Traversal
+
+To get all Controls for an Agent:
+```
+Agent → Policy → ControlSets (via junction) → Controls (via junction)
+```
+
+This multi-hop traversal is performed server-side when processing evaluation requests.