Add comprehensive RustAPI cookbook documentation

Introduces a new, structured documentation set for RustAPI, including sections on getting started, core concepts, crate deep dives, and practical recipes. Updates SUMMARY.md to reflect the new organization and adds detailed guides on handlers, performance, testing, crate internals, and common development tasks such as CRUD resources, JWT authentication, database integration, file uploads, middleware, and production tuning.

Author: Tuntii

docs/cookbook/src/SUMMARY.md

@@ -2,15 +2,35 @@
 
 [Introduction](introduction.md)
 
-- [Part I: The Architecture](architecture/README.md)
-    - [The Action Pattern](architecture/action_pattern.md)
-    - [Performance Philosophy](architecture/performance.md)
-    - [Testing Pyramid](architecture/testing_strategy.md)
+- [Part I: Getting Started](getting_started/README.md)
+    - [Installation](getting_started/installation.md)
+    - [Quickstart](getting_started/quickstart.md)
+    - [Project Structure](getting_started/structure.md)
 
-- [Part II: Recipes](recipes/README.md)
-    - [Adding a New Feature](recipes/new_feature.md)
-    - [Quality & Maintenance](recipes/maintenance.md)
-    - [Performance Tuning](recipes/tuning.md)
-    - [Simulating CI](recipes/ci_simulation.md)
+- [Part II: Core Concepts](concepts/README.md)
+    - [Handlers & Extractors](concepts/handlers.md)
+    - [Performance Philosophy](concepts/performance.md)
+    - [Testing Strategy](concepts/testing.md)
+
+- [Part III: Crate Deep Dives](crates/README.md)
+    - [rustapi-core: The Engine](crates/rustapi_core.md)
+    - [rustapi-macros: The Magic](crates/rustapi_macros.md)
+    - [rustapi-validate: The Gatekeeper](crates/rustapi_validation.md)
+    - [rustapi-openapi: The Cartographer](crates/rustapi_openapi.md)
+    - [rustapi-extras: The Toolbox](crates/rustapi_extras.md)
+    - [rustapi-toon: The Diplomat](crates/rustapi_toon.md)
+    - [rustapi-ws: The Live Wire](crates/rustapi_ws.md)
+    - [rustapi-view: The Artist](crates/rustapi_view.md)
+    - [rustapi-jobs: The Workhorse](crates/rustapi_jobs.md)
+    - [rustapi-testing: The Auditor](crates/rustapi_testing.md)
+    - [cargo-rustapi: The Architect](crates/cargo_rustapi.md)
+
+- [Part IV: Recipes](recipes/README.md)
+    - [Creating Resources](recipes/crud_resource.md)
+    - [JWT Authentication](recipes/jwt_auth.md)
+    - [Database Integration](recipes/db_integration.md)
+    - [File Uploads](recipes/file_uploads.md)
+    - [Custom Middleware](recipes/custom_middleware.md)
+    - [Real-time Chat](recipes/websockets.md)
+    - [Production Tuning](recipes/high_performance.md)
 
-- [Part III: Reference](reference/README.md)

docs/cookbook/src/concepts/README.md

@@ -0,0 +1,3 @@
+# Core Concepts
+
+Documentation of the fundamental architectural decisions and patterns in RustAPI.

docs/cookbook/src/concepts/handlers.md

