DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Last call! Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Why Documentation Matters More Than You Think
  • Top 5 Software Architecture Books to Transform Your Career in 2025
  • 5 Signs You’ve Built a Secretly Bad Architecture (And How to Fix It)
  • Differences Between Software Design and Software Architecture

Trending

  • Contextual AI Integration for Agile Product Teams
  • Scaling DevOps With NGINX Caching: Reducing Latency and Backend Load
  • Optimizing Integration Workflows With Spark Structured Streaming and Cloud Services
  • Power BI Embedded Analytics — Part 2: Power BI Embedded Overview
  1. DZone
  2. Software Design and Architecture
  3. Microservices
  4. Software Architecture as Code

Software Architecture as Code

By 
Simon Brown user avatar
Simon Brown
·
Jun. 25, 14 · Interview
Likes (0)
Comment
Save
Tweet
Share
9.2K Views

Join the DZone community and get the full member experience.

Join For Free

if you've been following the blog, you will have seen a couple of posts recently about the alignment of software architecture and code. software architecture vs code talks about the typical gap between how we think about the software architecture vs the code that we write, while an architecturally-evident coding style shows an example of how to ensure that the code does reflect those architectural concepts. the basic summary of the story so far is that things get much easier to understand if your architectural ideas map simply and explicitly into the code.

regular readers will also know that i'm a big fan of using diagrams to visualise and communicate the architecture of a software system, and this "big picture" view of the world is often hard to see from the thousands of lines of code that make up our software systems. one of the things that i teach people during my sketching workshops is how to sketch out a software system using a small number of simple diagrams, each at very separate levels of abstraction. this is based upon my c4 model , which you can find an introduction to at simple sketches for diagramming your software architecture . the feedback from people using this model has been great, and many have a follow-up question of "what tooling would you recommend?". my answer has typically been "visio or omnigraffle", but it's obvious that there's an opportunity here.

representing the software architecture model in code

i've had a lot of different ideas over the past few months for how to create, what is essentially, a lightweight modelling tool and for some reason, all of these ideas came together last week while i was at the goto amsterdam conference. i'm not sure why, but i had a number of conversations that inspired me in different ways, so i skipped one of the talks to throw some code together and test out some ideas. this is basically what i came up with...

model model = new model();
 
softwaresystem techtribes = model.addsoftwaresystem(location.internal, "techtribes.je", "techtribes.je is the only way to keep up to date with the it, tech and digital sector in jersey and guernsey, channel islands");
 
person anonymoususer = model.addperson(location.external, "anonymous user", "anybody on the web.");
person aggregateduser = model.addperson(location.external, "aggregated user", "a user or business with content that is aggregated into the website.");
person adminuser = model.addperson(location.external, "administration user", "a system administration user.");
 
anonymoususer.uses(techtribes, "view people, tribes (businesses, communities and interest groups), content, events, jobs, etc from the local tech, digital and it sector.");
aggregateduser.uses(techtribes, "manage user profile and tribe membership.");
adminuser.uses(techtribes, "add people, add tribes and manage tribe membership.");
 
softwaresystem twitter = model.addsoftwaresystem(location.external, "twitter", "twitter.com");
techtribes.uses(twitter, "gets profile information and tweets from.");
 
softwaresystem github = model.addsoftwaresystem(location.external, "github", "github.com");
techtribes.uses(github, "gets information about public code repositories from.");
 
softwaresystem blogs = model.addsoftwaresystem(location.external, "blogs", "rss and atom feeds");
techtribes.uses(blogs, "gets content using rss and atom feeds from.");
 
container webapplication = techtribes.addcontainer("web application", "allows users to view people, tribes, content, events, jobs, etc from the local tech, digital and it sector.", "apache tomcat 7.x");
container contentupdater = techtribes.addcontainer("content updater", "updates profiles, tweets, github repos and content on a scheduled basis.", "standalone java 7 application");
container relationaldatabase = techtribes.addcontainer("relational database", "stores people, tribes, tribe membership, talks, events, jobs, badges, github repos, etc.", "mysql 5.5.x");
container nosqlstore = techtribes.addcontainer("nosql data store", "stores content from rss/atom feeds (blog posts) and tweets.", "mongodb 2.2.x");
container filesystem = techtribes.addcontainer("file system", "stores search indexes.", null);
 
anonymoususer.uses(webapplication, "view people, tribes (businesses, communities and interest groups), content, events, jobs, etc from the local tech, digital and it sector.");
authenticateduser.uses(webapplication, "manage user profile and tribe membership.");
adminuser.uses(webapplication, "add people, add tribes and manage tribe membership.");
 
webapplication.uses(relationaldatabase, "reads from and writes data to");
webapplication.uses(nosqlstore, "reads from");
webapplication.uses(filesystem, "reads from");
 
