diff --git a/README.md b/README.md
index 457c74c..886aeee 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,32 @@ This bot is designed to run once for many repositories in `Bram/*` instead of du
 10. `src/gitea/review-api.ts` posts review and handles inline comment fallback.
 11. `src/gitea/reviewer-api.ts` removes bot reviewer from PR.
 
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+  A[Gitea Webhook] --> B[src/server.ts]
+  B --> C[verify-signature.ts]
+  C --> D[event-router.ts]
+  D --> E[review-runner.ts]
+
+  E --> F[dedupe-store.ts]
+  E --> G[should-process-event.ts]
+  E --> H[load-repo-config.ts]
+  E --> I[gitea/client.ts]
+  E --> J[build-review-prompt.ts]
+  E --> K[review-agent.ts]
+  K --> L[Cursor Cloud Agent.prompt]
+  K --> M[review-schema.ts]
+
+  E --> N[review-api.ts]
+  N --> O[POST /pulls/{index}/reviews]
+  N --> P[DELETE prior bot reviews]
+
+  E --> Q[reviewer-api.ts]
+  Q --> R[PATCH reviewers remove bot]
+```
+
 ## Project Structure
 
 ### Server and Webhook Layer