# ergo-services/ergo architecture

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

- Interactive diagram: https://gitdiagram.com/ergo-services/ergo
- Repository: https://github.com/ergo-services/ergo

## Overview

##### Project type and purpose
- This is a Go-based framework (library) implementing the Erlang-style actor model, network transparency, and supervision trees.
- Purpose: provide a highly concurrent, distributed, fault-tolerant runtime with ready-to-use components (actors, supervisors, network stack, meta-processes) and tooling (code generator, observer).

##### File structure
- Top-level modules:
- act/: core actor runtime (Actor, Pool, Supervisor strategies, WebWorker)
- node/: high-level Node orchestration (application registry, logging, networking integration)
- net/: pluggable network stack (EDF codec, handshake, protocol, registrar)
- meta/: meta-process actors for built-in services (HTTP, TCP, UDP servers, port processes)
- gen/: code-generation interfaces (Node, Application, Process, Cron, Logger, Mailbox)
- app/: example “system” application (observer backend)
- lib/: utility sub-packages (buffers, maps, OS-deps, tracing)
- testing/: unit and integration test harness and staged distributed tests
- Key config & entry points:
- ergo.go / debug.go / version.go
- go.mod / go.sum

##### Insights from the README
- Core features: Actor Model, Network Transparency, Observability, Supervision, Cron scheduler, Port meta-process.
- Extension points: custom loggers, cert manager, network stack interfaces.
- Tools: “ergo” CLI for code generation; “observer” for runtime inspection.

##### Components
a. Main components:
1. Core Actor Runtime (act/)
2. Node Manager (node/)
3. Supervisor Tree & Actors (act/supervisor + app logic)
4. Messaging Subsystem (mailbox, message passing, gen/mailbox.go)
5. Network Stack (net/edf, net/handshake, net/proto, net/registrar)
6. Meta-Processes (meta/web_server, meta/tcp_server, meta/udp_server, meta/port)
7. Utilities & Codegen (gen/, lib/)
8. Observer Application (app/system)
9. CLI Tools (ergo, observer)
10. Testing Framework (testing/)

b. Relationships & interactions:
- Node Manager instantiates Applications via gen.Node interfaces.
- Applications define Supervisor trees; Supervisors spawn and monitor Actors.
- Actors communicate via asynchronous message passing into Mailboxes.
- Node Manager registers with Registrar (net/registrar) for service discovery.
- Network Stack uses EDF codec to serialize messages over TCP/UDP transports.
- Handshake module negotiates connections between nodes.
- Meta-Processes run as Actors to provide HTTP/TCP/UDP server functionality or manage external OS processes.
- Observer Application runs over meta/web_server to expose runtime state.
- CLI Tools (ergo) use gen/ to scaffold new Node/App/Actor code.
- Testing harness uses mock nodes, in-memory network, and event capture (testing/unit).

c. Architectural patterns & principles:
- Actor Model for isolation and concurrency
- Supervision Tree for fault tolerance
- Modular networking (pluggable codecs, handshake, registrar)
- Meta-process pattern for embedding services as Actors
- Code Generation for consistency and boilerplate reduction
- Layered design: Core → Node → App → Meta → External

