Update README.md

Author: 4th-cloud

README.md

@@ -9,58 +9,71 @@ Unlike traditional AI service layers, PolicyStream embeds **policy enforcement,
 
 ## ✨ Key Features  
 
-- **🔒 Security & Governance** → All requests evaluated by a Policy Enforcement Point (PEP) against organizational policies before execution.  
-- **📊 Observability & Auditability** → Every decision and model interaction logged into an Evidence Store for compliance reporting.  
-- **⚖️ Risk Awareness** → Dynamic checks against Data Protection Impact Assessments (DPIAs), risk registers, and compliance rules.  
-- **⚙️ Modular AI Runtime** → Supports Retrieval-Augmented Generation (RAG), tool brokers, and hosted/third-party LLMs.  
-- **☸️ Cloud-Native Design** → Deployable on Kubernetes (EKS, GKE, AKS, or on-prem), with GitHub Actions + GHCR pipelines.  
-- **🌐 Multitenancy + Regionalization** → Supports tenant-aware routing and regional data residency enforcement.  
+- **Security & Governance** → All requests evaluated by a Policy Enforcement Point (PEP) against organizational policies before execution.  
+- **Observability & Auditability** → Every decision and model interaction logged into an Evidence Store for compliance reporting.  
+- **Risk Awareness** → Dynamic checks against Data Protection Impact Assessments (DPIAs), risk registers, and compliance rules.  
+- **Modular AI Runtime** → Supports Retrieval-Augmented Generation (RAG), tool brokers, and hosted/third-party LLMs.  
+- **Cloud-Native Design** → Deployable on Kubernetes (EKS, GKE, AKS, or on-prem), with GitHub Actions + GHCR pipelines.  
+- **Multitenancy + Regionalization** → Supports tenant-aware routing and regional data residency enforcement.  
 
 ---
 
 ## 🏗️ Architecture Overview  
 
 ```mermaid
 flowchart TB
-  subgraph CLIENTS[Clients]
-    Web[🌐 Web App]
-    Mobile[📱 Mobile App]
-    Partner[🤝 Partner API]
+  %% Clients
+  subgraph CLIENTS["Clients"]
+    Web["Web App"]
+    Mobile["Mobile App"]
+    Partner["Partner API"]
   end
 
-  subgraph GATEWAY[Gateway + WAF]
-    AuthN[🔑 Auth & Tokens]
-    RateLimit[⏳ Rate Limiting]
-    Validate[🧾 Schema & Payload Validation]
-    PEP[⚖️ Policy Enforcement Point]
+  %% Edge / Gateway
+  subgraph GATEWAY["Gateway and WAF"]
+    AuthN["Auth and Tokens"]
+    RateLimit["Rate Limiting"]
+    Validate["Schema and Payload Validation"]
+    PEP["Policy Enforcement Point (PEP)"]
   end
 
-  subgraph AIMS[AIMS (Policy Decision Point)]
-    PDP[📜 Policy Rules Engine (OPA/Rego)]
-    Evidence[📂 Evidence Store (Audit Logs)]
+  %% AIMS / PDP
+  subgraph AIMS["AIMS - Policy Decision Point"]
+    PDP["Policy Rules Engine (OPA/Rego)"]
+    Evidence["Evidence Store (Audit Logs)"]
   end
 
-  subgraph SERVICES[Core AI Services]
-    RAG[📚 Retrieval-Augmented Gen]
-    Tools[🛠️ Tool Broker]
-    Models[🤖 Model Service(s)]
+  %% Core Services
+  subgraph SERVICES["Core AI Services"]
+    RAG["Retrieval-Augmented Generation"]
+    Tools["Tool Broker"]
+    Models["Model Service"]
   end
 
-  subgraph OBS[Observability & Audit]
-    Logs[📑 Logs & Traces]
-    Metrics[📈 Metrics & Usage]
-    SIEM[🛡️ Security Monitoring]
+  %% Observability
+  subgraph OBS["Observability and Audit"]
+    Logs["Logs and Traces"]
+    Metrics["Metrics and Usage"]
+    SIEM["Security Monitoring (SIEM/SOC)"]
   end
 
-  CLIENTS --> GATEWAY
+  %% Flows
+  Web --> GATEWAY
+  Mobile --> GATEWAY
+  Partner --> GATEWAY
+
   GATEWAY --> PEP
   PEP --> PDP
   PDP --> Evidence
-  PEP --> SERVICES
-  SERVICES --> RAG
-  SERVICES --> Tools
-  SERVICES --> Models
-  SERVICES --> Logs
+
+  PEP --> RAG
+  PEP --> Tools
+  PEP --> Models
+
+  RAG --> Logs
+  Tools --> Logs
+  Models --> Logs
+
   Logs --> SIEM
   Logs --> Metrics
 ```
@@ -69,39 +82,39 @@ flowchart TB
 
 ## 📦 Microservices  
 
