# meamidos/gopactor architecture

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

- Interactive diagram: https://gitdiagram.com/meamidos/gopactor
- Repository: https://github.com/meamidos/gopactor

## Overview

##### Project Type and Purpose
- Type: A Go testing library for actor systems
- Purpose:
– Provide assertion functions (e.g., ShouldReceive, ShouldSendTo) for actors built with ProtoActor
– Intercept inbound, outbound & system messages

##### File Structure
Top-level packages:
- assertions/…        — assertion helper functions
- catcher/…           — core interception logic, middleware & context wrappers
- gopactor/…          — high-level API: SpawnFromInstance, SpawnNullActor, singleton management
- options/…           — configuration options and builder methods
- root files (options.go, should.go, spawn_test.go, etc.) tie packages together and define public API

##### README for Additional Insights
- Integrates with ProtoActor (github.com/AsynkronIT/protoactor-go)
- Uses Goconvey for BDD-style test syntax
- Provides adapters for intercepting actor messages and system events

##### Main Components
a. Test Harness (User’s BDD Test Code)
- Uses Goconvey’s Convey/So functions
- Calls Gopactor API (SpawnFromInstance, SpawnNullActor)
b. Gopactor Library
- High-Level API (package “gopactor”)
- Assertion Layer (package “assertions” + should.go)
- Interception Engine (package “catcher”)
- Middleware chain intercepting actor context
- Context wrapper capturing inbound/outbound messages
- Configuration (package “options”)
c. ProtoActor Runtime
- Actor spawning, mailbox, message dispatching
- System messages (Stop, Restart)
d. Mock/Null Actors
- SpawnNullActor creates no-op actors to replace real children
e. External Test Runner & Libraries
- Go test runner (go test)
- Goconvey for assertion rendering

##### Relationships and Data Flow
1. Test Harness → Gopactor API
2. Gopactor API uses Options to configure interceptors → Instructs Catcher
3. SpawnFromInstance wraps the real actor’s Context in Catcher middleware
4. Messages from Requestor actor → Sent via ProtoActor → Arrive at Catcher Context
5. Catcher Context captures “inbound” → forwards to real actor
6. Actor .Receive executes → calls ctx.Respond or ctx.Send
7. Catcher Context captures “outbound” → records for assertions → forwards to real ProtoActor mailbox
8. Assertions (ShouldReceive, ShouldSendTo, etc.) query the interceptor’s recorded events

##### Architectural Patterns & Design Principles
- Decorator/Middleware
– Catcher wraps ProtoActor Context to intercept calls
- Singleton / Global Registry
– gopactor singleton for managing active interceptors
- Fluent Builder
– Options.WithX methods for configuration chaining
- Dependency Inversion
– Test code works against Gopactor interfaces, not directly on ProtoActor

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Test Runner & Libraries
    GoTestRunner["Go Test Runner"]:::external
    Goconvey["Goconvey"]:::external

    %% Test Harness
    TestHarness["Test Harness"]:::test
    GoTestRunner -->|"runs tests"| TestHarness
    Goconvey -->|"BDD-style syntax"| TestHarness

    %% Gopactor Library Layers
    subgraph "Gopactor Library"
        direction TB
        GopactorAPI["Gopactor API"]:::internal
        Options["Configuration (Options)"]:::internal
        Catcher["Catcher Engine"]:::internal
        AssertionLayer["Assertion Layer"]:::internal
        NullActor["Null Actor"]:::internal
    end

    %% External Runtime
    ProtoActor["ProtoActor Runtime"]:::external
    RealActor["Real Actor"]:::external

    %% Relationships and Data Flow
    TestHarness -->|"calls API"| GopactorAPI
    TestHarness -->|"uses assertions"| AssertionLayer
    GopactorAPI -->|"uses options"| Options
    GopactorAPI -->|"SpawnFromInstance / SpawnNullActor"| Catcher
    GopactorAPI -->|"SpawnNullActor path"| NullActor
    Options -->|"configures middleware"| Catcher
    Catcher -->|"wraps context for"| RealActor
    RealActor -->|"messages/events"| Catcher
    Catcher -->|"forwards message"| ProtoActor
    AssertionLayer -->|"queries recorded events"| Catcher

    %% Click Events for Test Harness
    click TestHarness "https://github.com/meamidos/gopactor/blob/master/spawn_test.go"
    click TestHarness "https://github.com/meamidos/gopactor/blob/master/should_test.go"
    click TestHarness "https://github.com/meamidos/gopactor/blob/master/catcher/catcher_test.go"
    click TestHarness "https://github.com/meamidos/gopactor/blob/master/options/options_test.go"

    %% Click Events for Gopactor API
    click GopactorAPI "https://github.com/meamidos/gopactor/blob/master/gopactor/gopactor.go"
    click GopactorAPI "https://github.com/meamidos/gopactor/blob/master/gopactor/assertions.go"
    click GopactorAPI "https://github.com/meamidos/gopactor/blob/master/gopactor/singleton.go"
    click GopactorAPI "https://github.com/meamidos/gopactor/blob/master/gopactor/spawn.go"

    %% Click Events for Assertion Layer
    click AssertionLayer "https://github.com/meamidos/gopactor/blob/master/assertions/should.go"
    click AssertionLayer "https://github.com/meamidos/gopactor/blob/master/should.go"

    %% Click Events for Catcher Engine
    click Catcher "https://github.com/meamidos/gopactor/blob/master/catcher/catcher.go"
    click Catcher "https://github.com/meamidos/gopactor/blob/master/catcher/context.go"
    click Catcher "https://github.com/meamidos/gopactor/blob/master/catcher/middleware.go"
    click Catcher "https://github.com/meamidos/gopactor/blob/master/catcher/assertions.go"

    %% Click Events for Options
    click Options "https://github.com/meamidos/gopactor/blob/master/options/options.go"
    click Options "https://github.com/meamidos/gopactor/blob/master/options.go"

    %% Styles
    classDef test fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef internal fill:#d4edda,stroke:#28a745,color:#155724
    classDef external fill:#ffe5b4,stroke:#fd7e14,color:#6f42c1
```
