briggysmalls / archie

Tool for documenting system architecture

archie

Simple model-based system architecture tooling

Installation

Install the CLI with:

go get github.com/briggysmalls/archie/cli/archie

Documentation

The full project documentation can be found at:

https://briggysmalls.github.io/archie

archie's Issues

Add coverage

Its handy having coverage tests as part of a CI server, to quickly review if new changes are covered by test cases.

Tag view doesn't show connected, untagged elements

The tag view should show any elements connected to those tagged with the tag in question, even if they have no tag.

However currently untagged elements just simply disappear

Use a simple model in API

The JSON/YAML format of the model is a nice simplified version of the model.

We only need the complex one for the searching through the heirarchy etc.

Even drawing should only need the simplified model (without all the pointers and parent/child links).

Could an API be exposed, that makes a Model interface that exposes ContextView and LandscapeView that returns these simplified models. Hiding all the complexity from the caller?

Coaleace associations into single arrow

A system, at the zoomed out, top-level view, may have associations between items that represent multiple connections at a low-level view.

For example a user may interact with a hi-fi system in multiple ways: drive volume control, drive input select, receive sound, receive status indicators.

The question is how to represent the implicit relationships. Should the two be connected with a single, no-arrow-headed line? Or two arrows in each direction?

Use go generate where relevant

Things like the documentation could be generated using go generate.

This would allow us to use Archie in a pre build step

Add associations section to YAML element

It has been suggested that the YAML could have an associations section to elements.

This would allow definition of associations between children local to where they are defined making it more readable.

It also would eliminate the need to fully namespace the souce/destinations, further improving readability and making them easier to write.

Consider data flow diagram

The current diagrams present a view a bit like a SysML 'internal block diagram'. The way it's been used is for associations to indicate dependencies, and not inheritance etc. It doesn't indicate 'activities'/'processes'.

Other diagrams, such as a data flow diagram, exist that do reveal 'functions'. This can be helpful to indicate when relationships come into play.

It might be useful to extend the model to support annotating relationships with this concept

Tag view doesn't work properly at root level

It seems that if all elements are root level elements, and the tag view is used, then related elements are not displayed. Instead only element with the given tag are shown.

This is probably a bug in the logic for looking at if the parent of primary elements is a shared anscestor (the parent of a root element is nil)

Create API specification

This project exposes an API for generating diagrams.

This could be specified using the openAPI specification within this project. This would enable:

• Easier consumption by clients. For example, clients could be generated using Swagger tools.
• The server could be generated from the API using a too like go-swagger which would remove manual boilerplate
• Serve swagger UI for documentation of the API

Expand README

The repo should at the very least have a README

Images not repeatable: sort tags

Currently tags can appear in different orders (presumably due to iterating through dicts somewhere).

The tags should be ordered once they've been coalesced.

Do not display associations between non-primary elements

The context diagram currently will display associations between an actor and an item when neither are within the scope of the context diagram.

These associations should be omitted.

Switch to mage

I’m done with makefiles!

Let’s keep trying to use mage.

make viewer SPA

The viewer serves a new page each view, which reloads the mermaid library every time.

There are a load of incremental improvements that could be made:

• preload/cache mermaid.js?
• SPA that requests diagram from golang api
• SPA that uses golang core library compiled to WASM as a library

Add logging middleware to API

Currently it's not very easy to debug issues with the server.

It is easy enough to add logging middleware to gorillamux, in fact it seems so common that people have written some standard handlers.

This would be useful for debugging issues, inspecting requests that hit the server.

Generate interfaces

When two items connect via multiple sub-items it can be easy to lose track of the number of connections that must be supported through that interface.

In the future it would be nice to have some way of enumerating the different connections contained within an interface.

Make CLI application have name 'archie'

Projects like delve ensure the delve tool has a desireable name by having a structure like:

delve
└── cmd
    └── dlv
...

This should be done with this project so that the archie tool is installed with a reasonable name

Collapse parents if they contain nothing

When making a context diagram for something that has multiple parents that contain nothing else, the diagram could be neatly collapsed by writing A/B or similar. Reducing extra lines.

Associations have technology

Associations should be able to be labelled with a technology* too.

*note: I'm not keen on the word technology for this...

Document CLI

The first documentation should begin by documenting the CLI.

Improve CLI API

The CLI API leaves something to be desired. Some potential improvements:

