Add request and response flow chart

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.

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.

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