How emichael/dslabs works
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.