• Make diagram 'type' (landscape, context, tag) a sub-command. This will enable proper checking of correct parameters for 'context' say (i.e. require scope but no tag)
• Make model a positional argument: we always need it

Allow bare elements at root level

Currently item elements must be defined in the long form at the root level:

model:
  elements:
    - name: hello

It would be nice to be able to use the short form:

model:
  elements:
    - hello

Ensure tag colours are consistent

If generating multiple diagrams from the same model, it would be expected for the tag colours to remain consistent. However currently they are not.

Provide styling to api with request

Currently a configuration file can be provided to give the API some plantUml styling that will apply to all diagrams.

More flexible would be to allow the requester to supply styling on a per-request basis.

This is also preferable because the requester may not have control of the server.

Introduce technology diagram

It is useful to filter a system according to a particular discipline so that certain teams can review all the modules together, even if they are divided across different logical boundaries.

For example, electronics engineers will be interested in all electronic blocks in order to consider deployment to different PCBs. All electronic element should be rendered even if some are associated within one logical block (e.g. amplification) vs another (e.g. connectivity)

Mix tag/context view

In the case where a software item is being specified. A 'leaf' in a system tree with the tag 'software'.

It would be useful to display a 'context' diagram for this item that only shows software. This is esstentially the 'context' view - including only related elements - but with the 'burrowing' behaviour of the tag view.

It is not helpful to show a leaf item's context if the relations are all higher level functional blocks.

Add GitHub repo to documentation

It's nice to link to the documentation, however it is important for people to be able to find their way to the repo

Tag view should add actors if connected to primaries

Currently the tag view, if passed a nil scope (i.e. entire landscape) won't add actors even if they are connected to a primary element (one that is assigned the requested tag)

'Strict' mode

Possibly reinvented the wheel when coaleascing connections between elements.

It appears 'dot' has a 'strict' mode that will do this itself.

https://www.graphviz.org/doc/info/lang.html

Make graphviz configurable

Right now there is no way to add a 'footer' like in plantuml to influence styling.

Coalesce mirrored associations

Two items may be connected with associations that are identical, save for the the source and destination are reversed. Currently this is rendered as below:

This adds clutter/noise for not much benefit. Either a double-headed arrow, or even a no-headed arrow would convey this information better.

This continues the work discussed in #9

Build docker image in circleci

Currently the docker image is built on dockerhub.

However the documentation, which is built in circle CI, depends on this docker image.

Changes to the documentation and archie may well occur simultaneously (it is documentation after all!) which might mean that we get stuck in a dependency cycle: docs require latest archie, but latest archie can't be built until committed to master.

Building the docker container in circleci should make it available immediately

Make Graphviz directed

I think there is use in having directed graphs (arrows with arrowheads).

The Graphviz writer doesn't currently draw them.

Issue #9 could help with diagram clutter in the case of too many arrows.

Identify elements that have children

In a context view it would be useful to distinguish elements that have more children inside. Maybe by using a slightly different shape?

Specify writer on command line

There should be a way to specify writers on the command line.

Lookup scope error is overwritten

The error resulting from lookup scope is overwritten and therefore silently ignored.

archie/archie.go

Line 62 in 706ade9

element, err = a.lookupScope(scope)

Check no composition makes an actor a parent

Actors cannot be a parent, and should therefore never the source of a composition relationship

This validation could be added to the model code.

Allow multiple tags in associations

Elements can have multiple tags assigned to them.

However currently each association needs its own entry.

There are merits to each approach, but I do find myself wishing there was a shorthand for connecting multiple things between the same two elements.

Compile to javascript

Given most of the use cases for archie is to display diagrams in a browser, it would be handy to have a javascript library.

This could enable the development of a frontend viewer, as well as the simpler desire to just render 'static' diagrams for documentation.

Validate model schema

Tools such as json-schema exist for validating that json meets a predefined schema.

Any provided model to core should be validated against a schema.

Given golang seems only to have a json-schema validator, perhaps core should aim to work only with JSON. Or convert yaml to JSON in order to validate it like that.

Document package

The package should be documented.

This is done using godoc.

golint will prompt you to document exported things properly

Fix inconsistency in context connectins

The context diagram will draw an association between two elements that are within the scope.

However if one of the elements contains sub-elements and is made the scope of a context diagram, the same association will not be drawn to the enclosing scope 'package'.

This is inconsistent behaviour, either:

1. Associations cannot have a source/destination that has sub-elements
2. Associations should be drawn to/from elements that are the enclosing scope in a context diagram