contentupdater.uses(relationaldatabase, "reads from and writes data to");
contentupdater.uses(nosqlstore, "reads from and writes data to");
contentupdater.uses(filesystem, "writes to");
contentupdater.uses(twitter, "gets profile information and tweets from.");
contentupdater.uses(github, "gets information about public code repositories from.");
contentupdater.uses(blogs, "gets content using rss and atom feeds from.");

it's a description of the context and container levels of my c4 model for the techtribes.je system. hopefully it doesn't need too much explanation if you're familiar with the model, although there are some ways in which the code can be made simpler and more fluent. since this is code though, we can easily constrain the model and version it. this approach works well for the high-level architectural concepts because there are very few of them, plus it's hard to extract this information from the code. but i don't want to start crafting up a large amount of code to describe the components that reside in each container, particularly as there are potentially lots of them and i'm unsure of the exact relationships between them.

scanning the codebase for components

if your code does reflect your architecture (i.e. you're using an architecturally-evident coding style), the obvious solution is to just scan the codebase for those components, and use those to automatically populate the model. how do we signify what a "component" is? in java, we can use annotations...

package je.techtribes.component.tweet;

import com.structurizr.annotation.component;
...

@component(description = "provides access to tweets.")
public interface tweetcomponent {

  /**
   * gets the most recent tweets by page number.
   */
  list<tweet> getrecenttweets(int page, int pagesize);

  ...
  
}

identifying those components is then a matter of scanning the source or the compiled bytecode. i've played around with this idea on and off for a few months, using a combination of java annotations along with annotation processors and libraries including scannotation, javassist and jdepend. the reflections library on google code makes this easy to do, and now i have simple java program that looks for my component annotation on classes in the classpath and automatically adds those to the model. as for the dependencies between components, again this is fairly straightforward to do with reflections. i have a bunch of other annotations too, for example to represent dependencies between a component and a container or software system, but the principle is still the same - the architecturally significant elements and their dependencies can mostly be embedded in the code.

creating some views

the model itself is useful, but ideally i want to look at that model from different angles, much like the diagrams that i teach people to draw when they attend my sketching workshop. after a little thought about what this means and what each view is constrained to show, i created a simple domain model to represent the context, container and component views...

model model = ...
softwaresystem techtribes = model.getsoftwaresystemwithname("techtribes.je");
container contentupdater = techtribes.getcontainerwithname("content updater");
 
// context view
contextview contextview = model.createcontextview(techtribes);
contextview.addallsoftwaresystems();
contextview.addallpeople();
 
// container view
containerview containerview = model.createcontainerview(techtribes);
containerview.addallsoftwaresystems();
containerview.addallpeople();
containerview.addallcontainers();
 
// component view for the content updater container
componentview componentview = model.createcomponentview(techtribes, contentupdater);
componentview.addallsoftwaresystems();
componentview.addallcontainers();
componentview.addallcomponents();
// let's exclude the logging component as it's used by everything
componentview.remove(contentupdater.getcomponentwithname("loggingcomponent"));
componentview.removeelementswithnorelationships();

again, this is all in code so it's quick to create, versionable and very customisable.

exporting the model

now that i have a model of my software system and a number of views that i'd like to see, i could do with drawing some pictures. i could create a diagramming tool in java that reads the model directly, but perhaps a better approach is to serialize the object model out to an external format so that other tools can use it. and that's what i did, courtesy of the jackson library . the resulting json file is over 600 lines long ( you can see it here ), but don't forget most of this has been generated automatically by java code scanning for components and their dependencies.

visualising the views

the last question is how to visualise the information contained in the model and there are a number of ways to do this. i'd really like somebody to build a google maps or prezi-style diagramming tool where you can pinch-zoom in and out to see different views of the model, but my ui skills leave something to be desired in that area. for the meantime, i've thrown together a simple diagramming tool using html 5, css and javascript that takes a json string and visualises the views contained within it. my vision here is to create a lightweight model visualisation tool rather than a visio clone where you have to draw everything yourself. i've deployed this app on pivotal web services and you can try it for yourself . you'll have to drag the boxes around to lay out the elements and it's not very pretty, but the concept works. the screenshot that follows shows the techtribes.je context diagram.

a screenshot of a simple context diagram

thoughts?

all of the c4 model java code is open source and sitting on github . this is only a few hours of work so far and there are no tests, so think of this as a prototype more than anything else at the moment. i really like the simplicity of capturing a software architecture model in code, and using an architecturally-evident coding style allows you to create large chunks of that model automatically. this also opens up the door to some other opportunities such automated build plugins, lightweight documentation tooling, etc. caveats apply with the applicability of this to all software systems, but i'm excited at the possibilities. thoughts?

Software architecture

Published at DZone with permission of Simon Brown, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Why Documentation Matters More Than You Think
  • Top 5 Software Architecture Books to Transform Your Career in 2025
  • 5 Signs You’ve Built a Secretly Bad Architecture (And How to Fix It)
  • Differences Between Software Design and Software Architecture

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!