# eigr/spawn architecture

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

- Interactive diagram: https://gitdiagram.com/eigr/spawn
- Repository: https://github.com/eigr/spawn

## Overview

##### Main Components
- Actor Runtime Core – Representing the core business logic around actors: state managers, registries, lifecycle supervisors, and invocation schedulers (look inside the “lib/actors” directory).
- Activators – These “spawner” components are responsible for interfacing with external messaging systems. Include separate nodes for activators such as activator_kafka, activator_rabbitmq, activator_pubsub, activator_sqs, and activator_simple. They represent the entry points and bridge the actor runtime with external protocols.
- Operator and Infrastructure Components – The spawn_operator module contains controllers and Kubernetes integration. This component helps manage deployment aspects using CRDs (custom resource definitions) and handles the lifecycle of actor systems on Kubernetes.
- SDK and API Layers – The spawn_sdk and spawnctl folders indicate there is an SDK for interacting with the actor mesh and a command-line tool (ctl) for deployment and orchestration.
- Sidecar and Proxy – There are “sidecar” components and a dedicated spawn_proxy which support cross-cutting concerns such as encapsulating gRPC interfaces, connection handling, and protocol parsing.
- Monitoring/Observability – With a spawn_monitor component and observability configuration (otel files), there is built-in support for metrics, logging, and tracing.
- State Stores and Persistence – The spawn_statestores repositories suggest dedicated components for state management and persistent storage, including adapters for Postgres, MariaDB, and native implementations.

##### Relationships and Data Flow
- How the client applications (or external services via the SDK/API) send requests that flow through the gateway/activators.
- From the activators, show the communication to the core actor system (actors, supervisors, and registries).
- Interactions with external state stores (via the statestore components) and monitoring systems (via observability configurations).
- Communication between the sidecar processes and the main application for handling graceful shutdowns, routing, and service discovery.

##### Architectural Patterns and Design Principles
- Modularity: Divide the system into discrete, well-labeled modules (e.g., “Actor Core”, “Activators”, “Operator”, “SDK/API”, “State Stores”, “Sidecar/Proxy”, “Monitor”).
- Actor Model: Emphasize how stateful actors communicate, get supervised, and manage lifecycle events.
- Microservices/Multi-Component: Represent the different activators and operators as independent services that plug into the overall mesh.

##### Relevant Technologies & Frameworks
- Elixir/Erlang: Foundation of the actor implementation (libraries in “lib/actors”, supervisor patterns, etc.).
- Kubernetes: Through the spawn_operator and k8s configurations, show how the system scales and manages its components.
- gRPC, HTTP, and Protocol Buffers: These are evident in the presence of “grpc” folders and “.proto” definitions.
- Docker/Containerization: Several Dockerfiles exist for various components indicating container-based deployments.
- Multi-language SDKs: Represent SDK support for Dart, Go, Java, Node, Python, Rust as indicated in the “docs/sdks” folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Interface"
        ExternalClients["External Clients"]:::external
        SDKLayer["SDK Layer"]:::sdk
        SpawnCTL["CLI/API Tool"]:::sdk
    end

    subgraph "Activators"
        ActivatorAPI["Activator-API"]:::activator
        ActivatorKafka["Activator-Kafka"]:::activator
        ActivatorRabbitMQ["Activator-RabbitMQ"]:::activator
        ActivatorPubSub["Activator-PubSub"]:::activator
        ActivatorSQS["Activator-SQS"]:::activator
        ActivatorSimple["Activator-Simple"]:::activator
    end

    subgraph "Runtime Core"
        ActorCore["Actor Runtime Core"]:::core
        Sidecar["Sidecar"]:::core
        ProxyService["Proxy Service"]:::core
    end

    subgraph "Management & Monitoring"
        KubernetesOperator["Kubernetes Operator"]:::management
        SpawnMonitor["Monitoring/Observability"]:::management
        StateStores["State Stores"]:::management
    end

    %% Data Flow Connections
    ExternalClients -->|"sendsRequests"| SDKLayer
    SDKLayer -->|"APIcall"| ActivatorAPI
    SpawnCTL -->|"deployCommands"| KubernetesOperator

    ActivatorAPI -->|"activates"| ActorCore
    ActivatorKafka -->|"activates"| ActorCore
    ActivatorRabbitMQ -->|"activates"| ActorCore
    ActivatorPubSub -->|"activates"| ActorCore
    ActivatorSQS -->|"activates"| ActorCore
    ActivatorSimple -->|"activates"| ActorCore

    ActorCore -->|"integrates"| Sidecar
    Sidecar -->|"routesTo"| ProxyService
    ActorCore -->|"exposesVia"| ProxyService

    KubernetesOperator -->|"orchestrates"| ActorCore
    KubernetesOperator -->|"manages"| ActivatorAPI
    KubernetesOperator -->|"configures"| ProxyService
    KubernetesOperator -->|"monitors"| Sidecar

    ActorCore -->|"logsMetrics"| SpawnMonitor
    ActorCore -->|"persistsState"| StateStores

    %% Click Events
    click ActorCore "https://github.com/eigr/spawn/tree/main/lib/actors"
    click ActivatorAPI "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_api"
    click ActivatorKafka "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_kafka"
    click ActivatorRabbitMQ "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_rabbitmq"
    click ActivatorPubSub "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_pubsub"
    click ActivatorSQS "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_sqs"
    click ActivatorSimple "https://github.com/eigr/spawn/tree/main/spawn_activators/activator_simple"
    click KubernetesOperator "https://github.com/eigr/spawn/tree/main/spawn_operator/spawn_operator"
    click SDKLayer "https://github.com/eigr/spawn/tree/main/spawn_sdk/spawn_sdk"
    click SpawnCTL "https://github.com/eigr/spawn/tree/main/spawnctl"
    click Sidecar "https://github.com/eigr/spawn/tree/main/lib/sidecar"
    click ProxyService "https://github.com/eigr/spawn/tree/main/spawn_proxy/proxy"
    click SpawnMonitor "https://github.com/eigr/spawn/tree/main/spawn_monitor"
    click StateStores "https://github.com/eigr/spawn/tree/main/spawn_statestores"

    %% Styling
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef sdk fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef activator fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef management fill:#FFA07A,stroke:#333,stroke-width:2px;
```
