# rivet-gg/actor-core architecture

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

- Interactive diagram: https://gitdiagram.com/rivet-gg/actor-core
- Repository: https://github.com/rivet-gg/actor-core

## Overview

##### Project Type and Purpose

**Project Type:**
ActorCore is a **Stateful, Scalable, Realtime Backend Framework** designed for building multiplayer, realtime, or AI agent backends.

**Purpose:**
- **State Management:** Provides persistent, in-memory state with built-in durability.
- **Realtime Capabilities:** Enables ultra-fast state updates with low latency.
- **Serverless & Scalable:** Supports effortless scaling and deployment on various serverless platforms.
- **Integrated Features:** Includes RPC, events, scheduling, connections, and metadata management without additional boilerplate.

**Key Indicators in README:**
- Descriptions of features like state, RPC, events, scheduling.
- Supported platforms: Rivet, Cloudflare Workers, Bun, Node.js.
- Integrations with Hono and Redis.

##### File Structure

**Top-Level Directories and Their Roles:**
- **`packages/`**: Contains all modular components of the framework.
- **`actor-core/`**: The main core framework handling state, RPC, events, etc.
- **`actor-core-cli/`**: Command-line interface tool for interacting with ActorCore.
- **`drivers/`**: Implements various drivers like `memory` and `redis` for state management.
- **`platforms/`**: Contains integrations for different deployment environments (Rivet, Cloudflare Workers, Bun, Node.js, Rivet).
- **`create-actor/`**: Utility for generating new actors.
- **`misc/`**: Miscellaneous tools and middleware.
- **`examples/`**: Demonstrative applications (e.g., `chat-simple`, `counter`) showcasing ActorCore’s capabilities.
- **`docs/`**: Documentation covering concepts, drivers, integrations, and more.
- **`.github/`**: Workflow configurations and media assets for GitHub.
- **`scripts/`**: Automation scripts for tasks like publishing and testing.

**Architectural Patterns:**
- **Monorepo Structure:** Facilitates modular development with clearly separated packages.
- **Pluggable Architecture:** Drivers and platforms are interchangeable, allowing flexibility in state management and deployment.
- **Modular Components:** Each package serves a distinct purpose, promoting maintainability and scalability.

**Configuration and Deployment:**
- **Configuration Files:** `.yarnrc.yml`, `tsconfig.base.json`, `turbo.json`, etc., indicate the use of Yarn workspaces and Turbo for build optimization.
- **CI/CD Workflows:** Located under `.github/workflows/`, suggesting automated testing and deployment pipelines.

##### README for Additional Insights

**Architecture Highlights:**
- **Persistent, In-Memory State:** Eliminates the need for external databases by providing built-in durability.
- **Ultra-Fast State Updates:** Achieved through co-locating compute and data.
- **Batteries Included:** Comprehensive features without requiring additional setup.
- **Serverless & Scalable:** Designed for deployment on various serverless platforms with ease.

**Features Overview:**
- **State Management:** Efficient in-memory access with persistence.
- **RPC:** Facilitates seamless client-server communication.
- **Events:** Real-time event handling and broadcasting.
- **Scheduling:** Manages timed tasks and operations.
- **Connections & Multiplayer:** Handles connections and multiplayer interactions.
- **Metadata:** Manages additional data attributes.

**Comparative Advantages:**
- ActorCore offers a richer set of built-in features compared to alternatives like Durable Objects, Socket.io, Redis, and AWS Lambda, reducing the need for external services and boilerplate code.

**a. Identify Main Components:**
- **Core Framework:**
- **Actor Core (`actor-core/`):** Manages state, RPC, events, scheduling.
- **CLI Tools:**
- **Actor Core CLI (`actor-core-cli/`):** Interface for interacting with the framework.
- **Create Actor (`create-actor/`):** Utility for generating new actors.
- **Drivers (`drivers/`):**
- **Memory Driver (`drivers/memory/`):** In-memory state management.
- **Redis Driver (`drivers/redis/`):** Redis-based state management.
- **Platforms (`platforms/`):**
- **Rivet, Cloudflare Workers, Bun, Node.js, Rivet:** Different deployment environments.
- **Examples (`examples/`):**
- **Chat Simple, Counter:** Demonstrative applications.
- **Miscellaneous (`misc/`):**
- **Docs Middleware:** Additional documentation tools.
- **Documentation (`docs/`):** Comprehensive guides and reference materials.

**b. Determine Relationships and Interactions:**
- **Core Framework** interacts with various **Drivers** for state management.
- **CLI Tools** facilitate the creation and deployment of actors on selected **Platforms**.
- **Platforms** host the deployed applications, utilizing specific drivers as needed.
- **Examples** demonstrate how to implement features using the core framework and drivers.
- **Documentation** provides guidance on concepts, integrations, and usage.

**c. Highlight Architectural Patterns and Design Principles:**
- **Modularity:** Clear separation of concerns across packages.
- **Pluggability:** Drivers and platforms can be interchanged without affecting the core.
- **Scalability:** Designed to handle growth seamlessly through serverless deployments.
- **Reusability:** Components like drivers and platforms can be reused across different projects.

