How to evaluate a client's tech architecture

profile picture

Stijn Co-CTO

13 Jul 2017  ·  6 min read


Have you ever struggled with the best way to screen and visualise a customer's technical stack before starting a project? We share what's worked for us!

When you work on projects like ours with bigger clients, like telcos, utility providers and software companies, it’s crucial to know all about their technical stack before you dive into building the project. After all, you don’t want to run into mysterious problems or unexpected dependencies later…

In this post, we’ll walk you through our process for these technology or architecture assessments and the many benefits of doing it right!

What do you want to learn?

When performing tech assessments, we always have two main goals:

  • performing a reality check on the proposed concept
  • identifying any missing components or services that we need to build our concept.

Your mileage may very, but at November Five, this is a more-than-crucial step. When we create our concepts, we explicitly don’t tie ourselves to the constraints of today’s technology. We don’t promise the impossible, of course, but we’ve found that this allows for maximum creativity and the best ideas.

But this does mean that it’s not until the technical assessment that we really go deep into the technical setup, making all the more essential to do this right.

Now, experience has taught us that diving into a client’s technical architecture can be tricky. Two things can happen: ideally, the technical staff is completely on board and shares a tremendous amount of information with us – years and years of architecture, development and evolution. In the other scenario, the staff is (understandably) doubtful, even hesitant, to share their architecture with us – because this is the thing on which they have worked for months, years or even complete careers.

It’s important to assure everyone that we’re not there to challenge or criticise their work. However, this architecture will be the foundation of our product, and as such, we need to examine it.

The better we understand the ecosystem that we’ll be extending, the better the product will become.

When it comes to the actual learnings, we focus on the status of the services we need for our product, like CRM packages, streaming services, or completely new systems. They won’t usually all be present at the start of development and sometimes need to be created from scratch. A first step is to determine whether these missing parts should be acquired, customised, or developed by November Five or our client.

These decisions are mostly driven by operational responsibility.

  • If the new service needs to iterate with process changes managed by the client, the most logical choice is to have our client develop and maintain the service. That will make changes much easier to plan and implement.
  • If the service will change together with our product, it makes more sense for us to take charge of development.

Most of the time the best option will be somewhere in the middle, with both parties collaborating on the development.

How do you organise a technical assessment?

A thorough technical assessment is a pretty complicated beast. Gathering information is one thing, but representing it in a way that makes sense can be complicated. And truth be told, our first attempts were not always that well-organised, which is why we were looking for a better way.

Enter Simon Brown’s extremely useful C4 model. His view on creating several zoom levels of architecture resonated in the team and guided our conversations about a better methodology.

The basic premise of his model for architecture visualisations is straightforward: start by laying out the system as if you were explaining your project to your grandmother over a family dinner.

This gives you your Context View: in one fell swoop, you have now defined which parts you own and which you don’t. You quickly define which actors can work on or use your system.

Context View

This can already be a pretty big challenge, if your day-to-day job is managing dozens of these interconnected services.

Next you zoom in on the central node. This is what Simon refers to as the container view. These are course grained subsystems like the CMS, frontend/native applications, billing systems, backoffice systems, CRM systems, etc.

Containers

When you’re creating this diagram, it is important to know how information flows through the system. To help our clients help us, we ask them to think about the customer lifecycle. The way each of the actors travels through his or her lifecycle will define the order in which we start drawing and annotating arrows.

We’ve found that with this approach, we get 80% of the system’s use cases properly described – which is what really matters in the initial assessment.

The edge cases and exotic use cases can be defined and evaluated properly at a later stage.

Simon Brown’s model recognises two more C levels, the components level and the class diagram, but usually, those are only discussed once we’re in the actual development phase.

What tools do you use?

Like most of November Five’s processes, we prefer to keep things lightweight and practical. The diagrams are built and maintained in LucidChart, while the information recorded in the conversation is stored in the product’s dedicated Confluence space.

We’ve also created a number of templates to use in these conversations. This ensures that our information (and the conversation in itself) is always structured and consistent across our projects.

Template

In these templates we tackle a number of default topics.

  • The SPOC, our contact for the entire discussion.
  • An overview of the products that are used, the business processes in which they manifests, and the way we connect, authenticate and authorise the system. It also clarifies which actors can actually talk to this system (authenticated and anonymous users, call center employees, back-office employees, bots or other services, …).
  • A connection test.
  • The exact maintenance windows of every system that our product depends on.
  • A detailed roadmap. Systems change, are updated or replaced by other systems, and we need to avoid situations where we discover someone’s migrated a key depency… a week before we’re going live.
  • Meeting notes for later reference.
  • Attachments, like API documentation, Word documents, PDFs, Visio files, Powerpoints, etc.

Who’s involved?

Logically, the two high-level diagrams we described earlier can only be drawn up by a client’s CTO or Architect. However, these people tend to have very busy schedules!

We’ve found that having them appoint a SPOC withing their company drastically reduces the time that we need with the CTOs or Architects. It shares the workload across a larger team, and our main stakeholders don’t end up becoming bottlenecks.

In short, this is the schedule we impose during the assessment:

  1. Architect / CTO creates the Context & Container View
  2. Architect / CTO appoints SPOCs
  3. Each SPOC defines the Container View for the component (s)he is responsible for, during a 1,5h long session with us
  4. November Five organises a presentation and alignment session (with all above) to validate our conclusions.

Signed, sealed, still improving

Of course, we’re constantly improving this workflow, and fine-tuning it as we take on new projects. However, we feel we’ve reached a solid basis to work from – give it a try and let us know if it’s worked for you!

Or, of course, you can come right to the source: we’re still looking for project managers!