# moussare19/qsim architecture

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

- Interactive diagram: https://gitdiagram.com/moussare19/qsim
- Repository: https://github.com/moussare19/qsim

## Overview

QSIM is an educational C11 discrete-event simulator. A model is initialized, scheduled through the context API, and run by dispatching events until a time or predicate termination condition; the M/M/1 model handles arrivals and departures, then exposes a report of queueing metrics. The graph also preserves the documented random-number, distribution, event-management, and statistics capabilities. Some engine and reporting links rely on README descriptions or source-index references; unsampled implementation details are not inferred beyond those relationships.

Main entry points: [`mm1_handlers.c`](https://github.com/moussare19/qsim/blob/dev/mm1_handlers.c) (Arrival and departure), [`mm1_init.c`](https://github.com/moussare19/qsim/blob/dev/mm1_init.c) (M/M/1 setup), [`context.c`](https://github.com/moussare19/qsim/blob/dev/context.c) (Model context API), [`kernel.c`](https://github.com/moussare19/qsim/blob/dev/kernel.c) (Simulation kernel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Simulation engine"]
  node_context["Model context API<br/>[context.c]"]
  node_dispatch["Event dispatch<br/>[dispatch.c]"]
  node_kernel["Simulation kernel<br/>[kernel.c]"]
  node_clock["Virtual clock<br/>[clock.c]"]
  node_fel["Future event list<br/>[fel.c]"]
  node_event["Event notice<br/>[event.h]"]
end

subgraph group_stochastic["Stochastic modeling"]
  node_prng["xoshiro PRNG<br/>[prng.c]"]
  node_dist["Distributions<br/>[dist.c]"]
end

subgraph group_model["M/M/1 model"]
  node_mm1_init["M/M/1 setup<br/>[mm1_init.c]"]
  node_mm1_handlers["Arrival and departure<br/>[mm1_handlers.c]"]
  node_mm1_state["Queue model state<br/>[mm1_state.h]"]
  node_entity["Customer entities<br/>[entity.c]"]
  node_entity_queue["Waiting queue<br/>[entity_queue.c]"]
end

subgraph group_statistics["Statistics and reporting"]
  node_time_acc["Time accumulators<br/>[time_acc.c]"]
  node_sample_acc["Sample accumulators<br/>[sample_acc.c]"]
  node_mm1_report["Queueing report<br/>[mm1_report.c]"]
end

node_user(("Simulation user"))

node_user -->|"configures model"| node_mm1_init
node_user -->|"starts run"| node_mm1_init
node_mm1_init -->|"seeds generator"| node_prng
node_mm1_init -->|"creates context"| node_context
node_mm1_init -->|"runs dispatch"| node_dispatch
node_mm1_init -->|"schedules arrival"| node_mm1_handlers
node_mm1_handlers -->|"schedules events"| node_context
node_mm1_handlers -->|"samples durations"| node_dist
node_mm1_handlers -->|"updates state"| node_mm1_state
node_mm1_handlers -->|"creates and frees"| node_entity
node_mm1_handlers -->|"enqueues and dequeues"| node_entity_queue
node_mm1_handlers -->|"updates metrics"| node_time_acc
node_mm1_handlers -->|"records samples"| node_sample_acc
node_context -->|"uses kernel"| node_kernel
node_dispatch -->|"dispatches events"| node_context
node_kernel -->|"manages events"| node_fel
node_kernel -->|"advances time"| node_clock
node_fel -->|"stores notices"| node_event
node_dist -->|"draws random values"| node_prng
node_mm1_report -->|"reads model metrics"| node_mm1_state
node_user -->|"requests report"| node_mm1_report

click node_mm1_init "https://github.com/moussare19/qsim/blob/dev/mm1_init.c"
click node_mm1_handlers "https://github.com/moussare19/qsim/blob/dev/mm1_handlers.c"
click node_mm1_state "https://github.com/moussare19/qsim/blob/dev/mm1_state.h"
click node_entity "https://github.com/moussare19/qsim/blob/dev/entity.c"
click node_entity_queue "https://github.com/moussare19/qsim/blob/dev/entity_queue.c"
click node_context "https://github.com/moussare19/qsim/blob/dev/context.c"
click node_dispatch "https://github.com/moussare19/qsim/blob/dev/dispatch.c"
click node_kernel "https://github.com/moussare19/qsim/blob/dev/kernel.c"
click node_clock "https://github.com/moussare19/qsim/blob/dev/clock.c"
click node_fel "https://github.com/moussare19/qsim/blob/dev/fel.c"
click node_event "https://github.com/moussare19/qsim/blob/dev/event.h"
click node_prng "https://github.com/moussare19/qsim/blob/dev/prng.c"
click node_dist "https://github.com/moussare19/qsim/blob/dev/dist.c"
click node_time_acc "https://github.com/moussare19/qsim/blob/dev/time_acc.c"
click node_sample_acc "https://github.com/moussare19/qsim/blob/dev/sample_acc.c"
click node_mm1_report "https://github.com/moussare19/qsim/blob/dev/mm1_report.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_context,node_dispatch,node_kernel,node_clock,node_fel,node_event,node_user toneBlue
class node_prng,node_dist toneAmber
class node_mm1_init,node_mm1_handlers,node_mm1_state,node_entity,node_entity_queue toneMint
class node_time_acc,node_sample_acc,node_mm1_report toneRose
```

## Components

### Simulation engine

- [Model context API](https://github.com/moussare19/qsim/blob/dev/context.c): `context.c`
- [Event dispatch](https://github.com/moussare19/qsim/blob/dev/dispatch.c): `dispatch.c`
- [Simulation kernel](https://github.com/moussare19/qsim/blob/dev/kernel.c): `kernel.c`
- [Virtual clock](https://github.com/moussare19/qsim/blob/dev/clock.c): `clock.c`
- [Future event list](https://github.com/moussare19/qsim/blob/dev/fel.c): `fel.c`
- [Event notice](https://github.com/moussare19/qsim/blob/dev/event.h): `event.h`

### Stochastic modeling

- [xoshiro PRNG](https://github.com/moussare19/qsim/blob/dev/prng.c): `prng.c`
- [Distributions](https://github.com/moussare19/qsim/blob/dev/dist.c): `dist.c`

### M/M/1 model

- [M/M/1 setup](https://github.com/moussare19/qsim/blob/dev/mm1_init.c): `mm1_init.c`
- [Arrival and departure](https://github.com/moussare19/qsim/blob/dev/mm1_handlers.c): `mm1_handlers.c`
- [Queue model state](https://github.com/moussare19/qsim/blob/dev/mm1_state.h): `mm1_state.h`
- [Customer entities](https://github.com/moussare19/qsim/blob/dev/entity.c): `entity.c`
- [Waiting queue](https://github.com/moussare19/qsim/blob/dev/entity_queue.c): `entity_queue.c`

### Statistics and reporting

- [Time accumulators](https://github.com/moussare19/qsim/blob/dev/time_acc.c): `time_acc.c`
- [Sample accumulators](https://github.com/moussare19/qsim/blob/dev/sample_acc.c): `sample_acc.c`
- [Queueing report](https://github.com/moussare19/qsim/blob/dev/mm1_report.c): `mm1_report.c`

### Other components

- **Simulation user**

## Connections

- Simulation user → M/M/1 setup: configures model (evidence: `README.md`)
- Simulation user → M/M/1 setup: starts run (evidence: `README.md`)
- M/M/1 setup → xoshiro PRNG: seeds generator (evidence: `mm1_init.c`)
- M/M/1 setup → Model context API: creates context (evidence: `mm1_init.c`)
- M/M/1 setup → Event dispatch: runs dispatch (evidence: `mm1_init.c`)
- M/M/1 setup → Arrival and departure: schedules arrival (evidence: `mm1_init.c`)
- Arrival and departure → Model context API: schedules events (evidence: `mm1_handlers.c`)
- Arrival and departure → Distributions: samples durations (evidence: `mm1_handlers.c`)
- Arrival and departure → Queue model state: updates state (evidence: `mm1_handlers.c`)
- Arrival and departure → Customer entities: creates and frees (evidence: `mm1_handlers.c`)
- Arrival and departure → Waiting queue: enqueues and dequeues (evidence: `mm1_handlers.c`)
- Arrival and departure → Time accumulators: updates metrics (evidence: `mm1_handlers.c`)
- Arrival and departure → Sample accumulators: records samples (evidence: `mm1_handlers.c`)
- Model context API → Simulation kernel: uses kernel (evidence: `README.md`)
- Event dispatch → Model context API: dispatches events (evidence: `README.md`)
- Simulation kernel → Future event list: manages events
- Simulation kernel → Virtual clock: advances time
- Future event list → Event notice: stores notices
- Distributions → xoshiro PRNG: draws random values (evidence: `dist.c`)
- Queueing report → Queue model state: reads model metrics (evidence: `mm1_report.c`)
- Simulation user → Queueing report: requests report (evidence: `README.md`)