d. Key technologies & libraries:
- Go 1.20+
- act, node, net, meta, gen, lib internal packages
- External CLI tools: ergo.tools/ergo, ergo.tools/observer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Runtime Layer
    subgraph "Core Actor Runtime" 
        direction TB
        CoreRuntime["act/"]:::core
        Actor((Actor)):::core
        Supervisor{{"Supervisor\n(OFO, SOFO, ARFO)"}}:::core
        Mailbox[(Mailbox)]:::core
    end

    %% Node Manager Layer
    subgraph "Node Manager" 
        direction TB
        NodeManager["node/"]:::node
        Registrar[(Registrar)]:::network
    end

    %% Messaging Subsystem
    subgraph "Messaging Subsystem" 
        direction TB
        MailboxCode["gen/mailbox.go"]:::core
        MessageCode["gen/message.go"]:::core
    end

    %% Network Stack Layer
    subgraph "Network Stack" 
        direction TB
        EDFCodec["net/edf/"]:::network
        Handshake["net/handshake/"]:::network
        Protocol["net/proto/"]:::network
        RegistrarService["net/registrar/"]:::network
    end

    %% Meta-Processes Layer
    subgraph "Meta-Processes (Built-in Services)" 
        direction TB
        HTTPServer["meta/web_server.go"]:::meta
        TCPServer["meta/tcp_server.go"]:::meta
        UDPServer["meta/udp_server.go"]:::meta
        PortProcess["meta/port.go"]:::meta
    end

    %% Utilities & Code Generation
    subgraph "Utilities & Codegen" 
        direction TB
        Codegen["gen/"]:::tooling
        Libraries["lib/"]:::tooling
    end

    %% Observer Application
    subgraph "Observer Application" 
        direction TB
        ObserverApp["app/system/"]:::meta
    end

    %% CLI Tools
    subgraph "CLI Tools" 
        direction TB
        ERGO["ergo.go"]:::tooling
        DebugCLI["debug.go"]:::tooling
    end

    %% Testing Framework
    subgraph "Testing Framework" 
        direction TB
        Testing["testing/"]:::testing
    end

    %% Relationships
    NodeManager -->|"instantiates"| CoreRuntime
    CoreRuntime -->|"spawns/monitors"| Supervisor
    Supervisor -->|"manages"| Actor
    Actor -->|"sends/receives"| Mailbox
    NodeManager -->|"registers with"| RegistrarService
    EDFCodec -->|"serializes via"| Protocol
    Protocol -->|"communicates over"| RegistrarService
    Handshake -->|"negotiates"| Protocol
    MetaProcesses["Meta-Processes"] -->|"attach to"| CoreRuntime
    HTTPServer -->|"runs on"| CoreRuntime
    ObserverApp -->|"queries via HTTP"| HTTPServer
    ERGO -->|"generates code into"| Codegen
    DebugCLI -->|"inspects runtime"| ObserverApp
    Testing -->|"uses mocks/in-memory network"| CoreRuntime

    %% Click Events
    click CoreRuntime "https://github.com/ergo-services/ergo/tree/master/act/"
    click Actor "https://github.com/ergo-services/ergo/blob/master/act/actor.go"
    click Supervisor "https://github.com/ergo-services/ergo/blob/master/act/supervisor.go"
    click MailboxCode "https://github.com/ergo-services/ergo/blob/master/gen/mailbox.go"
    click MessageCode "https://github.com/ergo-services/ergo/blob/master/gen/message.go"
    click EDFCodec "https://github.com/ergo-services/ergo/tree/master/net/edf/"
    click Handshake "https://github.com/ergo-services/ergo/tree/master/net/handshake/"
    click Protocol "https://github.com/ergo-services/ergo/tree/master/net/proto/"
    click RegistrarService "https://github.com/ergo-services/ergo/tree/master/net/registrar/"
    click HTTPServer "https://github.com/ergo-services/ergo/blob/master/meta/web_server.go"
    click TCPServer "https://github.com/ergo-services/ergo/blob/master/meta/tcp_server.go"
    click UDPServer "https://github.com/ergo-services/ergo/blob/master/meta/udp_server.go"
    click PortProcess "https://github.com/ergo-services/ergo/blob/master/meta/port.go"
    click Codegen "https://github.com/ergo-services/ergo/tree/master/gen/"
    click Libraries "https://github.com/ergo-services/ergo/tree/master/lib/"
    click ObserverApp "https://github.com/ergo-services/ergo/tree/master/app/system/"
    click ERGO "https://github.com/ergo-services/ergo/blob/master/ergo.go"
    click DebugCLI "https://github.com/ergo-services/ergo/blob/master/debug.go"
    click Testing "https://github.com/ergo-services/ergo/tree/master/testing/"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72
    classDef network fill:#D5F5E3,stroke:#1D8348
    classDef meta fill:#FCF3CF,stroke:#F1C40F
    classDef tooling fill:#E8DAEF,stroke:#6C3483
    classDef testing fill:#F2F3F4,stroke:#626567
    classDef node fill:#FADBD8,stroke:#C0392B
```
