# matsdk/taurpc architecture

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

- Interactive diagram: https://gitdiagram.com/matsdk/taurpc
- Repository: https://github.com/matsdk/taurpc

## Overview

##### Main components
- Rust Core Library – The heart of the project, containing the IPC logic. This includes:
- The API definitions (procedures) defined with macros in Rust.
- The resolvers that implement these procedures.
- State management constructs for sharing data.
- Event triggers and channel-based communication for emitting events.
- Macro Expansion Module – The “taurpc-macros” sub-crate, which processes the API traits (using procedural macros) to generate the necessary glue code for type generation and IPC handling.
- Type Generation Engine – Leveraging Specta (and optionally specta_typescript) to produce the TypeScript definitions based on Rust types at runtime.
- Tauri Integration – The Tauri runtime setup (evident in the src-tauri directories within both the project root and the “example” folder) that integrates the IPC layer with Tauri’s event and command system.
- Frontend Client – The generated TypeScript binding file (for instance, “bindings.ts”) alongside frontend source code (as in the example folder that uses Svelte) to illustrate how the typed API is called from the frontend.
- Build/Configuration/Developer Tools – The tooling files (.eslintrc, dprint.json, package.json, pnpm-lock.yaml, etc.), CI workflows (.github/workflows), and change logs used in development and continuous integration.

##### Relationships and data flow
- API Request Flow:
- From the frontend, calls are made using the generated TypeScript proxy.
- These calls are sent over Tauri’s IPC mechanism.
- The Rust backend (via the generated IPC handler from the macros and resolvers) receives, processes the request, and if needed, manages state or triggers events.
- Type Generation Flow:
- During development (or at runtime when the Tauri app is launched), the API definitions are processed by the procedural macros to output TS types (exported as “bindings.ts” or another specified file).
- This ensures that the frontend always has synchronized and strongly-typed definitions of the backend API.
- Event and Channel Communication:
- The backend can trigger events (e.g., to update progress or send computed data) that the frontend listens to using the same type-safe constructs.
- There is also support for channels where callbacks are sent over, ensuring one-to-one communication.

##### Architectural patterns and design principles
- Separation of Concerns:
- The system is split between macro generation, API resolution, event handling, and the Tauri integration layer.
- The “taurpc” crate (and its sub-crate “taurpc-macros”) encapsulates the IPC logic and type generation responsibility.
- Typed Bidirectional Communication:
- Emphasis on using Rust traits (with the #[taurpc::procedures] macros) to define backend procedures that are then mirrored as TypeScript types.
- This pattern helps eliminate many runtime errors by ensuring both ends of the IPC channel agree on the function signatures and data structures.
- Extensibility via Routers:
- Developer Experience:

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        TSBindings["Generated TS Bindings"]:::frontend
        ClientApp["Client App (Svelte)"]:::frontend
    end

    %% Tauri Integration Layer
    subgraph "Tauri Integration"
        IPCHandler["IPC Handler (Tauri Runtime)"]:::backend
    end

    %% Rust Backend Layer
    subgraph "Rust Backend"
        ApiCore["API Definitions & Resolvers"]:::rust
        MacroExpansion["Macro Expansion (taurpc-macros)"]:::rust
        TypeGen["Type Generation Engine (Specta)"]:::rust
    end

    %% Build/Configuration & Developer Tools
    subgraph "Build/Configuration & Developer Tools"
        BuildTools["CI/CD & Config Tools"]:::tools
    end

    %% API Request Flow
    ClientApp -->|"API_Calls"| IPCHandler
    IPCHandler -->|"Forward_IPC"| ApiCore
    ApiCore -->|"Events/Responses"| ClientApp

    %% Type Generation Flow (dashed)
    TypeGen -.->|"Generate_Types"| TSBindings

    %% Macro Expansion Connections (dashed)
    MacroExpansion -.->|"Generate_Glue_Code"| ApiCore
    MacroExpansion -.->|"Process_API_Traits"| TypeGen

    %% Developer Tools Influence (dashed)
    BuildTools ---|"Dev_Tools"| ApiCore
    BuildTools ---|"Dev_Tools"| IPCHandler
    BuildTools ---|"Dev_Tools"| ClientApp

    %% Click Events
    click ApiCore "https://github.com/matsdk/taurpc/blob/main/taurpc/src/lib.rs"
    click MacroExpansion "https://github.com/matsdk/taurpc/tree/main/taurpc/taurpc-macros"
    click TypeGen "https://github.com/matsdk/taurpc/blob/main/taurpc/src/export.rs"
    click IPCHandler "https://github.com/matsdk/taurpc/tree/main/example/src-tauri"
    click TSBindings "https://github.com/matsdk/taurpc/blob/main/example/src/lib/bindings.ts"
    click ClientApp "https://github.com/matsdk/taurpc/tree/main/example/src"
    click BuildTools "https://github.com/matsdk/taurpc/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef backend fill:#f7d794,stroke:#000,stroke-width:2px;
    classDef rust fill:#f4a261,stroke:#000,stroke-width:2px;
    classDef tools fill:#e9c46a,stroke:#000,stroke-width:2px;
```
