# kandoo/beehive architecture

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

- Interactive diagram: https://gitdiagram.com/kandoo/beehive
- Repository: https://github.com/kandoo/beehive

## Overview

##### Project type and purpose
- Beehive is a Go-based distributed programming framework.
- It provides primitives for asynchronous message passing, sharding/partitioning (Map), replicated state (dictionaries), fault-tolerance (Raft), transactions, HTTP and detached handlers, and live instrumentation.

##### File structure
- Top-level Go entrypoints:
- app.go, hive.go, web.go – core server and HTTP API
- registry.go, replication.go, rpc.go – cluster membership, replication logic, RPC interface
- raft/ – in-process Raft implementation for consensus and replication
- compiler/ – codegen of Map functions
- composition/, bucket/, state/ – utility packages for message composition, in-memory state, transaction support
- examples/ – sample apps illustrating HelloWorld, KV store, task queue, routing, detached handlers
- Godeps/ – vendored dependencies (gorilla/mux, protobuf, etc.)
- Tests scattered alongside each package confirm functionality.

##### Extract architectural insights from the README
- Hives = cluster nodes hosting Bees (worker goroutines).
- Applications = sets of message handlers. Each handler has a Map (for sharding) and Rcv (business logic).
- Bees own “cells” (dictionary keys) and execute Rcv under a transaction.
- Cell ownership and replication use Raft: each cell is replicated to a colony of Bees (size = replication factor).
- Messages flow: Emit → Map → route to owning Bee (local or remote) → Rcv → state updates & new messages.
- Extensions: HTTP handlers mounted at /apps/APP_NAME/, Detached handlers for external I/O, instrumentation for live optimization.

