# anthdm/hollywood architecture

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

- Interactive diagram: https://gitdiagram.com/anthdm/hollywood
- Repository: https://github.com/anthdm/hollywood

## Overview

##### Main Components
- Engine & Core Actor System – This is the heart of Hollywood and is encapsulated in the “actor” package. It is responsible for creating, managing, and supervising actors (the independent units that process messages).
- Actor Instances – Each actor is represented by components like “actor/engine.go,” “actor/pid.go,” and “actor/context.go” that exhibit the typical actor lifecycle (Initialized, Started, Stopped, etc.).
- Messaging & Event Stream – The system uses an event stream to support message routing, including handling special system events (like DeadLetterEvent or ActorRestartedEvent). This is highlighted in both the README and in components such as “actor/event.go” and “cluster/event.go.”
- Clustering & Distributed Communication – The “cluster” directory shows the support for actor clustering with files like “cluster/cluster.go” and “cluster/member_set.go.” This design provides logical separation for distributed system capabilities.
- Remote Communication – The “remote” directory demonstrates how actors communicate over the network. It involves remote configuration, TLS support, and protobuf-based message serialization (see files like “remote/remote.go” and “remote/remote.proto”).
- Supporting Utilities – Additional packages like “ringbuffer” and “safemap” are used to optimize message queues and provide thread-safe structures.
- Examples and Benchmarks – A variety of example applications (located under “examples”) illustrate scenarios such as chat applications, trade engines, and event monitoring. Benchmarks (in _bench) help validate performance claims.

##### Relationships and Data Flow
- Individual actors (receivers) as nodes that exchange messages via defined channels or inboxes. Emphasize that actors are uniquely identified by PIDs.
- Lifecycle message flows (e.g., from the engine to an actor for initialization, start, and stop events).
- A message routing component (via the event stream) that ensures that messages are delivered correctly and dead letters (undelivered messages) are captured.
- Demonstrate external communication between local and remote systems – show how messages can be sent over the network using dRPC and protobuf serialization. If TLS is enabled (as configured in the README for remote actors), include that in the connection details.

##### Architectural Patterns and Design Principles
- Actor Model – Focus on the message-passing, isolated state, and non-blocking, concurrent design of actors.
- Decentralized Communication – Emphasize local and remote message dispatch, showcasing the lightweight and fault-tolerant nature.
- Supervision/Crash Recovery – Indicate how actors are monitored and restarted upon failure, as shown by configurable options (e.g., WithMaxRestarts).
- Event-driven System – The use of event streams and logging via the built-in logger becomes a vital part of the overall design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main System Components
    A["Actor Engine"]:::engineCore
    subgraph B["Actors"]
        B1["Actor PID"]:::actor
        B2["Actor Context"]:::actor
    end
    subgraph C["Messaging & Event Stream"]
        C1["Event"]:::messaging
        C2["Event Stream"]:::messaging
    end
    subgraph D["Clustering & Distributed Communication"]
        D1["Cluster Manager"]:::clustering
        D2["Member Set"]:::clustering
    end
    subgraph E["Remote Communication"]
        E1["Remote Gateway"]:::remote
        E2["Remote Proto"]:::remote
    end
    subgraph F["Supporting Utilities"]
        F1["Ringbuffer"]:::utilities
        F2["SafeMap"]:::utilities
    end
    subgraph G["Examples and Benchmarks"]
        G1["Examples"]:::examples
        G2["Benchmarks"]:::examples
    end

    %% Relationships and Data Flows
    A -->|"spawns"| B1
    A -->|"spawns"| B2
    A -->|"sends"| C1
    B1 -->|"communicates"| C2
    B2 -->|"communicates"| C2
    C1 -->|"routes"| C2
    C2 -->|"triggers"| D1
    D1 -->|"manages"| D2
    D1 -->|"coordinates"| E1
    A -->|"dispatches"| E1
    %% Supporting Utilities act as underlying support for Actor Engine
    F1 --- A
    F2 --- A
    %% External Consumer Example
    G1 -->|"uses"| A
    G2 -->|"benchmarks"| A

    %% Legend Subgraph (for clarity)
    subgraph Legend["Legend"]
        L1["Actor Engine (Core)"]:::engineCore
        L2["Actors"]:::actor
        L3["Messaging & Event Stream"]:::messaging
        L4["Clustering"]:::clustering
        L5["Remote Communication"]:::remote
        L6["Utilities"]:::utilities
        L7["Examples/Benchmarks"]:::examples
    end

    %% Click Events
    click A "https://github.com/anthdm/hollywood/blob/master/actor/engine.go"
    click B1 "https://github.com/anthdm/hollywood/blob/master/actor/pid.go"
    click B2 "https://github.com/anthdm/hollywood/blob/master/actor/context.go"
    click C1 "https://github.com/anthdm/hollywood/blob/master/actor/event.go"
    click C2 "https://github.com/anthdm/hollywood/blob/master/actor/event_stream.go"
    click D1 "https://github.com/anthdm/hollywood/blob/master/cluster/cluster.go"
    click D2 "https://github.com/anthdm/hollywood/blob/master/cluster/member_set.go"
    click E1 "https://github.com/anthdm/hollywood/blob/master/remote/remote.go"
    click E2 "https://github.com/anthdm/hollywood/blob/master/remote/remote.proto"
    click F1 "https://github.com/anthdm/hollywood/tree/master/ringbuffer/"
    click F2 "https://github.com/anthdm/hollywood/tree/master/safemap/"
    click G1 "https://github.com/anthdm/hollywood/tree/master/examples/"
    click G2 "https://github.com/anthdm/hollywood/tree/master/_bench/"

    %% Styles for Nodes
    classDef engineCore fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef actor fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef messaging fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef clustering fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef remote fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef utilities fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef examples fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
```
