# kwsc98/fusen-rs architecture

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

- Interactive diagram: https://gitdiagram.com/kwsc98/fusen-rs
- Repository: https://github.com/kwsc98/fusen-rs

## Overview

##### Project type and purpose
- **Type**: A Rust-based RPC microservice framework with compile-time code generation via macros.
- **Purpose**: Provide a lightweight, high-performance abstraction over multiple RPC protocols (HTTP1/2 JSON, gRPC, Dubbo3), service registration/discovery (Nacos), and middleware (load-balancer, AOP–style aspects), all without external code generation scripts.

##### File structure
- **Workspace crates**:
- `fusen-common`: shared utilities (config parsers, logging, errors, codec abstractions, registry client, date utils).
- `fusen-macro`: derives and procedural macros that generate RPC client/server boilerplate at compile time.
- `fusen` (core runtime): implements the server and client runtime, protocol handlers (HTTP, gRPC, Dubbo “triple”), routing, filters, registration, and built-in support modules (compression, shutdown, telemetry).
- `examples`: demonstration client and server projects showing how to configure and run fusen in standalone, Fusen-registry, Dubbo, and SpringCloud modes.
- **Key patterns**:
- *Builder pattern* for `FusenApplicationContext` (initialization, adding servers/clients/handlers).
- *Plugin/AOP pattern* for `Handler`s: load-balance, logging aspect, etc.
- *Macro-driven RPC trait expansions* via `#[fusen_trait]`, `#[fusen_server]`, and client stubs like `DemoServiceClient`.
- **Config and deployment files**:
- `*-config.yaml` in examples → service registry (Nacos) & network settings.
- `Cargo.toml` at each crate → dependency graph / build.

##### README for additional insights
- **Multi-protocol support** (HTTP1/2, gRPC, Dubbo3 “tri”)
- **Service registry integration** with Nacos for Rust ↔ Java interoperability.
- **Extensibility points**: custom load balancers, AOP aspects, custom codecs.

##### Detail
- How **application context** wires together common utilities, registry client, protocol servers, and handler chain.
- **example apps** only as instantiations of the framework: user code → macros → runtime.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time Macro Generation
    subgraph "Build-time Macro Generation"
        direction TB
        DeriveMacro["Derive Macros"]:::buildtime
        ProcMacro["Procedural Macros"]:::buildtime
    end

    %% Common Utilities Library
    subgraph "Common Utilities (fusen-common)"
        direction TB
        ConfigParsers["Config Parsers"]:::common
        CodecAbstractions["Codec Abstractions"]:::common
        RegistryClientCommon["Registry Client"]:::common
        UtilsCommon["Logging / Errors / Date Utils"]:::common
    end

    %% Core Runtime
    subgraph "Core Runtime (fusen)"
        direction TB
        AppContext["Application Context Builder\n(lib.rs, server.rs)"]:::runtime
        ProtocolLayer["Protocol Layer"]:::runtime
        CodecImpls["Codec Implementations"]:::runtime
        RoutingLayer["Routing Layer"]:::runtime
        FilterChain["Filter Chain Framework"]:::runtime
        HandlerPlugins["Handler Plugins"]:::runtime
        RegistryIntegration["Registry Integration"]:::runtime
        SupportModules["Support Modules"]:::runtime
    end

    %% Example Applications
    subgraph "Example Applications"
        direction TB
        ServerApp["Example Server (#[fusen_server])"]:::runtime
        ClientApp["Example Client (DemoServiceClient)"]:::runtime
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Nacos["Nacos Registry"]:::external
        DubboJava["Dubbo3 Java Services"]:::external
        SpringCloud["SpringCloud Services"]:::external
    end

    %% Compile-time Flow
    UserTrait["User-defined Trait"]:::common
    UserTrait -->|expands| DeriveMacro
    UserTrait -->|expands| ProcMacro
    DeriveMacro -->|"generates"| ServerApp
    ProcMacro -->|"generates"| ClientApp

    %% Runtime Initialization
    AppContext -->|"reads configs"| ConfigParsers
    AppContext -->|"initializes"| RegistryIntegration
    AppContext -->|"configures"| ProtocolLayer
    AppContext -->|"wires"| FilterChain
    AppContext -->|"wires"| HandlerPlugins
    AppContext -->|"starts Tokio runtime"| SupportModules

    %% Request Flow
    ClientApp -->|"invokes stub"| ProtocolLayer
    ProtocolLayer -->|"decode"| CodecImpls
    CodecImpls -->|"route lookup"| RoutingLayer
    RoutingLayer -->|"apply filters"| FilterChain
    FilterChain -->|"invoke handler"| HandlerPlugins
    HandlerPlugins -->|"dispatch to"| ServerApp
    ServerApp -->|"business logic"| ServerApp
    ServerApp -->|"response"| HandlerPlugins
    HandlerPlugins --> CodecImpls
    CodecImpls --> ProtocolLayer
    ProtocolLayer --> ClientApp

    %% Service Discovery
    RegistryIntegration -->|"register/heartbeat"| Nacos
    ClientApp -->|"discover"| Nacos

    %% External Dependencies
    ProtocolLayer --> DubboJava
    ProtocolLayer --> SpringCloud

    %% Click Events
    click DeriveMacro "https://github.com/kwsc98/fusen-rs/tree/main/fusen-macro/derive-macro/src"
    click ProcMacro "https://github.com/kwsc98/fusen-rs/tree/main/fusen-macro/procedural-macro/src"
    click ConfigParsers "https://github.com/kwsc98/fusen-rs/blob/main/fusen-common/src/config/toml.rs"
    click CodecAbstractions "https://github.com/kwsc98/fusen-rs/blob/main/fusen-common/src/codec.rs"
    click RegistryClientCommon "https://github.com/kwsc98/fusen-rs/blob/main/fusen-common/src/register.rs"
    click AppContext "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/lib.rs"
    click AppContext "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/server.rs"
    click ProtocolLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/protocol/mod.rs"
    click ProtocolLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/protocol/http_handler.rs"
    click ProtocolLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/protocol/server.rs"
    click ProtocolLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/protocol/compression.rs"
    click ProtocolLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/protocol/socket.rs"
    click CodecImpls "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/codec/http_codec.rs"
    click CodecImpls "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/codec/grpc_codec.rs"
    click CodecImpls "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/codec/json_codec.rs"
    click RoutingLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/route/mod.rs"
    click RoutingLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/route/client.rs"
    click RoutingLayer "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/route/server.rs"
    click FilterChain "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/filter/mod.rs"
    click FilterChain "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/filter/server.rs"
    click HandlerPlugins "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/handler/aspect/mod.rs"
    click HandlerPlugins "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/handler/loadbalance/mod.rs"
    click RegistryIntegration "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/register/mod.rs"
    click RegistryIntegration "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/register/nacos.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/mod.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/compression.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/shutdown.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/grpc.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/triple.rs"
    click SupportModules "https://github.com/kwsc98/fusen-rs/blob/main/fusen/src/support/dubbo.rs"
    click ServerApp "https://github.com/kwsc98/fusen-rs/blob/main/examples/src/server.rs"
    click ClientApp "https://github.com/kwsc98/fusen-rs/blob/main/examples/src/client.rs"

    %% Styles
    classDef buildtime fill:#f9f,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef common fill:#ff9,stroke:#333,stroke-width:1px
    classDef runtime fill:#9f9,stroke:#333,stroke-width:1px
    classDef external fill:#ccf,stroke:#333,stroke-width:1px
```
