# johthor/domainstory-plantuml architecture

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

- Interactive diagram: https://gitdiagram.com/johthor/domainstory-plantuml
- Repository: https://github.com/johthor/domainstory-plantuml

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "Core Library Module"
        direction TB
        domainStory["domainStory.puml"]:::library
        activitiesIuml["activities.iuml"]:::library
        actorsIuml["actors.iuml"]:::library
        boundariesIuml["boundaries.iuml"]:::library
        composite["domainStoryComposite.puml"]:::library
        header["header.iuml"]:::library
        helper["helper.iuml"]:::library
        notesIuml["notes.iuml"]:::library
        objectsIuml["objects.iuml"]:::library
        stateIuml["state.iuml"]:::library
        storyLayout["storyLayout.iuml"]:::library
        stylingIuml["styling.iuml"]:::library
        theming["theming.iuml"]:::library
        utilities["utilities.iuml"]:::library
    end

    subgraph "Build/Test Harness"
        direction TB
        runSh["run.sh"]:::test
        subgraph "Sharness Library"
            direction TB
            sharnessInstall["install-sharness.sh"]:::test
            plantumlVersion["plantuml.version"]:::test
            testUtils["testUtils.sh"]:::test
        end
        subgraph "Test Scripts"
            direction TB
            activitiesTest["activities.test.sh"]:::test
            notesTest["notes.test.sh"]:::test
            notesSmetanaTest["notes-smetana.test.sh"]:::test
            stylingTest["styling.test.sh"]:::test
            testSuite["testSuite.sh"]:::test
        end
        subgraph "Test Diagrams"
            direction TB
            testDiagrams["diagrams/"]:::test
            testPuml["puml/"]:::test
            testPumlSmetana["puml-smetana/"]:::test
        end
        subgraph "Expected Outputs"
            direction TB
            expectedActivities["preprocessed/activities/"]:::test
            expectedNotes["preprocessed/notes/"]:::test
            expectedStyling["preprocessed/styling/"]:::test
        end
    end

    subgraph "Sample Repository"
        direction TB
        basic["basic.puml"]:::samples
        darkBasic["basic_DARK_MODE.puml"]:::samples
        cinema["cinema.puml"]:::samples
        airportBus["airportBus.puml"]:::samples
        extensions["extensions.puml"]:::samples
        pictographic["pictographicLanguage.puml"]:::samples
    end

    subgraph "Documentation Generator"
        direction TB
        macroSyntax["macroSyntax.puml"]:::docs
        styleNames["stylePropertyNames.puml"]:::docs
        styleHierarchy["stylePropertyHierarchy.puml"]:::docs
        docsAssets["docs/assets/"]:::docs
    end

    subgraph "Metadata & Docs"
        direction TB
        readme["README.md"]:::external
        changelog["CHANGELOG.md"]:::external
        license["LICENSE"]:::external
    end

    %% External Services
    plantumlCLI["PlantUML CLI"]:::external
    githubCI["GitHub Actions CI"]:::external

    %% Relationships
    runSh -->|"invokes"| activitiesTest
    runSh --> notesTest
    runSh --> notesSmetanaTest
    runSh --> stylingTest
    runSh --> testSuite

    activitiesTest -->|"includes"| domainStory
    notesTest --> domainStory
    notesSmetanaTest --> domainStory
    stylingTest --> domainStory
    testSuite --> domainStory

    domainStory -->|"uses macros from"| activitiesIuml
    domainStory --> actorsIuml
    domainStory --> boundariesIuml
    domainStory --> composite
    domainStory --> header
    domainStory --> helper
    domainStory --> notesIuml
    domainStory --> objectsIuml
    domainStory --> stateIuml
    domainStory --> storyLayout
    domainStory --> stylingIuml
    domainStory --> theming
    domainStory --> utilities

    activitiesTest -->|"renders via"| plantumlCLI
    plantumlCLI --> expectedActivities
    notesTest --> plantumlCLI
    plantumlCLI --> expectedNotes
    stylingTest --> plantumlCLI
    plantumlCLI --> expectedStyling

    macroSyntax --> domainStory
    styleNames --> domainStory
    styleHierarchy --> domainStory
    macroSyntax -->|"renders via"| plantumlCLI
    styleNames --> plantumlCLI
    styleHierarchy --> plantumlCLI
    plantumlCLI --> docsAssets

    basic --> domainStory
    darkBasic --> domainStory
    cinema --> domainStory
    airportBus --> domainStory
    extensions --> domainStory
    pictographic --> domainStory

    githubCI --> runSh
    githubCI --> plantumlCLI

    %% Click Events
    click domainStory "https://github.com/johthor/domainstory-plantuml/blob/main/domainStory.puml"
    click activitiesIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/activities.iuml"
    click actorsIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/actors.iuml"
    click boundariesIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/boundaries.iuml"
    click composite "https://github.com/johthor/domainstory-plantuml/blob/main/src/domainStoryComposite.puml"
    click header "https://github.com/johthor/domainstory-plantuml/blob/main/src/header.iuml"
    click helper "https://github.com/johthor/domainstory-plantuml/blob/main/src/helper.iuml"
    click notesIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/notes.iuml"
    click objectsIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/objects.iuml"
    click stateIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/state.iuml"
    click storyLayout "https://github.com/johthor/domainstory-plantuml/blob/main/src/storyLayout.iuml"
    click stylingIuml "https://github.com/johthor/domainstory-plantuml/blob/main/src/styling.iuml"
    click theming "https://github.com/johthor/domainstory-plantuml/blob/main/src/theming.iuml"
    click utilities "https://github.com/johthor/domainstory-plantuml/blob/main/src/utilities.iuml"
    click runSh "https://github.com/johthor/domainstory-plantuml/blob/main/run.sh"
    click sharnessInstall "https://github.com/johthor/domainstory-plantuml/blob/main/test/lib/install-sharness.sh"
    click plantumlVersion "https://github.com/johthor/domainstory-plantuml/blob/main/test/lib/plantuml.version"
    click testUtils "https://github.com/johthor/domainstory-plantuml/blob/main/test/lib/testUtils.sh"
    click activitiesTest "https://github.com/johthor/domainstory-plantuml/blob/main/test/activities.test.sh"
    click notesTest "https://github.com/johthor/domainstory-plantuml/blob/main/test/notes.test.sh"
    click notesSmetanaTest "https://github.com/johthor/domainstory-plantuml/blob/main/test/notes-smetana.test.sh"
    click stylingTest "https://github.com/johthor/domainstory-plantuml/blob/main/test/styling.test.sh"
    click testSuite "https://github.com/johthor/domainstory-plantuml/blob/main/test/testSuite.sh"
    click testDiagrams "https://github.com/johthor/domainstory-plantuml/tree/main/test/diagrams/"
    click testPuml "https://github.com/johthor/domainstory-plantuml/tree/main/test/puml/"
    click testPumlSmetana "https://github.com/johthor/domainstory-plantuml/tree/main/test/puml-smetana/"
    click expectedActivities "https://github.com/johthor/domainstory-plantuml/tree/main/test/preprocessed/activities/"
    click expectedNotes "https://github.com/johthor/domainstory-plantuml/tree/main/test/preprocessed/notes/"
    click expectedStyling "https://github.com/johthor/domainstory-plantuml/tree/main/test/preprocessed/styling/"
    click basic "https://github.com/johthor/domainstory-plantuml/blob/main/samples/basic.puml"
    click darkBasic "https://github.com/johthor/domainstory-plantuml/blob/main/samples/basic_DARK_MODE.puml"
    click cinema "https://github.com/johthor/domainstory-plantuml/blob/main/samples/cinema.puml"
    click airportBus "https://github.com/johthor/domainstory-plantuml/blob/main/samples/airportBus.puml"
    click extensions "https://github.com/johthor/domainstory-plantuml/blob/main/samples/extensions.puml"
    click pictographic "https://github.com/johthor/domainstory-plantuml/blob/main/samples/pictographicLanguage.puml"
    click macroSyntax "https://github.com/johthor/domainstory-plantuml/blob/main/docs/puml/macroSyntax.puml"
    click styleNames "https://github.com/johthor/domainstory-plantuml/blob/main/docs/puml/stylePropertyNames.puml"
    click styleHierarchy "https://github.com/johthor/domainstory-plantuml/blob/main/docs/puml/stylePropertyHierarchy.puml"
    click docsAssets "https://github.com/johthor/domainstory-plantuml/tree/main/docs/assets/"

    %% Styles
    classDef library fill:#AEDFFF,stroke:#333,stroke-width:1px
    classDef test fill:#DFFFAE,stroke:#333,stroke-width:1px
    classDef docs fill:#FFF5AE,stroke:#333,stroke-width:1px
    classDef samples fill:#FFD0A0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