**d. Include Relevant Technologies:**
- **Programming Language:** TypeScript
- **Package Management:** Yarn
- **Build Tools:** Turbo, tsup
- **Integrations:** Hono, Redis
- **Deployment Platforms:** Rivet, Cloudflare Workers, Bun, Node.js

##### Essential Elements

- **Clear Labels:**
- Name each component accurately (e.g., Actor Core, Memory Driver, Cloudflare Workers Platform).
- Data flows, such as how the CLI interacts with the Core or how the Core communicates with Drivers and Platforms.
- Differentiate between types of components:
- **Interconnections:**
- Dependencies, such as the Core depending on Drivers or Platforms relying on specific Drivers.

##### Detail and Architectural Elements

- **Granular Separation:**
- **Highlight Scalability Features:**
- How the framework scales across different platforms and manages state efficiently.
- **Capture Integration Points:**
- Detail how ActorCore integrates with external tools like Hono and Redis.
- **Illustrate Workflow:**

##### Core Framework (actor-core)
- Manages state, RPC, events, scheduling.
##### CLI Tools
- **Actor Core CLI:** Interfaces with the core for deployment and management.
- **Create Actor:** Generates new actor instances.
##### Drivers
- **Memory Driver:** Handles in-memory state.
- **Redis Driver:** Manages Redis-based state persistence.
##### Platforms
- **Rivet, Cloudflare Workers, Bun, Node.js:** Deployment targets leveraging specific drivers.
##### Integrations
- **Hono, Redis:** External services integrated into the framework.
##### Examples
- **Chat Simple, Counter:** Sample applications demonstrating framework usage.
##### Documentation and Scripts
- Guides, workflows, and automation scripts supporting development and deployment.

**Final Tips:**
- **Iterative Refinement:** Start with a high-level overview and progressively add details.
- **Collaboration:** Engage with team members to ensure all components and interactions are captured accurately.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs and modules
    subgraph "Core Framework"
        ActorCore["Actor Core"]:::core
    end

    subgraph "CLI Tools"
        ActorCoreCLI["Actor Core CLI"]:::cli
        CreateActor["Create Actor Utility"]:::cli
    end

    subgraph "Drivers"
        MemoryDriver["Memory Driver"]:::driver
        RedisDriver["Redis Driver"]:::driver
    end

    subgraph "Platforms"
        Rivet["Rivet Platform"]:::platform
        CloudflareWorkers["Cloudflare Workers Platform"]:::platform
        Bun["Bun Platform"]:::platform
        NodeJS["Node.js Platform"]:::platform
    end

    subgraph "Examples"
        ChatSimple["Chat Simple Example"]:::example
        Counter["Counter Example"]:::example
    end

    subgraph "Documentation and Misc"
        Documentation["Documentation"]:::docs
        DocsMiddleware["Docs Middleware"]:::misc
    end

    %% Connections
    ActorCoreCLI --> ActorCore
    CreateActor --> ActorCore
    ActorCore --> MemoryDriver
    ActorCore --> RedisDriver
    ActorCore --> Rivet
    ActorCore --> CloudflareWorkers
    ActorCore --> Bun
    ActorCore --> NodeJS
    ActorCore --> ChatSimple
    ActorCore --> Counter
    Documentation --> ActorCore
    DocsMiddleware --> Documentation

    %% Click Events
    click ActorCore "https://github.com/rivet-gg/actor-core/tree/main/packages/actor-core/"
    click ActorCoreCLI "https://github.com/rivet-gg/actor-core/tree/main/packages/actor-core-cli/"
    click CreateActor "https://github.com/rivet-gg/actor-core/tree/main/packages/create-actor/"
    click MemoryDriver "https://github.com/rivet-gg/actor-core/tree/main/packages/drivers/memory/"
    click RedisDriver "https://github.com/rivet-gg/actor-core/tree/main/packages/drivers/redis/"
    click Rivet "https://github.com/rivet-gg/actor-core/tree/main/packages/platforms/rivet/"
    click CloudflareWorkers "https://github.com/rivet-gg/actor-core/tree/main/packages/platforms/cloudflare-workers/"
    click Bun "https://github.com/rivet-gg/actor-core/tree/main/packages/platforms/bun/"
    click NodeJS "https://github.com/rivet-gg/actor-core/tree/main/packages/platforms/nodejs/"
    click ChatSimple "https://github.com/rivet-gg/actor-core/tree/main/examples/chat-simple/"
    click Counter "https://github.com/rivet-gg/actor-core/tree/main/examples/counter/"
    click Documentation "https://github.com/rivet-gg/actor-core/tree/main/docs/"
    click DocsMiddleware "https://github.com/rivet-gg/actor-core/tree/main/packages/misc/docs-middleware/"

    %% Styles
    classDef core fill:#1f77b4,stroke:#000,stroke-width:1px;
    classDef cli fill:#2ca02c,stroke:#000,stroke-width:1px;
    classDef driver fill:#ff7f0e,stroke:#000,stroke-width:1px;
    classDef platform fill:#9467bd,stroke:#000,stroke-width:1px;
    classDef example fill:#ffbb78,stroke:#000,stroke-width:1px;
    classDef docs fill:#d62728,stroke:#000,stroke-width:1px;
    classDef misc fill:#c7c7c7,stroke:#000,stroke-width:1px;
```
