From fdfc54252ce7528dffd7f39f3f703cec567f6f4a Mon Sep 17 00:00:00 2001
From: Ishaan Jaffer <ishaanjaffer0324@gmail.com>
Date: Thu, 22 Jan 2026 14:57:43 -0800
Subject: [PATCH] init Architecture Diagram

---
 litellm/proxy/policy_engine/architecture.md | 54 +++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 litellm/proxy/policy_engine/architecture.md

diff --git a/litellm/proxy/policy_engine/architecture.md b/litellm/proxy/policy_engine/architecture.md
new file mode 100644
index 00000000000..fa9cbeecf5d
--- /dev/null
+++ b/litellm/proxy/policy_engine/architecture.md
@@ -0,0 +1,54 @@
+# Policy Engine Architecture
+
+## Overview
+
+The Policy Engine allows administrators to define policies that combine guardrails with scoping rules. Policies can target specific teams, API keys, and models using wildcard patterns, and support inheritance from base policies.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph Config["config.yaml"]
+        PC[policies config]
+    end
+
+    subgraph PolicyEngine["Policy Engine"]
+        PR[PolicyRegistry]
+        PV[PolicyValidator]
+        PM[PolicyMatcher]
+        PRe[PolicyResolver]
+    end
+
+    subgraph Request["Incoming Request"]
+        CTX[Context: team_alias, key_alias, model]
+    end
+
+    subgraph Output["Output"]
+        GR[Guardrails to Apply]
+    end
+
+    PC -->|load| PR
+    PC -->|validate| PV
+    PV -->|errors/warnings| PR
+    
+    CTX -->|match| PM
+    PM -->|matching policies| PRe
+    PR -->|policies| PM
+    PR -->|policies| PRe
+    PRe -->|resolve inheritance + add/remove| GR
+```
+
+## Components
+
+| Component | File | Description |
+|-----------|------|-------------|
+| **PolicyRegistry** | `policy_registry.py` | In-memory singleton store for parsed policies |
+| **PolicyValidator** | `policy_validator.py` | Validates configs (guardrails, inheritance, teams/keys/models) |
+| **PolicyMatcher** | `policy_matcher.py` | Matches request context against policy scopes |
+| **PolicyResolver** | `policy_resolver.py` | Resolves final guardrails via inheritance chain |
+
+## Flow
+
+1. **Startup**: `init_policies()` loads policies from config, validates, and populates `PolicyRegistry`
+2. **Request**: `PolicyMatcher` finds policies matching the request's team/key/model
+3. **Resolution**: `PolicyResolver` traverses inheritance and applies add/remove to get final guardrails