@@ -0,0 +1,140 @@
+# Handlers & Extractors
+
+The **Handler** is the fundamental unit of work in RustAPI. It transforms an incoming HTTP request into an outgoing HTTP response.
+
+Unlike many web frameworks that enforce a strict method signature (e.g., `fn(req: Request, res: Response)`), RustAPI embraces a flexible, type-safe approach powered by Rust's trait system.
+
+## The Philosophy: "Ask for what you need"
+
+In RustAPI, you don't manually parse the request object inside your business logic. Instead, you declare the data you need as function arguments, and the framework's **Extractors** handle the plumbing for you.
+
+If the data cannot be extracted (e.g., missing header, invalid JSON), the request is rejected *before* your handler is ever called. This means your handler logic is guaranteed to operate on valid, type-safe data.
+
+## Anatomy of a Handler
+
+A handler is simply an asynchronous function that takes zero or more **Extractors** as arguments and returns something that implements `IntoResponse`.
+
+```rust
+use rustapi::prelude::*;
+
+async fn create_user(
+    State(db): State<DbPool>,         // 1. Dependency Injection
+    Path(user_id): Path<Uuid>,        // 2. URL Path Parameter
+    Json(payload): Json<CreateUser>,  // 3. JSON Request Body
+) -> Result<impl IntoResponse, ApiError> {
+    
+    let user = db.create_user(user_id, payload).await?;
+    
+    Ok((StatusCode::CREATED, Json(user)))
+}
+```
+
+### Key Rules
+1. **Order Matters (Slightly)**: Extractors that consume the request body (like `Json<T>` or `Multipart`) must be the *last* argument. This is because the request body is a stream that can only be read once.
+2. **Async by Default**: Handlers are `async fn`. This allows non-blocking I/O operations (DB calls, external API requests).
+3. **Debuggable**: Handlers are just functions. You can unit test them easily.
+
+## Extractors: The `FromRequest` Trait
+
+Extractors are types that implement `FromRequest` (or `FromRequestParts` for headers/query params). They isolate the "HTTP parsing" logic from your "Business" logic.
+
+### Common Build-in Extractors
+
+| Extractor | Source | Example Usage |
+|-----------|--------|---------------|
+| `Path<T>` | URL Path Segments | `fn get_user(Path(id): Path<u32>)` |
+| `Query<T>` | Query String | `fn search(Query(params): Query<SearchFn>)` |
+| `Json<T>` | Request Body | `fn update(Json(data): Json<UpdateDto>)` |
+| `HeaderMap` | HTTP Headers | `fn headers(headers: HeaderMap)` |
+| `State<T>` | Application State | `fn db_op(State(pool): State<PgPool>)` |
+| `Extension<T>` | Request-local extensions | `fn logic(Extension(user): Extension<User>)` |
+
+### Custom Extractors
+
+You can create your own extractors to encapsulate repetitive validation or parsing logic. For example, extracting a user ID from a verified JWT:
+
+```rust
+pub struct AuthenticatedUser(pub Uuid);
+
+#[async_trait]
+impl<S> FromRequestParts<S> for AuthenticatedUser
+where
+    S: Send + Sync,
+{
+    type Rejection = ApiError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let auth_header = parts.headers.get("Authorization")
+            .ok_or(ApiError::Unauthorized("Missing token"))?;
+        
+        let token = auth_header.to_str().map_err(|_| ApiError::Unauthorized("Invalid token"))?;
+        let user_id = verify_jwt(token)?; // Your verification logic
+        
+        Ok(AuthenticatedUser(user_id))
+    }
+}
+
+// Usage in handler: cleaner and reusable!
+async fn profile(AuthenticatedUser(uid): AuthenticatedUser) -> impl IntoResponse {
+    format!("User ID: {}", uid)
+}
+```
+
+## Responses: The `IntoResponse` Trait
+
+A handler can return any type that implements `IntoResponse`. RustAPI provides implementations for many common types:
+
+- `StatusCode` (e.g., return `200 OK` or `404 Not Found`)
+- `Json<T>` (serializes struct to JSON)
+- `String` / `&str` (plain text response)
+- `Vec<u8>` / `Bytes` (binary data)
+- `HeaderMap` (response headers)
+- `Html<String>` (HTML content)
+
+### Tuple Responses
+You can combine types using tuples to set status codes and headers along with the body:
+
+```rust
+// Returns 201 Created + JSON Body
+async fn create() -> (StatusCode, Json<User>) {
+    (StatusCode::CREATED, Json(user))
+}
+
+// Returns Custom Header + Plain Text
+async fn custom() -> (HeaderMap, &'static str) {
+    let mut headers = HeaderMap::new();
+    headers.insert("X-Custom", "Value".parse().unwrap());
+    (headers, "Response with headers")
+}
+```
+
+### Error Handling
+
+Handlers often return `Result<T, E>`. If the handler returns `Ok(T)`, the `T` is converted to a response. If it returns `Err(E)`, the `E` is converted to a response.
+
+This effectively means your `Error` type must implement `IntoResponse`.
+
+```rust
+// Recommended pattern: Centralized API Error enum
+pub enum ApiError {
+    NotFound(String),
+    InternalServerError,
+}
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        let (status, message) = match self {
+            ApiError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
+            ApiError::InternalServerError => (StatusCode::INTERNAL_SERVER_ERROR, "Something went wrong".to_string()),
+        };
+        
+        (status, Json(json!({ "error": message }))).into_response()
+    }
+}
+```
+
+## Best Practices
+
+1. **Keep Handlers Thin**: Move complex business logic to "Service" structs or domain modules. Handlers should focus on HTTP translation (decoding request -> calling service -> encoding response).
+2. **Use `State` for Dependencies**: Avoid global variables. Pass DB pools and config via `State`.
+3. **Parse Early**: Use specific types in `Json<T>` structs rather than `serde_json::Value` to leverage the type system for validation.

