# mariomatheuspombal/actix-glpc architecture

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

- Interactive diagram: https://gitdiagram.com/mariomatheuspombal/actix-glpc
- Repository: https://github.com/mariomatheuspombal/actix-glpc

## Overview

##### Project type and purpose
- This is an open-source Rust library suite implementing an actor-model framework (“actix”), a set of procedural macros to simplify message definitions (“actix-derive”), and a publish/subscribe broker extension (“actix-broker”).
- The primary goal is to provide a highly concurrent, asynchronous runtime for actors, plus utility crates for automating boilerplate and enabling pub/sub within that runtime.

##### File structure
- Top‐level crates:
- actix/           → core runtime (actors, contexts, mailboxes, scheduler, futures integration).
- actix-derive/    → proc-macro definitions (Message, MessageResponse, runtime entrypoint annotations).
- actix-broker/    → actor-based pub/sub broker, example brokers and client APIs.
- Shared configuration files at root (Cargo.toml, CI workflows, formatting rules) orchestrate testing and publication of all crates.
- Examples and tests in each crate demonstrate usage patterns and integration points.

##### README for additional insights
- The actix README describes:
- the actor lifecycle (create, start, stop),
- message dispatch and handler resolution,
- integration points (Tokio, futures),
- high-level design goals (performance, scalability).
- actix-derive README explains the proc-macro expansion hooks.
- actix-broker README outlines the pub/sub API.

a. Main components
1. Actix Core Runtime
- System Arbiter / Thread Pool
- Actor instances & Context
- Mailbox & Envelope
- Registry (actor lookup by name/address)
- Integration with Tokio reactor/futures
2. Derive Macros
- Compile-time macros that generate handler glue code
- Message trait implementations
3. Pub/Sub Broker
- Broker actor (internal registry of subscribers)
- Publisher API
- Subscriber API
4. External Adapters (e.g., actix-web, custom actors)
b. Relationships & interactions
- At compile time: actix-derive → injects code into actor/message definitions that target the Actix Core Runtime.
- At runtime: User code spins up a System Arbiter → spawns Actors → each has a Context that holds a Mailbox.
- Messages flow: Sender → Envelope → Mailbox → Actor’s Handler → optional MessageResponse → back to sender.
- Broker: acts as an Actor registered in the Registry → publishers send “Publish(topic, payload)” → broker fans out to subscriber mailboxes.
- Derive macros eliminate manual impl of Message/Handler; they generate code that hooks into the Actor dispatch loop.
c. Architectural patterns & design principles
- Actor Model: isolation, message passing, supervision.
- Dependency inversion: core runtime unaware of user-defined actors.
- Code generation (compile-time) to reduce boilerplate.
- Modular crate layout: core runtime, macros, and optional broker.
d. Key technologies & libraries
- Rust async/futures & Tokio under the hood for scheduling.
- syn/quote in actix-derive for proc-macros.
- Standard Rust channels or internal queues for mailboxes.

##### Detail
- Essential elements without over-fragmenting: group low-level futures integration under “async runtime” rather than every internal future combinator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compile-Time Subgraph
    subgraph "Compile-Time"
        direction TB
        Derive["actix-derive (proc-macros)"]:::compile
        LibDerive["lib.rs"]:::compile
        MessageDerive["message.rs"]:::compile
        MessageResp["message_response.rs"]:::compile
    end

    %% Runtime Subgraph
    subgraph "Runtime"
        direction TB

        %% Actix Core Runtime
        subgraph "Actix Core Runtime"
            direction TB
            CoreLib["lib.rs"]:::core
            ActorMod["actor.rs"]:::core
            Context1["context.rs"]:::core
            Context2["context_impl.rs"]:::core
            Mailbox["mailbox.rs"]:::core
            Envelope["address/envelope.rs"]:::core
            Registry["registry.rs"]:::core
            subgraph "Async Runtime"
                direction TB
                FutDir["fut/"]:::core
                FutFuture["fut/future/"]:::core
                FutStream["fut/stream/"]:::core
            end
            Supervisor1["supervisor.rs"]:::core
            Utils["utils.rs"]:::core
        end

        %% Pub/Sub Broker
        subgraph "actix-broker"
            direction TB
            BrokerLib["lib.rs"]:::core
            BrokerActor["broker.rs"]:::core
            Msgs["msgs.rs"]:::core
            Subscribe["subscribe.rs"]:::core
        end

        UserActors["User Actors\n(External Adapters)"]:::external
    end

    %% Relationships
    Derive -->|"codegen"| CoreLib
    Derive --> CoreLib
    CoreLib --> Supervisor1
    Supervisor1 --> ActorMod
    UserActors -->|"send()/.send()"| Envelope
    Envelope -->|"enqueue"| Mailbox
    Mailbox -->|"handle()"| ActorMod
    ActorMod -->|"MessageResponse"| UserActors

    UserActors -->|"publish()"| Msgs
    Msgs --> BrokerActor
    BrokerActor -->|"deliver"| UserActors
    UserActors -->|"subscribe()"| Subscribe
    Subscribe --> BrokerActor

    %% Click Events
    click LibDerive "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-derive/src/lib.rs"
    click MessageDerive "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-derive/src/message.rs"
    click MessageResp "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-derive/src/message_response.rs"
    click CoreLib "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/lib.rs"
    click ActorMod "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/actor.rs"
    click Context1 "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/context.rs"
    click Context2 "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/context_impl.rs"
    click Mailbox "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/mailbox.rs"
    click Envelope "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/address/envelope.rs"
    click Registry "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/registry.rs"
    click FutDir "https://github.com/mariomatheuspombal/actix-glpc/tree/master/actix/src/fut/"
    click FutFuture "https://github.com/mariomatheuspombal/actix-glpc/tree/master/actix/src/fut/future/"
    click FutStream "https://github.com/mariomatheuspombal/actix-glpc/tree/master/actix/src/fut/stream/"
    click Supervisor1 "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/supervisor.rs"
    click Utils "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix/src/utils.rs"
    click BrokerLib "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-broker/src/lib.rs"
    click BrokerActor "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-broker/src/broker.rs"
    click Msgs "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-broker/src/msgs.rs"
    click Subscribe "https://github.com/mariomatheuspombal/actix-glpc/blob/master/actix-broker/src/subscribe.rs"

    %% Styles
    classDef compile fill:#e0f7e0,stroke:#2d8;
    classDef core fill:#e0f0ff,stroke:#22a;
    classDef external fill:#f0f0f0,stroke:#999;
```
