From 5fabe4b49c9c4e386902a656adf7d23d60eb856e Mon Sep 17 00:00:00 2001
From: Daniel Covington <daniel.covington@example.com>
Date: Sun, 10 May 2026 06:35:32 -0400
Subject: [PATCH] Add request and response flow chart

---
 README.md            |  4 +++
 docs/README.md       |  4 +++
 docs/REQUEST_FLOW.md | 61 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 docs/REQUEST_FLOW.md

diff --git a/README.md b/README.md
index 8f233d7..d858079 100644
--- a/README.md
+++ b/README.md
@@ -40,3 +40,7 @@ php scripts/migrate.php status
 php scripts/migrate.php fresh --seed
 php scripts/seed_projects.php 6
 ```
+
+## Framework flow
+
+See `docs/REQUEST_FLOW.md` for a chart of how requests and responses move through the framework.
diff --git a/docs/README.md b/docs/README.md
index 7deaf13..6466a99 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -51,3 +51,7 @@ php scripts/migrate.php fresh
 php scripts/migrate.php fresh --seed
 php scripts/seed_projects.php 6
 ```
+
+## Flow chart
+
+See [`REQUEST_FLOW.md`](./REQUEST_FLOW.md) for the request/response flow chart.
diff --git a/docs/REQUEST_FLOW.md b/docs/REQUEST_FLOW.md
new file mode 100644
index 0000000..a3ad4cc
--- /dev/null
+++ b/docs/REQUEST_FLOW.md
@@ -0,0 +1,61 @@
+# Request / Response Flow
+
+This diagram shows how a browser request moves through the Mind-Vision-Code framework and how the response gets built and sent back.
+
+```mermaid
+flowchart TD
+    A[Browser Request] --> B[public/index.php]
+    B --> C[autoload.php]
+    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 / 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