Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

C4 DSL #63

Open
victorvogelpoel opened this issue Feb 24, 2018 · 4 comments
Open

C4 DSL #63

victorvogelpoel opened this issue Feb 24, 2018 · 4 comments

Comments

@victorvogelpoel
Copy link
Contributor

Your "Record" addition sparked an idea. Adding more DSL-thingies

I am already using PSGraph to plot a certain stucture in a system I am administrating, The system is the authority, PSGraph visualizes it.

I am reading up on Simon Brown's C4 Architecture modelling: define architecture in code. Its Java implementation is able to export the definition to DOT, but the C# version does not. Enter PowerShell and PSGraph...
How about creating a DSL for C4 in PSGraph (perhaps as an extension)?

@KevinMarquette
Copy link
Owner

I like the idea. I anticipate adding more commands or examples that facilitate creating things that can be done with UML. I don't know much about C4 off hand. I did a quick search and found this reference: https://c4model.com/#notation

Looking at the notation and the metamodel, the basics looks to be very doable. Creating the DSL commands for Person, Container, Component, Relationship, ect would not be bad at all.

With the current logic, each view would be a new graph. that would remove the need to add any view related logic unless I wanted to add support for constrained views. (ex, a view could define the elements that are allowed to be used). I don't think I'm ready to go down that path.

I'll have to decide how I would ultimately implement this. Do I add extension support? What does that really mean to PSGraph? How would extensions be managed? or should this just be a 2nd module called PSGraphC4 that depends on PSGraph?

@PeterMTaylor
Copy link

I would be very interested Kevin to “extend” auto generated documentation adapting the C4 notation suggested for some Github source code with another Powershell Github API that converts downloaded raw source code like C# into C4 notation overview so developers could pick up pace for contribution. Sometime Visual overview of the project is all it’s needed for their initial hesitation, then combine with PScribo to format the document into viewable pages for reading.

To offer some input into your C4 design perhaps a command from your Readme might look easier with an extra attribute called -notation attached to represent any “extended” notations you may add or support further beyond C4 in the future so C4 could be another name.

Thus:
Export-PSGraph -notation C4 -Source $env:temp\hello.vz -Destination $env:temp\hello.png -ShowGraph

PSGraph still holds the responsibility of nodes, edges, it’s the output context that requires some thought as to which shape will represent a node or edge of interest. So maybe suggesting a library of which symbols to “extend” your notation and the attributes is like an index of which notation to apply on the output command.

Cheers,
Peter.

@victorvogelpoel
Copy link
Contributor Author

I'd like to define the architecture of a software system in a (PowerShell) DSL a la C4 and have PSGraph visualize it (handle the dirty bits of the DOT language). Define Persons, Containers, Components and relationships and then define multiple views. And hand this to PSGraph script to visualize specified views.

Thinking a little more about this, I think the PSGraph C4 additions would simply be a graph script for each view type and knows how to translate the C4 model entities to PSGraph entities to DOT entities. Does this make sense? Have some thinking to do...

@KevinMarquette
Copy link
Owner

KevinMarquette commented Feb 26, 2018

@victorvogelpoel You are on the right track with that approach.

If we peel back the covers on PSGraph, its just doing the PowerShell to DOT conversion with its commands. The output of Graph {...} is DOT syntax. You can actually run each command node,edge,rank command individually to see the DOT strings it would create.

I am trying to keep PSGraph as just that translation layer to DOT. All my commands that leverage PSGraph are packaged into PSGraphPlus.

So I would see this PSGraphC4 module as one that depends on PSGraph. It would have its own DSL. Those commands would basically have to build a nested object or data structure with relationships.

Here are 2 quick passes at what a DSL could look like:

This first one would be fairly easy to implement in PowerShell with advanced functions, scriptblocks, and fancy parameter binding. The description would be optional. The ID could be the name. I see those 2 as the node name and label.

PSGraphC4 {
    Person Customer -Description 'A Customer of the Bank'
    SoftwareSystem -ID IBS 'Internet Banking System' -Description 'Allow customers to view accounts' {
        Container -ID IBS-Web 'Web Application' -Description 'The intenet facing interface' {
            Component 'Home Page Controler'
            Component 'Accounts Summary Controler'
            Component 'Mainframe Banking System Facade'
            Component 'Sign In Controller'
            Component 'Security Component'
        }
        Container -ID IBS-SQL 'Database' -Description 'Stores interesting data'
    }
    SoftwareSystem -ID MBS 'Mainframe Baning System' -Description 'stores all the core banking info'
}

Alternatively, the description could be in the scriptblock. We would have to be a little more clever in the code, but it may be worth it

SoftwareSystem -ID IBS 'Internet Banking System'  {
    Description 'Allow customers to view accounts'
    Container -ID IBS-Web 'Web Application' {
        Description 'The intenet facing interface' 
        Component 'Home Page Controler'
        ...

This 2nd one leverages a DSC style syntax that is provided by the dynamickeyword class. I think this is possible.

PSGraphC4 {
    Person Customer {
        Name        = 'Customer'
        Description = 'A Customer of the Bank'
    }
    SoftwareSystems {
        SoftwareSystem IBS {
            Name        = 'Internet Banking System'
            Description = 'Allow customers to view accounts'
            Containers  = {
                Container IBS-WEB {
                    Name        = 'Web Application'
                    Description ='The intenet facing interface'
                    Components  = {
                        Component IBS-WEB-HPC  {Name = 'Home Page Controler'}
                        Component IBS-WEB-ASC  {Name='Accounts Summary Controler'}
                        Component IBS-WEB-MBSF {Name='Mainframe Banking System Facade'}
                        Component IBS-WEB-SIC  {Name='Sign In Controller'}
                        Component IBS-WEB-SC   {Name='Security Component'}
                    }
                }
                Container IBS-SQL {
                    Name        = 'Database'
                    Description ='Stores interesting data'
                }
            }
        }
        SoftwareSystem -ID MBS 'Mainframe Baning System' -Description 'stores all the core banking info'
    }
}

Missing from both of those examples is the relationships. I have not fleshed anything our for that. I expect that is where we would want to use an ID for every object.

We may want our data structure to be easy to load and save from JSON. That would open up other tooling options. Kick these ideas around a bit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants