diff --git a/docs/roadmap.md b/docs/roadmap.md
index fd200523..f376e678 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -77,18 +77,42 @@ after formatting. Line numbers below refer to that file.
   - [ ] Define `FromMessageRequest` for extractor types (lines 760-782). See
     [`FromMessageRequest`][from-message-request] in
     [`src/extractor.rs`](../src/extractor.rs).
+
   - [ ] Provide built-in extractors `Message<T>`, `ConnectionInfo`, and
     `SharedState<T>` (lines 792-840). `SharedState<T>` is defined in
     [`src/extractor.rs`](../src/extractor.rs#L54-L87).
+
   - [ ] Support custom extractors implementing `FromMessageRequest` (lines
     842-858). Refer again to [`src/extractor.rs`](../src/extractor.rs#L39-L52).
-  - [ ] Implement middleware using `Transform`/`Service` traits and a simple
-    `from_fn` style variant (lines 866-899). Trait definitions live in
-    [`src/middleware.rs`](../src/middleware.rs#L71-L84).
-  - [ ] Register middleware with `WireframeApp::wrap` and execute it in order
-    (lines 900-919). See the [`wrap` method](../src/app.rs#L73-L84).
+
+  - [ ] Implement middleware using `Transform`/`Service` traits.
+
+    - [ ] Implement `ServiceRequest` and `ServiceResponse` wrappers (lines
+      866-899) and introduce a `Next` helper to build the asynchronous call
+      chain. Trait definitions live in
+      [`src/middleware.rs`](../src/middleware.rs#L71-L84).
+    - [ ] Provide a `from_fn` helper for functional middleware.
+    - [ ] Add tests verifying middleware can modify requests and observe
+      responses.
+
+  - [ ] Register middleware with `WireframeApp::wrap` and build the chain around
+    handlers, so the last registered middleware runs first on requests and first
+    on responses (lines 900-919). See the
+    [`wrap` method](../src/app.rs#L73-L84).
+
   - [ ] Document common middleware use cases like logging and authentication
-    (lines 920-935).
+    (lines 920-935). Include a logging example using `from_fn`:
+
+    ```rust
+    use wireframe::middleware::from_fn;
+
+    let logging = from_fn(|req, next| async move {
+        tracing::info!("request_frame = {:?}", req.frame());
+        let mut res = next.call(req).await?;
+        tracing::info!("response_frame = {:?}", res.frame());
+        Ok(res)
+    });
+    ```
 
 ## 3. Initial Examples and Documentation
 
diff --git a/docs/rust-binary-router-library-design.md b/docs/rust-binary-router-library-design.md
index da3e840b..91ec52dc 100644
--- a/docs/rust-binary-router-library-design.md
+++ b/docs/rust-binary-router-library-design.md
@@ -881,9 +881,45 @@ by implementing a pair of traits, analogous to Actix Web's `Transform` and
   returned service) and `#[inline]` for potential performance gains.
 - The `Service` trait would define the actual request/response processing
   logic. Middleware would operate on "wireframe's" internal request and
+
   response types, which could be raw frames at one level or deserialized
   messages at another, depending on the middleware's purpose.
 
+The relationships among these components are illustrated in the following
+diagram:
+
+```mermaid
+classDiagram
+    class ServiceRequest {
+    }
+    class ServiceResponse {
+    }
+    class Next {
+        +call(request: ServiceRequest): ServiceResponse
+    }
+    class Middleware {
+        <<interface>>
+        +call(request: ServiceRequest, next: Next): ServiceResponse
+    }
+    class Transform {
+        <<trait>>
+        +new_service(): Service
+    }
+    class Service {
+        <<trait>>
+        +call(request: ServiceRequest): ServiceResponse
+    }
+    class FromFn {
+        +from_fn(fn): Middleware
+    }
+    ServiceRequest <.. Next
+    ServiceResponse <.. Next
+    Middleware <|.. FromFn
+    Transform <|.. Middleware
+    Middleware <|.. Service
+    Next --> Middleware
+```
+
 A simplified functional middleware approach, similar to
 `actix_web::middleware::from_fn` 26, could also be provided for simpler use
 cases: