# garro95/desim architecture

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

- Interactive diagram: https://gitdiagram.com/garro95/desim
- Repository: https://github.com/garro95/desim

## Overview

Based on our analysis of the file tree and the README, “desim” is a Rust-based discrete-time events simulation framework. It is designed as a library that allows users to define and run simulations by scheduling and processing events through coroutines. The main purpose is to offer an efficient and concurrent simulation environment for both physical and logical systems.

##### Main Components
- Simulation Engine: At the core is the Simulation struct, which acts as the primary interface. It handles scheduling, running, and managing the simulation’s state.
- Process/Coroutine Manager: Representing the processes (or “coroutines”) that yield Effects, this component controls the lifecycle of simulation processes.
- Event Scheduler/Queue: This element manages the ordered list of events. It is responsible for selecting the next event and processing it.
- Resource Management: Since “desim” allows for resource allocation and custom Resource types (via a Resource trait), include a component for managing resources such as locks or resource pools.
- API/Interface Layer: Expose the public API methods that allow users to spawn processes, schedule events, and query simulation state (e.g., current simulation time or processed events).

##### Relationships and Interactions
- The Simulation Engine uses the Event Scheduler to determine which event to process next.
- Processes (coroutines) interact directly with the Simulation Engine by yielding Effects (such as scheduling further events or requesting resources).
- The Resource Manager is invoked by the Simulation Engine and processes when resources need to be allocated or deallocated.
- Initialization: Application code (or examples) creates a Simulation instance.
- Process spawning: Application code submits processes (coroutines) to the Simulation Engine.
- Event flow: An event is scheduled in the scheduler, then processed by the Simulation Engine which results in processes resuming and possibly triggering further actions.
- Resource interaction: Processes request resources and the Resource Manager responds, linking back to the Simulation Engine for eventual state updates.

##### Architectural Patterns and Design Principles
- Component-Based Design: The project is modular, with distinct roles for simulation control, process management, and resource management.
- Event-Driven Architecture: A central event queue drives simulation progress.
- Use of Experimental Coroutines: This is a key innovation; highlight that processes are implemented as coroutines, which allows yielding control and resuming, contributing to the simulator’s concurrency.
- Interface Segregation: The API layer exposes clear methods (ex: spawn process, schedule event) that lead inward to a well-encapsulated Simulation Engine.

##### Relevant Technologies/Frameworks
- Rust Programming Language: Note the use of Cargo for building, and mention reliance on experimental language features (like coroutines/generators).
- GitHub Workflows: Though primarily for CI/CD (build, test, format), acknowledge them as supporting artifacts ensuring code quality.

- “Event Scheduler” (managing the event queue)
- “Process/Coroutine Manager” (handling process lifecycles)
- “Resource Manager” (for handling resource allocation)
- An “API Layer” interfacing these components as the external face that developers interact with.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Simulation Components"
        SE["Simulation Engine (Simulation struct)"]:::core
        ES["Event Scheduler/Queue"]:::core
        PC["Process/Coroutine Manager"]:::core
        RM["Resource Manager"]:::core
    end

    subgraph "External Interfaces"
        API["API/Interface Layer"]:::external
        EX["Examples Integration"]:::external
        CICD["CI/CD Configuration"]:::external
    end

    API -->|"creates_simulation"| SE
    SE -->|"schedules_event"| ES
    SE -->|"manages_processes"| PC
    SE -->|"handles_resource_requests"| RM
    PC -->|"yields_effects"| SE
    ES -->|"triggers_process_resumption"| PC
    EX -->|"demonstrates_usage"| API
    CICD -->|"quality_checks"| SE

    click SE "https://github.com/garro95/desim/blob/master/src/lib.rs"
    click PC "https://github.com/garro95/desim/blob/master/src/lib.rs"
    click ES "https://github.com/garro95/desim/blob/master/src/lib.rs"
    click RM "https://github.com/garro95/desim/blob/master/src/resources.rs"
    click API "https://github.com/garro95/desim/blob/master/src/prelude.rs"
    click EX "https://github.com/garro95/desim/tree/master/examples/"
    click CICD "https://github.com/garro95/desim/tree/master/.github/workflows/"

    classDef core fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
