diff --git a/docs/README.md b/docs/README.md
index 813a37e..55488aa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -72,3 +72,7 @@ The employee directory page uses:
 - `htmx` for fragment-based form and summary updates
 - `Alpine.js` for lightweight page state
 - `Tabulator` for the interactive employee table
+
+## Flow chart
+
+See [`REQUEST_FLOW.md`](./REQUEST_FLOW.md) for a chart of how requests and responses move through the framework.
diff --git a/docs/REQUEST_FLOW.md b/docs/REQUEST_FLOW.md
new file mode 100644
index 0000000..98f3f50
--- /dev/null
+++ b/docs/REQUEST_FLOW.md
@@ -0,0 +1,61 @@
+# Request / Response Flow
+
+This chart shows how a browser request moves through the MindVisionCode framework and how a response is built and returned.
+
+```mermaid
+flowchart TD
+    A[Browser Request] --> B[public/index.php]
+    B --> C[autoload.php / vendor autoload]
+    B --> D[ensureSessionStarted()]
+    B --> E[Create App + Router]
+    B --> F[Load routes/web.php]
+    B --> G[Request::capture()]
+    G --> H[Dispatcher::dispatch()]
+    H --> I{Route matched?}
+    I -- No --> J[Response::notFound()]
+    I -- Yes --> K[Route::dispatch()]
+    K --> L[App::call()]
+    L --> M{Handler type}
+    M -- Controller method --> N[Controller action]
+    M -- Closure --> O[Route closure]
+    N --> P[Repository / ViewModel / Service calls]
+    P --> Q[Database::query() / execute()]
+    N --> R[view() / json() / redirect()]
+    O --> R
+    R --> S[Response object]
+    J --> S
+    H --> T[normalizeResponse()]
+    T --> S
+    S --> U[Response::send()]
+    U --> V[Browser receives HTML / JSON / redirect]
+```
+
+## Response building paths
+
+### View response
+
+```text
+Controller -> view() -> View::render() -> template -> layout -> Response
+```
+
+### JSON response
+
+```text
+Controller -> json() -> Response::json() -> Response::send()
+```
+
+### Redirect response
+
+```text
+Controller -> redirect() -> Response::redirect() -> Response::send()
+```
+
+## Key classes
+
+- `public/index.php` bootstraps the app
+- `Core\Dispatcher` matches routes and handles errors
+- `Core\Route` extracts route parameters
+- `Core\App` invokes controller methods or closures
+- `Core\Controller` gives actions helper methods
+- `Core\View` renders templates into a layout
+- `Core\Response` sends the final output