# emichael/dslabs architecture

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

- Interactive diagram: https://gitdiagram.com/emichael/dslabs
- Repository: https://github.com/emichael/dslabs

## Overview

Based on our analysis of the file tree and the README, this project is a distributed systems framework intended for educational labs. Its purpose is to provide a complete infrastructure for creating, testing, model checking, visualizing, and debugging distributed systems implementations. It contains not only the core framework APIs (such as the definition of nodes, messages, timers, etc.) but also a comprehensive testing harness, visualization tools, and lab assignments that cover various distributed protocols (from ping-pong protocols to Paxos and sharded key/value stores).

##### Main Components to Highlight
- Framework Core: Represent the core package located in the 'framework/src/dslabs/framework'. This includes components like Address, Application, Node, Message, Timer, and related classes that form the backbone of the distributed system programming model.
- Testing Infrastructure: Identify the two testing directories ('framework/tst' and 'framework/tst-self') which include the JUnit tests, model checking components, search utilities, and visualization testing modules. This part of the system is responsible for ensuring correctness through automated testing and model checking.
- Grading Tools: Include a separate grading component which is found under the 'grading' directory. This contains grading scripts (Python scripts and configuration files) used by teaching assistants to batch grade student submissions.
- Student Handouts: Represent a component for 'handout-files', which provides student-facing materials such as a README, test runner scripts, and a Makefile to build handouts.
- Website/Documentation: The 'www' directory holds the website built (by Jekyll) that documents the project, its slides, and other resources.
- Build and Configuration: Do not forget to capture the build system (gradle files, gradle wrapper, settings.gradle, Makefile) that ties together the build, dependency resolution (including use of Java 17, Python 3, Lombok, and google-java-format), and project formatting.

##### Relationships and Data Flow
- That the Framework Core provides the API through which lab assignments implement distributed nodes and protocols.
- That the Testing Infrastructure (with both self-tests and lab-specific tests) invokes the Framework Core components and runs them in emulated network conditions with message-passing and timer events.
- That the Grading Tools use parts of the Testing Infrastructure to execute tests and generate feedback for submitted labs.
- Interaction between the Visualization module (under testing/visualization) and the Framework Core to graphically represent execution traces, message flows, and to highlight invariant violations.

##### Architectural Patterns and Design Principles
- Use of a message-passing, event loop model (nodes consuming messages and timer events) as the cornerstone of the programming model.
- Separation of concerns: the core framework (API), testing and model checking (ensuring correct behavior under various interleavings), and lab assignments (allowing incremental learning and development).
- Integration of a visual debugging tool that aids both testing (by showing invariant-violating traces) and student understanding.
- The design also clearly separates student code (found in the lab folders) from the framework and testing mechanisms provided to support and grade the implementations.

- Partition the container into several layers or modules: Core Framework, Testing & Model Checking, Lab Assignments, Support Tools (Grading & Handouts), and Website/Documentation.
- Within the Core Framework, delineate subcomponents that handle network messaging, state management of nodes, and timer events.
- Within Testing & Model Checking, illustrate the test execution engine and the visualization module that displays invariant violations.
- Interactions: for instance, lab implementations rely on the Core Framework, which is then exercised by the Testing Infrastructure; the Grading Tools execute these same tests and interface with the build system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Framework Layer
    Core["Distributed Node API"]:::core

    %% Testing & Model Checking Layer
    TestEngine["Test Execution Engine"]:::testing
    VisualDebugger["Visualization Debugger"]:::testing

    %% Lab Assignments Layer
    LabCode["Lab Assignment Code"]:::labs

    %% Support Tools Layer
    Grading["Grading Scripts"]:::support
    Handouts["Student Handouts"]:::support

    %% Website/Documentation Layer
    Website["Website & Documentation"]:::website

    %% Build & Configuration Subgraph
    subgraph "Build & Configuration"
        BC1["build.gradle"]:::build
        BC2["settings.gradle"]:::build
        BC3["Makefile"]:::build
        BC4["gradlew"]:::build
        BC5["gradlew.bat"]:::build
        BC6[".gradle-wrapper"]:::build
    end

    %% Relationships
    %% Build system supports all components (using BC1 as representative)
    BC1 -->|"build/dependency"| Core
    BC1 -->|"build/dependency"| TestEngine
    BC1 -->|"build/dependency"| LabCode
    BC1 -->|"build/dependency"| Grading
    BC1 -->|"build/dependency"| Handouts
    BC1 -->|"build/dependency"| Website

    %% Core Framework interactions
    LabCode -->|"APIcalls"| Core
    TestEngine -->|"TestExecution"| Core
    TestEngine -->|"ModelTrace"| VisualDebugger

    %% Testing and Grading
    Grading -->|"ExecuteTests"| TestEngine
    LabCode -->|"Submission"| Grading

    %% Class Definitions (colors)
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef testing fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef labs fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef support fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef website fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for Component Mapping
    click Core "https://github.com/emichael/dslabs/tree/master/framework/src/dslabs/framework"
    click TestEngine "https://github.com/emichael/dslabs/tree/master/framework/tst"
    click VisualDebugger "https://github.com/emichael/dslabs/tree/master/framework/tst-self"
    click LabCode "https://github.com/emichael/dslabs/tree/master/labs"
    click Grading "https://github.com/emichael/dslabs/tree/master/grading"
    click Handouts "https://github.com/emichael/dslabs/tree/master/handout-files"
    click Website "https://github.com/emichael/dslabs/tree/master/www"
    click BC1 "https://github.com/emichael/dslabs/blob/master/build.gradle"
    click BC2 "https://github.com/emichael/dslabs/blob/master/settings.gradle"
    click BC3 "https://github.com/emichael/dslabs/tree/master/Makefile"
    click BC4 "https://github.com/emichael/dslabs/tree/master/gradlew"
    click BC5 "https://github.com/emichael/dslabs/blob/master/gradlew.bat"
    click BC6 "https://github.com/emichael/dslabs/blob/master/.gradle-wrapper"
```