docs/cookbook/src/concepts/performance.md

@@ -0,0 +1,83 @@
+# Performance Philosophy
+
+RustAPI is built on a simple premise: **Abstractions shouldn't cost you runtime performance.**
+
+We leverage Rust's unique ownership system and modern async ecosystem (Tokio, Hyper) to deliver performance that rivals C++ servers, while maintaining developer safe-guards.
+
+## The Pillars of Speed
+
+### 1. Zero-Copy Networking
+Where possible, RustAPI avoids copying memory. When you receive a large JSON payload or file upload, we aim to pass pointers to the underlying memory buffer rather than cloning the data.
+
+- **`Bytes` over `Vec<u8>`**: We use the `bytes` crate extensively. Passing a `Bytes` object around is `O(1)` (it's just a reference-counted pointer and length), whereas cloning a `Vec<u8>` is `O(n)`.
+- **String View**: Extractors like `Path` and `Query` often leverage `Cow<'str, str>` (Clone on Write) to avoid allocations if the data doesn't need to be modified.
+
+### 2. Multi-Core Async Runtime
+RustAPI runs on **Tokio**, a work-stealing, multi-threaded runtime.
+
+- **Non-blocking I/O**: A single thread can handle thousands of concurrent idle connections (e.g., WebSockets waiting for messages) with minimal memory overhead.
+- **Work Stealing**: If one CPU core is overloaded with tasks, other idle cores will "steal" work from its queue, ensuring balanced utilization of your hardware.
+
+### 3. Compile-Time Router
+Our router (`matchit`) is based on a **Radix Trie** structure.
+
+- **O(log n) Lookup**: Route matching speed depends on the length of the URL, *not* the number of routes defined. Having 10 routes or 10,000 routes has negligible impact on routing latency.
+- **Allocation-Free Matching**: For standard paths, routing decisions happen without heap allocations.
+
+## Memory Management
+
+### Stack vs. Heap
+RustAPI encourages stack allocation for small, short-lived data.
+- **Extractors** are often allocated on the stack.
+- **Response bodies** are streamed, meaning a 1GB file download doesn't require 1GB of RAM. It flows through a small, constant-sized buffer.
+
+### Connection Pooling
+For database performance, we strongly recommend using connection pooling (e.g., `sqlx::Pool`).
+- **Reuse**: Establishing a TCP connection and performing a simplified SSL handshake for every request is slow. Pooling keeps connections open and ready.
+- **Multiplexing**: Some drivers allow multiple queries to be in-flight on a single connection simultaneously.
+
+## Optimizing Your App
+
+To get the most out of RustAPI, follow these guidelines:
+
+1. **Avoid Blocking the Async Executor**: Never run CPU-intensive tasks (cryptography, image processing) or blocking I/O (std::fs::read) directly in an async handler.
+    - *Solution*: Use `tokio::task::spawn_blocking` to offload these to a dedicated thread pool.
+    
+    ```rust
+    // BAD: Blocks the thread, potentially stalling other requests
+    fn handler() {
+        let digest = tough_crypto_hash(data); 
+    }
+    
+    // GOOD: Runs on a thread meant for blocking work
+    async fn handler() {
+        let digest = tokio::task::spawn_blocking(move || {
+            tough_crypto_hash(data)
+        }).await.unwrap();
+    }
+    ```
+
+2. **JSON Serialization**: While `serde` is fast, JSON text processing is CPU heavy.
+    - For extremely high-throughput endpoints, consider binary formats like **Protobuf** or **MessagePack** if the client supports it.
+
+3. **Keep `State` Light**: Your `State` struct is cloned for every request. Wrap large shared data in `Arc<T>` so only the pointer is cloned, not the data itself.
+
+```rust
+// Fast
+#[derive(Clone)]
+struct AppState {
+    db: PgPool,                // Internally uses Arc
+    config: Arc<Config>,       // Wrapped in Arc manually
+}
+```
+
+## Benchmarking
+
+Performance is not a guessing game. Use tools like `wrk`, `k6`, or `drill` to stress-test your specific endpoints.
+
+```bash
+# Example using drill
+drill --benchmark benchmark.yml --stats
+```
+
+Remember: RustAPI provides the *capability* for high performance, but your application logic ultimately dictates the speed. Use the tools wisely.