How johthor/domainstory-plantuml works
Project Type and Purpose
• This is an open-source PlantUML extension library that provides macros, themes, and tooling to document domain stories visually.
• Key use cases: define actors, work objects, boundaries, activities; support styling, theming, and extensibility; ship with samples and an automated test harness.
File Structure
• Root level
– domainStory.puml: the core macro library.
– run.sh: entry point script for running tests and demos.
– README.md, CHANGELOG.md, LICENSE: documentation and metadata.
• src/
– Definitions of PlantUML macros in .iuml and .puml fragments (activities.iuml, actors.iuml, boundaries.iuml, styling.iuml, etc.)
• docs/
– assets/: rendered SVGs for the README.
• samples/
– Example domain stories (basic.puml, cinema.puml, airportBus.puml, extensions.puml).
• test/
– test suite built on a shell-based “sharness” harness (test/lib).
– test scripts (.test.sh) that invoke run.sh or plantuml and compare outputs against preprocessed expected files in test/preprocessed.
– puml test cases (test/puml-smetana/, test/puml/) and their expected results.
README for Additional Insights
• Describes the macro syntax, styling methods, advanced features, and integration points with PlantUML (local includes, remote includes, standard library).
• Enumerates styling properties, theming options, and extension points.
a. Main Components
1. Core Library Module (domainStory.puml + src/)
2. Build/Test Harness (run.sh, test/ scripts, test/lib/sharness)
3. Sample Repository (samples/)
4. Documentation Generator (docs/, PlantUML engine)
5. External Dependencies (PlantUML CLI, GitHub/raw content URL)
b. Component Relationships
• samples/ live‐link to the Core Library via local or remote include → used for demonstrations.
• GitHub Actions or manual invokes of run.sh coordinate builds, tests, and sample renders.
c. Architectural Patterns and Principles
• Modular layering:
– Macro definition layer (src/)
– Packaging layer (domainStory.puml)
– Consumer layer (samples, tests, docs)
• Single Responsibility: tests only validate output; samples only demonstrate usage; docs only illustrate.
• Extensibility: src/ fragments can be extended or overridden (extension sample).
d. Key Technologies
• PlantUML: macro parsing and rendering engine.
• Bash + Sharness: test orchestration and assertion framework.
• GitHub: repository host, issue templates, CI triggers.
Detailing Essential Architectural Elements
• domainStory.puml packaging as the published artifact.
• How the src/ fragments compose into that single include.
• Test harness comparing actual vs. expected (test/preprocessed).
• User workflows:
– Writing a new .puml that !include domainStory.puml
– Running PlantUML locally vs. via CI