# fschuetz04/simgo architecture

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

- Interactive diagram: https://gitdiagram.com/fschuetz04/simgo
- Repository: https://github.com/fschuetz04/simgo

## Overview

##### Main components
a. Core Simulation Engine
- **Simulation** (simulation.go)
- **EventQueue** (eventqueue.go)
b. Process Management
- **Process** abstraction (process.go)
- **Awaitable** interface and combinators (awaitable.go, allof.go, anyof.go)
c. Event Abstraction
- **Event** (event.go)
- Timeout/Delay semantics (timeout created via `proc.Timeout(...)`)
d. Resource & Store Modules
- **Resource Manager** (resource.go)
- **Store Manager** (store.go)
e. Public API Layer
- `NewSimulation()`
- `ProcessReflect(...)`
- `RunUntil(...)`
- `Event()` and `Timeout(...)`
f. User Code / Examples (_examples/…)

##### Relationships & data flows
- **User code** calls the **API layer** to
- Instantiate `Simulation`
- Register processes (`ProcessReflect`)
- Kick off the simulation (`RunUntil`)
- The **Simulation** holds a **single EventQueue** (a min-heap of future events).
- Each registered **Process** runs in its own goroutine but is *logically* single-threaded because the engine only *triggers* one event at a time.
- A process calls `proc.Wait(...)` on an `Event` or combinator; under the hood this:
- Wraps the waiting logic in an **Awaitable**
- Enqueues the event into the **EventQueue**
- The **Simulation’s main loop**:
1. Pop the next event from the EventQueue (earliest timestamp)
2. Advance the simulation clock to that time
3. Trigger that event → resume the waiting goroutine (Process)
- **Resource Manager**: processes request/release resources; if unavailable they get parked in a wait queue until another process calls `Release`
- **Store Manager**: `Put`/`Get` operations generate events when data becomes available or space frees up

##### Architectural patterns & design principles
- **Event-driven core loop** (single thread of control)
- **Goroutine-per-process**, but serial execution via explicit event triggers
- **Heap-based priority queue** for scheduling
- **Combinator pattern** for `allOf`/`anyOf` awaitables
- **Modular design**: core engine + pluggable resource/store modules + user API

##### Essential elements checklist
- All core Go modules (simulation.go, eventqueue.go, etc.)
- The main event loop and its interaction with Process and EventQueue
- The Resource and Store modules as separate components
- Public API functions as the “entry points”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code
    User["User Code<br/>(Examples)"]:::external
    click User "https://github.com/fschuetz04/simgo/tree/main/_examples/"

    %% Public API Layer
    subgraph "Public API Layer"
        NewSim["NewSimulation()"]:::api
        ProcRef["ProcessReflect(...)"]:::api
        RunUntil["RunUntil(...)"]:::api
        EvFunc["Event()/Timeout(...)"]:::api
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        Simulation["Simulation"]:::core
        EventQueue["EventQueue"]:::core
    end

    %% Process Management & Awaitables
    subgraph "Process Management"
        Process["Process"]:::abstraction
        Awaitable["Awaitable"]:::abstraction
        AllOf["allOf"]:::abstraction
        AnyOf["anyOf"]:::abstraction
    end

    %% Event Abstraction
    subgraph "Event Abstraction"
        Event["Event"]:::abstraction
    end

    %% Resource & Store Modules
    subgraph "Resource & Store Modules"
        ResourceMgr["Resource Manager"]:::module
        StoreMgr["Store Manager"]:::module
    end

    %% Connections
    User -->|"calls NewSimulation()"| NewSim
    User -->|"calls ProcessReflect()"| ProcRef
    User -->|"calls RunUntil()"| RunUntil
    User -->|"uses Event()/Timeout()"| EvFunc

    NewSim -->|"creates"| Simulation
    RunUntil -->|"starts loop"| Simulation

    Simulation -->|"holds"| EventQueue
    Simulation -->|"spawns goroutines"| Process

    ProcRef -->|"registers"| Process

    Process -->|"Wait()/Timeout() enqueues"| EventQueue
    EvFunc -->|"creates events for"| Process

    EventQueue -->|"pop next event"| Simulation
    Simulation -->|"advance time & trigger"| Process

    Process -->|"Request/Release"| ResourceMgr
    Process -->|"Put/Get"| StoreMgr

    %% Click Events
    click Simulation "https://github.com/fschuetz04/simgo/blob/main/simulation.go"
    click EventQueue "https://github.com/fschuetz04/simgo/blob/main/eventqueue.go"
    click Process "https://github.com/fschuetz04/simgo/blob/main/process.go"
    click Awaitable "https://github.com/fschuetz04/simgo/blob/main/awaitable.go"
    click AllOf "https://github.com/fschuetz04/simgo/blob/main/allof.go"
    click AnyOf "https://github.com/fschuetz04/simgo/blob/main/anyof.go"
    click Event "https://github.com/fschuetz04/simgo/blob/main/event.go"
    click ResourceMgr "https://github.com/fschuetz04/simgo/blob/main/resource.go"
    click StoreMgr "https://github.com/fschuetz04/simgo/blob/main/store.go"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef abstraction fill:#ABEBC6,stroke:#1D8348,color:#145A32
    classDef api fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef external fill:#D5D8DC,stroke:#566573,color:#212F3C
    classDef module fill:#F5B7B1,stroke:#C0392B,color:#641E16
```
