# hmathsan/rest_framework_rs architecture

> Architecture diagram of the GitHub repository hmathsan/rest_framework_rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hmathsan/rest_framework_rs
- Repository: https://github.com/hmathsan/rest_framework_rs

## Overview

##### Project Type and Purpose
- This is a small, modular Rust REST-framework and sample server application (not a distributed microservice).
- Its goal is educational: to provide a basic HTTP server with JSON (de)serialization, routing via macros, and a toy “mount” interface for handlers.

##### File Structure
- Top-level crates:
- macros/ — a procedural-macro crate generating request/response boilerplate
- server/ — the core HTTP server framework (routing, parsing, model types, utilities)
- src/main.rs — the example binary that ties everything together
- Inside server/:
- server.rs — TCP listener setup and event loop
- model/ — request/response entities and enums (status codes, parse errors, HTTP methods)
- macros.rs & macros/ — support for procedural routing macros (get!, post!, etc.)
- server_utils/ — default handlers and helpers
- Dependencies: serde (for JSON), std::net (TCP), std::collections (HashMap)

##### Extract Architectural Insights from README
- The framework uses derive-macros to auto-implement Serialize/Deserialize and routing traits
- Handlers have the signature (headers, params, typed-body) → ResponseEntity
- Mounting is macro-driven, e.g. get!["/path", handler_fn]

##### Main Components and Their Interactions
a. Components:
1. Client (e.g., Postman/Browser)
2. TCP Listener (std::net::TcpListener)
3. HTTP Parser & Router (server::Server)
4. Routing Macros (macros crate + server/src/macros)
5. Model Layer (server::model)
6. Handler Functions (user code in main.rs)
7. Response Serializer (serde via ResponseEntity)
b. Data Flow:
- Client → TCP Listener → HTTP Parser → Router matches path & method
- Router invokes macro-generated dispatch code → calls user handler
- Handler returns ResponseEntity → JSON serialized → TCP write back to client
c. Architectural Patterns:
- Layered design (Network I/O → HTTP/Core → Model → User Handlers)
- Code-generation via procedural macros separates routing boilerplate from core logic
- Loose coupling: server core doesn’t depend on any specific handler code until mount time
d. Key Technologies:
- Rust crates: serde, serde_derive, std::net, std::collections
- Procedural macros for #[derive(Request)]/#[derive(Response)] and get!/post! macros
- Modular crate structure (macros, server, binary)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    Client["Client"]:::external

    %% Network Layer
    subgraph "Network I/O"
        TCP["TCP Listener"]:::network
        TCPWrite["TCP Listener Write"]:::network
    end

    %% Core Framework
    subgraph "Framework Core"
        Parser["HTTP Parser & Router"]:::core
        subgraph "Server Utilities"
            UtilsMain["server_utils.rs"]:::core
            UtilsReturns["default_returns.rs"]:::core
            UtilsUtils["server_utils.rs"]:::core
        end
    end

    %% Compile-time Macros
    subgraph "Routing Macros"
        MacroCrate["macros/src/lib.rs"]:::core
        ServerMacros["server/src/macros.rs"]:::core
        MountMacros["mount_macros.rs"]:::core
    end

    %% Model Layer
    subgraph "Model Layer"
        ModelMain["model.rs"]:::core
        Request["request.rs"]:::core
        Response["response.rs"]:::core
        ResponseEntity["response_entity.rs"]:::core
        subgraph "enums"
            Method["method.rs"]:::core
            ParseError["parse_error.rs"]:::core
            StatusCode["status_code.rs"]:::core
        end
    end

    %% User Code
    Handler["User Handler"]:::user

    %% Serializer
    Serializer["Response Serializer"]:::external

    %% Flow
    Client -->|Raw TCP data| TCP
    TCP -->|Stream| Parser
    Parser -->|Compile-time hooks| MacroCrate
    Parser -->|Compile-time hooks| ServerMacros
    Parser -->|Compile-time hooks| MountMacros
    Parser -->|Parsed HTTP| ModelMain
    MacroCrate -->|Dispatch code| Handler
    ServerMacros -->|Dispatch code| Handler
    MountMacros -->|Dispatch code| Handler
    ModelMain -->|Typed Request| Handler
    Request --> Handler
    Response --> Handler
    Handler -->|ResponseEntity| ResponseEntity
    ResponseEntity -->|Serialize JSON| Serializer
    Serializer -->|JSON bytes| TCPWrite
    TCPWrite -->|Raw TCP data| Client

    %% Click Events
    click TCP "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/server.rs"
    click Parser "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/lib.rs"
    click MacroCrate "https://github.com/hmathsan/rest_framework_rs/blob/master/macros/src/lib.rs"
    click ServerMacros "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/macros.rs"
    click MountMacros "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/macros/mount_macros.rs"
    click ModelMain "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model.rs"
    click Request "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/request.rs"
    click Response "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/response.rs"
    click ResponseEntity "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/response_entity.rs"
    click Method "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/enums/method.rs"
    click ParseError "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/enums/parse_error.rs"
    click StatusCode "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/enums/status_code.rs"
    click Handler "https://github.com/hmathsan/rest_framework_rs/blob/master/src/main.rs"
    click Serializer "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/model/response_entity.rs"
    click UtilsMain "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/server_utils.rs"
    click UtilsReturns "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/server_utils/default_returns.rs"
    click UtilsUtils "https://github.com/hmathsan/rest_framework_rs/blob/master/server/src/server_utils/server_utils.rs"

    %% Styles
    classDef network fill:#e2f7e1,stroke:#4CAF50,stroke-width:2px
    classDef core fill:#d0e7ff,stroke:#2196F3,stroke-width:2px
    classDef user fill:#ffe0b2,stroke:#FF9800,stroke-width:2px
    classDef external fill:#f0f0f0,stroke:#9e9e9e,stroke-width:2px
```
