Coding an architecture roadmap

Latest code experiment - using Go as an interface between an architecture repository to make visualisations/ reports/ charts.


Solution Architecture involves, among other things, looking to the future of what the current landscape should or could be. Things might not be great now, so you've got reason to change. Things might actually be great now, and they could be better - or you could need to do work to ensure things stay good. Whatever the reason, just like unmaintained code rots, un-managed architecture crumbles. A key asset in this future planning is the Roadmap.


An architectural roadmap looks at the current state of things, describes a desired future state of things, and then knuckles down to figure out what you need to do to get from A to B. All maps are wrong, as Simon Wardley says, but some maps are useful. Lesson number 1 in mapping, just like in project management, no plan survives contact with reality. BUT having a goal, a strategy, and a plan to achieve these is more reliable in getting to your end state than throwing milestones at a Gantt chart and hoping.

Working with others, there was some really good visual templates created that gave a really good visualisation of baseline->work packages->target. Unfortunately, some upgrades of source systems made the templates disappear. Or at least, no longer be discoverable or usable. So I started to look into how I could redo this


API access to data

Very cool, the new architecture system we're using has a much better API than the last one. It gave us a RESTful api for all the CRUD1 actions you could desire. My experiments with other APIs and Go's inbuilt YAML/ JSON parsing made this very easy.

  1. Create a struct representation of the object you're interacting with
  2. Use http to interact with the endpoint
    • Optional: for SAML authentication, spin up a localhost server to auth against
  3. Use json.unmarshal to convert the response.Body into the JSON object.

I stuck all this in a server-interact.go file to keep all that together

Local object for processing

The object in the API is not necessarily in the best or most reasonable structure for exactly the use case you want. In my case I needed a series of object to represent Capabilities, Physical Applications, and Physical Technologies2. For each of those I wanted a Baseline state and a Target state. For each of those I had individual attributes for each component. For example, Capabilities have Maturities in different areas; but Applications have a business or technology fit rating.

  1. Create a struct representation of the object to use in the model
  2. Convert the marshalled JSON from above into the interaction object

Graphing via SVG

SVG, a great image manipulation format. It's text based so it can be meaningfully version controlled and understood. It works with Cartesian coordinates, so any high-school level mathematics can let you draw really interesting things.

  1. Process the interaction object, looping through the attributes
  2. For each, use MATHS to calculate relative positions and sizes of items
    • Use a function for drawing common components so you don't repeat yourself or repeat yourself
  3. Save the file as SVG.

This is working rather nicely so far. Next step for me is working on the roadmap itself.

  1. Create, Read, Update, Delete. The four cardinal directions of data. ↩︎

  2. Yup, this is TOGAF↩︎