-### 1. **Gateway**  
+### 1. Gateway
 - Routes client requests.  
-- Handles **auth, rate-limiting, WAF rules, and initial request validation**.  
+- Handles auth, basic rate-limiting, and payload validation.  
 - Forwards requests to PEP → AIMS → Services.  
 
-### 2. **PEP (Policy Enforcement Point)**  
+### 2. PEP (Policy Enforcement Point)
 - Intercepts every request.  
-- Calls **AIMS PDP** for policy decisions.  
-- Supports **allow, deny, modify** outcomes.  
+- Calls AIMS PDP for policy decisions.  
+- Supports allow / deny / modify outcomes.  
 
-### 3. **AIMS (AI Management System)**  
-- Central **policy decision point** (OPA/Rego).  
-- Stores **evidence of every decision** (audit trail).  
-- Integrates with enterprise **risk registers, DPIAs, and compliance APIs**.  
+### 3. AIMS (AI Management System)
+- Central policy decision point (OPA/Rego-ready).  
+- Stores evidence of every decision (audit trail).  
+- Integrates with risk registers, DPIAs, and compliance APIs.  
 
-### 4. **RAG Service**  
-- Provides **context retrieval** (from vector DB / knowledge base).  
+### 4. RAG Service
+- Provides context retrieval from a knowledge base/vector DB.  
 - Adds grounding to model responses.  
 
-### 5. **Tools Service**  
-- Acts as a **broker** for external APIs.  
-- Example: calendar integration, DB lookups, external compliance checks.  
+### 5. Tools Service
+- Broker for external APIs and system tools.  
+- Examples: calendars, DB lookups, compliance checks.  
 
-### 6. **Models Service**  
-- Simple hosted model stub (echo service for dev).  
-- Replaceable with OpenAI, Anthropic, or NVIDIA NIM APIs.  
+### 6. Models Service
+- Simple echo model for development.  
+- Swap for OpenAI, Anthropic, or NVIDIA NIM APIs.  
 
 ---
 
-## 🚀 Quick Start  
+## 🚀 Quick Start (Docker Compose)
 
-### Local Development (Docker Compose)  
 ```powershell
+# from repo root
 docker compose up --build -d
 ```
 
@@ -117,43 +130,50 @@ curl.exe http://localhost:8083/healthz   # models
 
 **Test Request**  
 ```powershell
-curl.exe -X POST http://localhost:8080/v1/route `
-  -H "Content-Type: application/json" `
-  -d "{\"user_id\":\"u1\",\"prompt\":\"Draft a friendly email (no secrets).\",\"sensitivity\":\"Public\",\"labels\":[\"Public\"]}"
+curl.exe -X POST http://localhost:8080/v1/route -H "Content-Type: application/json" -d "{"user_id":"u1","prompt":"Draft a friendly email (no secrets).","sensitivity":"Public","labels":["Public"]}"
 ```
 
 ---
 
-## ☸️ Kubernetes Deployment  
+## ☸️ Kubernetes Deployment (Helm)
 
 ```powershell
-# Push to GitHub Container Registry
+# Push images to GHCR
 docker login ghcr.io -u <USERNAME> -p <TOKEN>
 $services = @("gateway","pep","aims","rag","tools","models")
 foreach ($s in $services) {
   docker build -t ghcr.io/<org>/policystream/$s:dev ".\services\$s"
   docker push ghcr.io/<org>/policystream/$s:dev
 }
 
-# Deploy via Helm
+# Deploy with Helm
 helm upgrade --install policystream .\charts\policystream `
   -n prod --create-namespace `
   --set global.registry=ghcr.io/<org>/policystream `
   --set global.tag=dev
 ```
 
+**Verify**
+```powershell
+kubectl -n prod get pods
+kubectl -n prod get svc
+# optional port-forward for quick testing
+kubectl -n prod port-forward svc/policystream-gateway 8080:80
+curl.exe http://localhost:8080/healthz
+```
+
 ---
 
-## 📖 Roadmap  
+## 📖 Roadmap
 
-- [ ] Add **NVIDIA NIM API support** for accelerated inference.  
-- [ ] Integrate **Azure Purview** for enterprise governance.  
-- [ ] Support **multi-cluster Kubernetes federation**.  
-- [ ] Add **policy authoring UI** for non-technical stakeholders.  
+- Add NVIDIA NIM API support for accelerated inference.  
+- Integrate Azure Purview-style governance connectors.  
+- Multi-cluster federation support.  
+- Policy authoring UI for non-technical stakeholders.  
 
 ---
 
-## 📜 References (APA-style placeholders)  
+## 📜 References (APA-style placeholders)
 
 - Microsoft. (2023). *Microsoft Purview: Data governance at scale*. Microsoft Docs.  
 - Open Policy Agent. (2024). *OPA/Rego Policy Engine*. CNCF.