##### Detail
- Break the core engine into: Dispatcher, Transaction Manager, Bee Pool, Dictionary Store, Raft subsystem
- How multiple applications register handlers with the Dispatcher
- Clustered Hives and peer discovery via the registry module
- Call out configuration and command-line flags that control ports, replication factor, instrumentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    ClientAPI["HTTP Client / CLI"]:::client
    DetachedHandler["Detached Handlers"]:::client

    %% Hive Server
    subgraph "Hive Server"
        HTTPServer["HTTP Server<br/>(web.go, http.go)"]:::server
        RPCInterface["RPC Interface<br/>(rpc.go)"]:::server
        Dispatcher["Dispatcher<br/>(app.go, hive.go)"]:::server
        Registry["Cluster Registry<br/>(registry.go)"]:::server
        Replication["Replication Logic<br/>(replication.go)"]:::server
        Config["CLI Flags / Config<br/>(cmd.go, cmds.go)"]:::server
        Stats["Instrumentation<br/>(stats.go)"]:::server
    end

    %% Bee Pool
    subgraph "Bee Pool"
        BeeWorker["Bee Worker<br/>(bee.go)"]:::worker
        Colony["Colony Manager<br/>(colony.go)"]:::worker
        SyncAPI["Sync / Emit API<br/>(sync.go)"]:::worker
    end

    %% State Store
    subgraph "State Store"
        Transaction["Transaction Support<br/>(state/tx.go)"]:::db
        Inmem["In-Memory State<br/>(state/inmem.go)"]:::db
        Dict["Dictionary Store<br/>(state/dict.go)"]:::db
    end

    %% Raft Consensus
    subgraph "Raft Subsystem"
        RaftNode["Raft Node<br/>(raft/node.go)"]:::consensus
        RaftStorage["Raft Storage<br/>(raft/storage.go)"]:::consensus
        RaftEncoder["Raft Encoder<br/>(raft/encoder.go)"]:::consensus
    end

    %% Extensions
    subgraph "Extensions"
        Compiler["Map Codegen<br/>(compiler/)"]:::ext
        Composition["Message Composition<br/>(composition/)"]:::ext
        Sharding["Sharding Primitives<br/>(bucket/)"]:::ext
        MsgSerial["Serialization<br/>(msg.go, gob/, js.go)"]:::ext
        DetachedTest["Detached Handlers Tests<br/>(detached_test.go)"]:::ext
        Examples["Example Apps<br/>(examples/)"]:::ext
    end

    %% Data Flow
    ClientAPI -->|HTTP/RPC| HTTPServer
    ClientAPI -->|HTTP/RPC| RPCInterface
    DetachedHandler -->|Emit/Sync| SyncAPI

    HTTPServer -->|requests| Dispatcher
    RPCInterface -->|messages| Dispatcher
    Config -->|configures| Dispatcher
    Stats -->|reports| Dispatcher
    Registry -->|membership| Dispatcher

    Dispatcher -->|dispatch| BeeWorker
    SyncAPI -->|sync calls| Dispatcher

    BeeWorker -->|transaction| Transaction
    Transaction -->|uses| Inmem
    Transaction -->|persists| Dict
    BeeWorker -->|replicate| Replication
    Replication -->|log| RaftNode
    RaftNode -->|store| RaftStorage
    RaftNode -->|encode| RaftEncoder
    BeeWorker -->|emit| SyncAPI

    %% Extensions Integration
    Compiler -->|generates Map| Dispatcher
    Composition -->|formats msgs| Dispatcher
    Sharding -->|partitions| Dispatcher
    MsgSerial -->|serializes| RPCInterface

    %% Examples and Tests
    DetachedTest -.->|validates| DetachedHandler
    Examples -.->|demonstrate| Dispatcher

    %% Click Events
    click Dispatcher "https://github.com/kandoo/beehive/blob/master/app.go"
    click HTTPServer "https://github.com/kandoo/beehive/blob/master/web.go"
    click RPCInterface "https://github.com/kandoo/beehive/blob/master/rpc.go"
    click Registry "https://github.com/kandoo/beehive/blob/master/registry.go"
    click Replication "https://github.com/kandoo/beehive/blob/master/replication.go"
    click Config "https://github.com/kandoo/beehive/blob/master/cmd.go"
    click Stats "https://github.com/kandoo/beehive/blob/master/stats.go"
    click BeeWorker "https://github.com/kandoo/beehive/blob/master/bee.go"
    click Colony "https://github.com/kandoo/beehive/blob/master/colony.go"
    click SyncAPI "https://github.com/kandoo/beehive/blob/master/sync.go"
    click Dict "https://github.com/kandoo/beehive/blob/master/state/dict.go"
    click Inmem "https://github.com/kandoo/beehive/blob/master/state/inmem.go"
    click Transaction "https://github.com/kandoo/beehive/blob/master/state/tx.go"
    click RaftNode "https://github.com/kandoo/beehive/blob/master/raft/node.go"
    click RaftStorage "https://github.com/kandoo/beehive/blob/master/raft/storage.go"
    click RaftEncoder "https://github.com/kandoo/beehive/blob/master/raft/encoder.go"
    click Compiler "https://github.com/kandoo/beehive/tree/master/compiler/"
    click Composition "https://github.com/kandoo/beehive/tree/master/composition/"
    click Sharding "https://github.com/kandoo/beehive/blob/master/bucket/bucket.go"
    click MsgSerial "https://github.com/kandoo/beehive/blob/master/msg.go"
    click DetachedTest "https://github.com/kandoo/beehive/blob/master/detached_test.go"
    click Examples "https://github.com/kandoo/beehive/tree/master/examples/"

    %% Styles
    classDef client fill:#ffebcc,stroke:#cc6600;
    classDef server fill:#cce5ff,stroke:#005cbf;
    classDef worker fill:#d4edda,stroke:#155724;
    classDef db fill:#f8d7da,stroke:#721c24;
    classDef consensus fill:#fff3cd,stroke:#856404;
    classDef ext fill:#e2e3e5,stroke:#6c757d;
```
