# andogq/qubit architecture

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

- Interactive diagram: https://gitdiagram.com/andogq/qubit
- Repository: https://github.com/andogq/qubit

## Overview

##### Project type and purpose
- This is an open-source monorepo containing a Rust library (qubit), a Rust procedural-macro crate (qubit-macros), a TypeScript client package (@qubit-rs/client), a Svelte integration example/package, and multiple end-to-end example applications.
- Its purpose is to provide seamless, type-safe JSONRPC 2.0-based RPC between Rust servers and TypeScript clients, generating TS bindings from Rust code and offering both HTTP and WebSocket transports.

##### File structure
- Top-level:
- Cargo workspace (Cargo.toml, crates/, src/) for the Rust library and macros.
- packages/ (client, svelte) for the TypeScript client and Svelte integration.
- examples/ demonstrating authentication, chaos test, chat-room React app, counter, hello-world.
- config and CI/CD (.github, pnpm-workspace.yaml, scripts).
- Rust crates:
- crates/qubit-macros: procedural macros for analysing handler attributes, codegen of TypeScript types.
- src/: core library—handler definitions, router builder, JSONRPC service adapter, TS-binding code.
- TS packages:
- packages/client: build_client, transport layers (http, ws), JSONRPC framing, handler/query/mutation/subscription wrappers.
- packages/svelte: opinionated UI template integrating the generated client in a SvelteKit app.

##### README for additional insights
- Core flow: define Rust functions with #[handler(query/mutation/subscription)], compose into a Router, call router.write_bindings_to_dir(), embed router in an Axum/Hyper server via jsonrpsee, then import generated TS bindings in TypeScript and call build_client<Bindings>(transport).
- Leverages serde for data serialization, ts-rs for type generation, jsonrpsee for RPC transport, and common Rust async ecosystem (tokio, axum).

##### Detail
- Every major crate, package, and example integration.
- Nested-router pattern inside the Rust server and subscription flow over WS.
- Annotations: e.g., “serde serialises payloads to JSON”, “ts-rs generates .d.ts”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Phase
    subgraph "Build Phase"
        direction TB
        mac["qubit-macros (Codegen)"]:::rustbuild
        tsgen["TS Binding Generator"]:::rustbuild
        lib_rs["qubit crate (src/lib.rs)"]:::rustbuild
        mac -->|"analyzes handler attributes"| tsgen
        tsgen -->|"generates TS bindings"| lib_rs
    end

    %% Runtime Server
    subgraph "Runtime Server"
        direction TB
        router["Rust JSONRPC Server"]:::server
        jsonrpsee["jsonrpsee"]:::external
        axum["axum/hyper"]:::external
        serde["serde"]:::external
        router -->|handles RPC| jsonrpsee
        jsonrpsee -->|runs on| axum
        router -->|uses| serde
    end

    %% Client Library
    subgraph "TypeScript Client"
        direction TB
        client_lib["@qubit-rs/client"]:::client
        transport_http["HTTP Transport"]:::client
        transport_ws["WebSocket Transport"]:::client
        client_lib -->|uses| transport_http
        client_lib -->|uses| transport_ws
    end

    %% Examples
    subgraph "Example Applications"
        direction TB
        auth["Authentication Example"]:::example
        chaos["Chaos Test Example"]:::example
        chat["Chat-room React Example"]:::example
        counter["Counter Example"]:::example
        hello["Hello-World Example"]:::example

        auth --> client_lib
        chaos --> client_lib
        chat --> client_lib
        counter --> client_lib
        hello --> client_lib
    end

    %% Integration Flow
    lib_rs -->|"write_bindings_to_dir()"| tsgen
    client_lib -->|"import bindings & call RPC"| router

    click mac "https://github.com/andogq/qubit/blob/main/crates/qubit-macros/Cargo.toml"
    click mac "https://github.com/andogq/qubit/blob/main/crates/qubit-macros/src/lib.rs"
    click mac "https://github.com/andogq/qubit/tree/main/crates/qubit-macros/src/macros/handler/"
    click mac "https://github.com/andogq/qubit/blob/main/crates/qubit-macros/src/macros/ts.rs"
    click tsgen "https://github.com/andogq/qubit/blob/main/src/ts.rs"
    click lib_rs "https://github.com/andogq/qubit/blob/main/src/lib.rs"
    click transport_http "https://github.com/andogq/qubit/tree/main/packages/client/src/transport/"
    click transport_ws "https://github.com/andogq/qubit/tree/main/packages/client/src/transport/"
    click client_lib "https://github.com/andogq/qubit/blob/main/packages/client/src/client.ts"
    click auth "https://github.com/andogq/qubit/blob/main/examples/authentication/src/main.rs"
    click chaos "https://github.com/andogq/qubit/blob/main/examples/chaos/src/main.rs"
    click chat "https://github.com/andogq/qubit/blob/main/examples/chat-room-react/src-rust/src/main.rs"
    click counter "https://github.com/andogq/qubit/blob/main/examples/counter/src/main.rs"
    click hello "https://github.com/andogq/qubit/blob/main/examples/hello-world/src/main.rs"

    classDef rustbuild fill:#b2f2bb,stroke:#2f9e44,color:#2f9e44
    classDef server fill:#91a7ff,stroke:#4263eb,color:#4263eb
    classDef client fill:#ffd8a8,stroke:#f08c00,color:#f08c00
    classDef external fill:#e9ecef,stroke:#868e96,color:#495057
    classDef example fill:#ffe3e3,stroke:#fa5252,color:#c92a2a
```
