Table of Contents

1. Introduction
2. How did we get here?
3. Looking back to look ahead
4. Building a good scenario visualiser (the data interactive tools bit)
5. Understanding your options

It’s a tricky time to be a borrower, with many of us facing lots of uncertainty around current markets, making it difficult to know what the future holds for our mortgage payments. Interest rates are on the rise, and naturally so are the concerns of many homeowners.

Government policy can have a big impact on mortgage payments, both in the short and long term. It’s important to understand how these policies can affect you, so you can make the best decisions for your financial future.

In this article, we’ll explore the current landscape of mortgage rates, what’s driving the increases, and how to leverage a data analysis and visualisation tool like Streamlit to understand how to best navigate the tricky economic climate we’re currently in.

How did we get here?

The last few months mark a clear upward trend in mortgage rates. We’re now firmly exiting a sustained period of historically low interest rates set by governments and central banks, after an unprecedented amount of quantitative easing measures (policies designed to encourage growth) post the 2008 housing crisis, and most lately through the global pandemic.

The end of the sub 2% mortgage rate era

Higher base rates as set by the central bank leads to higher interest rates on mortgages and other lending products across the country. The recent hike in base rate was the Bank of England’s response to an increase in living costs, primarily driven by a surge in energy prices.

A quick recap on inflation

Inflation is the sustained increase in the general price level of goods and services in an economy. This means that the purchasing power of a unit of currency falls and, as a result, inflation essentially erodes the value of money. Rising inflation in the U.K. is a complex topic but can be partially attributed to a wide mixture of factors including rising import prices, an intense winter period placing pressure on our energy supply chains, and of course, socio economic uncertainty due to events such as Brexit, the ongoing war in Ukraine, and the global pandemic.

In an attempt to keep inflation in check, the Bank of England has raised rates seven times since December 2021, most recently in September to 2.25%, the highest level in 14 years.

The aim of these measures is to lower inflation to a Monetary Policy Committee recommended target of 2% (as opposed to the currently much higher value of around 9–10%), although the raise in the base rate also means that households are likely to see their real incomes squeezed in the short to medium term. Increasing the base rate and consequently borrowing costs incentivises consumers to save rather than spend, as incomes get squeezed and we become more mindful of future financial commitments.

The Bank of England’s decision to increase the base rate may help to curb inflation in the short-term by lowering demand for goods and services, therefore lowering prices. However, it remains to be seen how effective this will be in the long-term and what impact it will have on the economy overall.

Impact on mortgage lending

With concerns mounting around further interest rate rises and in the face of increasing market uncertainty, most consumer lenders will take measures to adjust their pricing to account for increased costs of borrowing, adjust their affordability assessments to account for inflation (and also potentially reduced house prices), and revise their risk assessments in accordance with heightened market volatility. Some major mortgage lenders have even gone to the length of temporarily halting their mortgage products altogether in an attempt to maintain a strong position on risk aversion.

This means that, for many people looking to buy a home or remortgage, the process has become more expensive and more difficult. It’s not all bad, though. If you’re currently on a fixed rate mortgage, your repayments are unlikely to change until this rate expires. And if you’re looking to remortgage, there are still plenty of deals out there to be had — you just might have to shop around a bit more to find one that suits your needs and to set your expectations that the you’re now more likely to start paying a higher price.

Looking back to look ahead

The base rate may not mean much to most people, but it’s a big deal for those with mortgages. And right now, the markets are predicting that the base rate could rise to nearly 6% by next spring.

In order to know what to expect if you’re due to remortgage in the next few years or to purchase your first home in a similar time span, it’s useful to look at the wider historical context of the base rate and the various factors that impact it.

Historically speaking, base rate increases and decreases tend to closely follow inflation as the base rate is the main instrument of monetary policy. So when inflation rises sharply, the base rate is likely to rise also.

Given what we know about the current levels of inflation, energy prices as an underlying contributing factor, and how current levelling compares to historic levels — it’s reasonable to assume that we’ll continue to see levels of inflation above the 2% target well into next year and we should probably expect to see further base rate hikes until inflation levels eventually start to decrease and normalise.

So, what does this mean for those that locked in fixed rate mortgages during the period of historically low base rates? How much can you expect to pay when the initial rate on your mortgage expires and it’s time to remortgage? Trying to do a good job of answering these questions can get pretty difficult, and it’d be great to get some help to allow us to easily understand and visualise the potential scenarios ahead.

Building a good scenario visualiser

Before we build our tool, let’s get a clear idea of what insight we’re trying to gain and what assumptions we’re willing to make.

Key insights we’re looking to get

• Assuming, I’ve currently got a mortgage and I’m on a fixed rate for a set term. What will my monthly debt repayment schedule look like? How about annually or over the lifespan of my mortgage?
• What am I paying now and what am I likely to pay when I remortgage? and how will that change depending on what’s happening with the economy?
• How do some of these different options compare?

Carefully thinking about how we visualise our data

There’s something special about a hand-drawn diagram or graph. It’s a reflection of the thinker’s mind, a trace of their thought process as they worked through a problem. It’s a snapshot of a moment in time, of a particular way of seeing the world.

Most modern visualisations are generated by computers, using a single description to create a static picture for any dataset. This has its advantages — it’s efficient, and can be tailored to the specific needs of the viewer.

The power of interactive data visualisation lies in its ability to give us flexibility in how we capture the essence of a problem, and the way we think about it.

A key difference in creating interactive data visualisations as opposed to static ones (for a static example, think of a graph you produce in excel, which you then display as an image in a presentation), is that it enables for rapid feedback in the data exploration process. This dexterity is what makes it such a powerful tool for understanding complex problems as it allows us to quickly see the data in different ways, and to find patterns in information that might otherwise be hidden.

Putting things in practice: Building an interactive data visualisation interface with Streamlit

To build a simple dynamic visualiser we’ll start by thinking of our inputs (control variables) and the outputs (charts, graphs, tables etc)

What are the scenario control parameters?

• Properties of your current mortgage
• Properties of your mortgage deal when you’re next due to remortgage

What are the calculated outcomes?

• Amortisation (mortgage repayment) schedule
• Monthly and lifetime costs
• Comparative cost analysis

Streamlit is a really powerful Python utility that makes it easy to create dynamic, custom data apps in just a few minutes. Using this library we can construct our control panel in just a few lines of code!

Next, we’ll use this package, in a combination with a few others to calculate and visualise our key insights. There are a few more pieces needed to complete our interactive data puzzle and properly connect our control panel to the visualised outputs.

A few of the Python packages leveraged to help us make the right calculations:

• We use the NumPy financial python library in order to calculate interest payments and monthly payments in a few lines of code.
• We use the Pandas python library in order to allow us to manipulate and represent tabular data such as the repayment schedule (Think excel but in code).

Putting it all together

The finished product allows us to leverage an interactive way to analyse and compare how your mortgage future might pan out depending on a few key assumptions.

You can use a demo version of this app here, to try and see how different scenarios may impact your individual circumstances.

Money Saving Expert states that, for each 1 percentage point your mortgage rate increases, you should expect to pay roughly £50 more a month (£600/year) per £100,000 of mortgage debt. We can use our app to validate this case using some friendly numbers for illustration.

Assuming,

• Your current mortgage loan value is £100,000
• You’re currently paying 1% in interest rate charges
• You remortgage at the end of your initial term with a rate of 2%
• With a new loan term of 24 years

Our tools tells us that we can expect our monthly payments to increase by around £42 per month, and around £89 per month when we increase the rate again to 3%.

We can also use our tool to see how the cumulative repayments look over the course of the loan’s full term (using a few assumptions around rate consistency and the type of mortgage you’re on). You can see the impact on how much interest you’re paying by the jump in the light blue line below around the end of the initial term, when the rate increases.

Understanding your options

The current situation is unprecedented, and it is impossible to know for certain what the future holds. However, there are some things that we can do to protect ourselves from the worst of the inflationary pressure. For example, switching to a cheaper mortgage deal at the right time and overpaying when we can are two options that can potentially help to ease the financial burden.

All in all, one of the things that has become clear is that our ability to make quick and smart data driven decisions will become even more key to modern economies as we face periods of high uncertainty and growing rates of inflation. To that end, understanding our data and how it can help us make informed decisions about our financial future is more important than ever.

Using interactive data tools to get a better understanding of how monetary policy may impact your… was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

As a Platform Engineer at Koodoo, one of the many challenges my colleagues and I face is management of secrets, ensuring that they are protected and that only the right people and applications are able to access them. We have been somewhat fortunate that in the early days of Koodoo we adopted Kubernetes which has its own secret storage configuration objects, however this does also present its own challenges. On top of the challenges presented in Kubernetes we also have to address the challenges of “single source of truth”, secret life cycles and access management, all of which become very difficult when there are multiple systems outside of Kubernetes also relying on secrets.

Challenges with Kubernetes Secrets

To write secrets to Kubernetes, it will require either a manifest to be written with the secret values base64 encoded (NOT ENCRYPTED!) or for a raw kubectl command to be called to write a secret from stdin.

The temptation to write the secret manifest to a Github repository is high, especially so that it is included in our pipelines. However, this could end very badly given the fairly open and distributed nature of the setup of our Github Organisation for our team. On the other hand, writing a secret using a kubectl command means one or more individuals are responsible for ensuring that secret exists and is backed up somewhere should it need to be re-created. This is a mess either way because we could very easily lose control of who has access to secrets, particularly when restricting access to secrets in-line with our Joiners/Movers/Leavers procedures. Also equally messy is knowing which version of the secret is the right one, knowing where the secret is ultimately stored outside of the cluster, and where we need to go to change or delete the secret when requirements change.

Once the secrets are in Kubernetes, you need to configure RBAC to ensure only the right people and principals can access the secrets, however when you manage multiple clusters it can become harder to administer as you scale out.

You also have to take steps towards safely configuring the storage. Secrets by default are stored unencrypted in etcd (the cluster’s underlying data store). Normally this is resolved by enabling Encryption at Rest for secrets, a capability GKE makes available which is fine and since we are using GKE, this capability is available to us out of the box.

Another challenge is how to manage secrets that are shared between different environments and services. In an ideal world, every environment would be completely separate and isolated: dev, test and RC should have absolutely nothing in common in terms of resources or data storage. Different services and workloads should also be isolated, which in Kubernetes can be achieved by creating namespaces. In reality though, some of the 3rd party services we rely on means that complete isolation is not always possible. While we do always ensure separation between production and non-production workloads, dev, test, and RC might be required to share certain secrets. For example, to be able to connect to an email delivery service. That secret might also need to be shared between services, so needs to be available across multiple namespaces. Imagine a situation where our provider comes along and says “you’re using a v1 format authentication token, we’ve moved on to v2 and you need to update by the end of the month”. That update has to be done multiple times across multiple namespaces and clusters. Yes, toil can always be automated away and tied into some sort of automated process, but you often have to first experience the pain before you do anything to fix it, balancing the time to automate against the manual effort given your working day is stretched across dozens of workstreams.

Lastly, there is also a need to access secrets outside of our Kubernetes cluster, for example in our CI/CD pipelines in Github, or for developers to share secret keys for their Postman calls, argh! Nightmare, how do we access those from outside of the cluster?!

Enter Hashicorp Vault

After some consideration, it was decided that we needed to look at a solution that would allow us to avoid some of the headaches associated with the above challenges and give us new capabilities that have not got a convenient solution within Kubernetes. What we decided to implement was Hashicorp Vault which promises to Manage Secrets and Protect Sensitive Data.

Predominantly we were interested in the following key features in Vault that would potentially be advantageous to our platform:

1. Configuration management — all of this can be defined as Infrastructure as Code (IaC) using Terraform!
2. Identity-based Access — Not only can we authenticate and apply policies to users, authorising them to manage secrets, but we can do the same for applications and machines.
3. Kubernetes Integration — secrets can be securely injected into our applications across multiple clusters, all obtained from our single source of truth.
4. Secrets Management — we are able to centralise our secrets into one place and make them available to multiple applications, systems and environments.
5. Storage backends — there’s a lot of choice as to where to store our secrets data!
6. “Encryption as a Service” — our applications can pass data to Vault to be encrypted before it is stored in an event or database.
7. Automated PKI Infrastructure — we can reduce the manual steps to update certificates for inter-service communications, for example with monitoring.
8. Dynamic Secrets — credentials can be created on-demand rather than having to store static secrets that are manually managed. Dynamic secrets often can be configured with a time-to-live (TTL), ensuring that they expire when no longer needed.

Configuration Management

At Koodoo, the Platform Team’s number 1 tool for Infrastructure as Code is Terraform. Whenever we look for a new infrastructure solution we tend to favour those that can be defined in code using Terraform.

The perceived advantages of adopting IaC are reduced cost in terms of the number of people and amount of effort required to configure a solution. Speed and efficiency means that new requirements and configuration changes are often faster to deliver, particularly with the use of modular reusable code. IaC also reduces risk in that automation can avoid human error from manual reconfiguration, this particularly works well when you include testing in your pipelines, but also increases reliability and repeatability.

Identity-based Access and Kubernetes Integration

This was a big selling point for us in the Platform team, as we have many squads working on multiple services and engineers responsible for application development, infrastructure and data pipelines. There are secrets that we would want our application to be able to access, however we’d want to also restrict who within the organisation can access those secrets, who specifically can access secrets in production and before you know it we have a crazy matrix of authorisation that needs to be applied to multiple environments. There are secrets that only the developers should have access to and be responsible for managing (such as for authenticating with third-party integrations), as well as secrets that only the data team should see (such as data warehouse credentials). On top of all this, we need to consider production support team members who are the only individuals who can access secrets pertaining to the production environment.

With Vault we are able to perform identity brokering with our main identity service provider that our users rely on for their day-to-day activities. This means that when a new engineer joins our team, as part of their onboarding process they are added to specific groups and their group membership grants access to specific secret mounts in Vault.

In a similar way, we use Kubernetes to perform identity brokering for our applications. Kubernetes service accounts provide an identity for processes running in a pod, what we have found awesome about Vault is that we can authenticate a service against Kubernetes, then an application is able to have a policy applied to it based on the service account name and namespace. This means service A cannot access secrets for service B because it does not have the correct service account and/or namespace! All of this is made possible with the vault-agent-injector which is able to mount secret data into the pod.

Secrets Management

What can I say? It’s a lot easier now to update secrets because we only need to do it in one place — Vault. All of our environments connect to and pull secrets from our shared Vault, so we have immediately reduced our workload. Secrets are versioned, so if someone mucks up we can roll back to a previous version of the secret. In addition to this, we can now start to consolidate the secrets used for Github Actions and other 3rd-party cloud services using AppRoles as an authentication method.

Storage Backends

Vault can write its secrets storage to so many different types of backend. At Koodoo we host a lot of our infrastructure in GCP, so it made sense for us to leverage Google Cloud Storage buckets as a storage backend. We then keep the GCS bucket in sync with an Azure Storage Account container as part of our backup procedure. On top of this, we use GCP Cloud KMS to unseal Vault, so we have this rather cool situation where the data in Vault can only be accessed when it lives in a specific GCP Project. It’s like having a safe that you can only unlock with your key when you’re in a specific location.

That’s cool and all, but given that we use GCP heavily, why not just put secrets into Google Cloud Secret Manager? Surely everything discussed above is available with the solution provided in GCP? In the initial stages Secret Manager was considered and would provide a lot of the features we required, however as discussed below, Vault goes that little bit further with regards to what it can offer.

“Encryption-as-a-Service”

When handling PII you should always ensure the best security practices of encryption at rest and even more importantly encryption in transit. For this we use Vault’s Transit secrets engine, and this is personally one of my favourites!

At Koodoo our applications are event-driven so we use tools like Google Cloud’s Pub/Sub to move the data from the application into the data pipeline for processing and analytics. Ultimately, the data does go on a journey that even traverses cloud providers! Whilst we use TLS to encrypt communications from the browser, and all the way until we reach the end of the data pipeline, we also encrypt any private data before it starts its journey to its final destination. Typically such an operation would require asymmetric encryption (such as GnuPG), where the backend API of Koodoo’s platform would have the public key, meaning it could only encrypt data, and the end of the data pipeline would have the private key allowing for decryption of that data. To avoid this overhead of managing PGP keys, we have written policies in Vault that makes the transit secret engine behave a bit like asymmetric encryption whilst using AES256 encryption (which is symmetric). Our APIs (and some of our engineers) only have access to the encryption endpoint, so they can pass data to Vault and receive an encrypted response body. If the API were then to attempt to post to the decrypt endpoint, it will receive an authorization error. All along the data pipeline the PII data remains encrypted until it reaches the data warehouse at which point it is decrypted by a job prior to loading into the data warehouse where it is re-encrypted at rest.

Automated PKI Infrastructure

As mentioned previously in “Encryption-as-a-Service”, we use TLS for encrypting our inter-service communication as well as verifying the identity of the service. At the moment we still often use static certificates from well known and trusted Certificate Authorities (CAs), however updating these certificates can be a burden as they appear in multiple places within our infrastructure. Vault has a solution! Vault is able to act as a Certificate Authority and issue certificates to services within our infrastructure automatically, this is particularly effective in Kubernetes when using something like cert-manager. This works well for authenticating and encrypting all communication between services used for monitoring, for example such as Prometheus, Loki, etc., where we hope to issue short lived certificates dynamically as part of the process. Why short-lived certificates? This is because if a certificate is leaked, the potential damage is limited to the TTL of the certificate and reduces the need for managing long revocation lists.

Dynamic Secrets

As is the strategy for our PKI Infrastructure, any chance to use short-lived secrets is a bonus! Vault provides you with a KV store used for keeping static secrets, however with static secrets there is a requirement to keep on top of the management of updating and deleting secrets as they age. Dynamic secrets on the other hand are great for providing short-term access to services, such as credentials for a database or service accounts for Google Cloud. These can be issued to both users and to applications with a short TTL, so that if credentials were to leak they would only be valid for maybe an hour or so before being deleted. It’s a lot harder to hit a moving target!

Where next?

At the moment, it often feels like we are only scratching the surface of what Vault can do. New releases bring some new functionality which might even replace or enhance the features of another third-party service or application. As Koodoo develops its platform and ventures into new areas we re-assess the way we do things and if there’s a use case will increase our usage of Vault.

Secrets Management: why we love Hashicorp Vault! was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. What makes International Women’s Day special to you?

It’s so important to look at how far we’ve come but also how far we still have to go. I feel completely in awe of the women who paved the way for me to live my life as a gay woman working in technology, living safely, able to vote. I’m not sure I would ever have been as brave as those women to drive the change they did.

I feel an incredible responsibility, as a parent, colleague, friend and human to ensure I am able to do what I can to make the world a better place for all people, to ensure I keep my eyes & ears open to the challenges women still face today, all over the world.

In summary I think it’s so important to remember, to celebrate and to reflect on the work we still have ahead of us.

2. Have you faced any barriers in your career due to being a woman? If so, how did you overcome them?

In general terms I am super emotive. I’m a crier, it’s just who I am. For a long time I saw it as a sign of weakness or that I wouldn’t be taken seriously, because at times I wasn’t. I was told I shouldn’t wear my heart on my sleeve or that what I was saying wasn’t valuable because I was emotional, hormonal or on my period.

Well sometimes it’s true I’m hormonal, it’s what women have to deal with!

Now I see it as my super power, I’m so emotive because I have high emotional intelligence and I feel things, I care and I’m passionate. I’ve learnt to use this to my benefit in the same way you would with any other super power or strength you discover about yourself.

Have I stopped myself from crying? No, in fact I’ve just stopped hiding it and I talk about it. I’ll say if I think I’m going to and that they should still listen to what I’m saying. I’ll tell my team and I let them cry when they need to. Ultimately we all feel better, have better conversations and come out with better actions.

3. What is the most important message you want to send out to young women thinking about their careers?

• Be you

There is no value in forcing yourself to be someone you are not and you will be miserable.

• Be open

Have open dialogue with your colleagues, building strong working relationships is how we are able to have more challenging conversations and learn from each other.

• Don’t stay where you aren’t happy

Every job teaches us something about ourselves and what we want from a career and in a workplace, good or bad. Don’t stay in those environments that make you unhappy because you feel you have to. You don’t. No workplace is right for everyone and there is no shame in acknowledging somewhere isn’t right for you, find the places where you thrive and people who share your passions and values.

Challenge companies on their values when you interview, working somewhere that has values that align with your own personal values will create a much more harmonious environment for you to be fulfilled.

4. Is there anyone that inspires you?

So so so many people, I find so many things inspiring and maybe that’s because I’m a fan of the little things, the times people stand up for themselves in a meeting or out on the street. When I see women standing together and supporting each other, the little gestures we can all do that have an impact.

5. Why do you think diversity in the workplace is so important?

I think it’s important everywhere. It’s critical to learning, broadening our minds and being more empathic human beings. If we surround ourselves with people just like us we won’t ever consider different perspectives or in the case of work, how people might use or benefit from our products.

It’s been said before but a diverse workforce is far more representative of the world we live in and the people likely to engage with your products or services. As an employee it makes the world of work far more interesting, there is so much value in needing to articulate your view in a way others can understand, in a way your customers need to understand.

Personally I really enjoy exploring different perspectives and evolving the way I think about things.

6. What are you most proud of doing?

Gosh this is a tricky one, I think the times I’ve pushed myself out of my comfort zone. I have not always been confident in my abilities throughout my career, no only as a women in a male dominate environment but also being dyslexic I feared people would think me lazy, rushed or even stupid.

I’ve spent a long time gathering feedback and understanding where I have the greatest value to add to a business. I’m also really upfront about my dyslexia to get it out of the way, manage expectations but also be really upfront about who I am.

It took me a long time to be able to take the risks in life and career than I have done, in the end if was the fear of all the missed opportunities and adventures that drove me forward and now I remind myself of a quote I love “Fear is the thief of dreams” any time I feel the fear.

7. What did you dream of when you were little?

Well my family mocked me because as a kid I told everyone I wanted to be a butterfly when I grew up… In some ways that hasn’t changed I do like to visit people and hopefully bring some joy to them all!

Sport was my real passion and if anyone told me that I’d be doing what I am now 15 years ago I wouldn’t have thought it was possible. However sport provided me with so many skills I’ve brought to work, passion, leadership, understanding the needs of the team and of management, being able to bridge the gap between.

More than everything it gave me confidence, it surrounded me with lots of women; strong, passionate women, who taught me so much about who I wanted to be as a person and that’s who I try to be everyday.

#IWD2022 with Claire Lowry-Hubball was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

TL;DR

At build time our frontend application dynamically imports a tailwind config file and a style-overrides file based on the value of a “THEME” environment variable. This allows us to apply different styles to every single component in our UI, effectively creating a customisable application.

1) Introduction 💭

2) A Component’s World🌏

• 2.1 — Creating theme-able components 🌈
• 2.2 — Using custom CSS classes🖌
• 2.3 — Using default Tailwind CSS classes 🎨

3) Applying a theme to a site 🖥

• 3.1 — Injecting a theme prop ⚙️
• 3.2 — Applying a Tailwind configuration file 🏋️‍♀️

4) Conclusion 🔮

1 — Introduction

At Koodoo, we are building a mortgage distribution platform with the end goal to match people with mortgages that suit them, hassle free. To achieve our mission we want to make our applications available to the widest audience. A key element in our distribution strategy is to partner up with price-comparison websites such as The Times, Confused.com, and Nerdwallet and power their mortgage services.

This is a win-win: our partners can focus on what they are good at, which is gathering wide audiences onto their website and promote services via their own channels while we can focus on what we are good at — building applications to connect people with mortgages. A key element to a successful integration with a partner is styling: to be attractive we need to provide applications that integrate seamlessly with our partner’s website and brand theme.

To achieve this, we develop “white label” applications. This means that when you visit any of our partners websites, you will have access to a seamless mortgage journey designed and developed by Koodoo but each have their own unique theming and content. This approach comes with additional complexity with regards to hosting, journey design (content customization) and styling but the benefits are enormous, we can focus our development efforts on a single code base and avoid the risk of divergence that would come from maintaining multiple applications.

In this article we will focus on the styling challenges and answer the question: How do we approach styling for white label applications. Let’s dive in! 🐇

2) A Component’s World 🌍

Modern web applications often use frameworks that promote UI componentization. At Koodoo, we typically use Next.js and Tailwind CSS as our frontend frameworks which means that our UIs are made of components.

We can define a “theme” as simply being a group of CSS rules which when put together represents the identity and the brand image of one of our partner. Theming is style customisation, so it is tightly coupled with how our components are written and styled. The first step in creating a customisable UI is creating theme-able components.

As we maintain multiple “white-label” applications across different teams we have our own React component library, that provides our applications with theme-able components.

Note: Having a component library is not necessary to achieve theming for white label applications, (we could also have all our components in the same code repository as our application), it just happens that as we develop multiple white label applications, having our own component library in a separate repository avoids duplications and facilitates maintainability in the long run.

2.1) Creating theme-able components 🧩 🌍

The code snippet below is for a <Button /> component and shows how our components are written to be theme-able. If we overlook the imports and the propTypes definition, our component is a simple function which does 3 things:

1. Defines three string variables (primaryClasses, secondaryClasses and criticalClasses) holding CSS utility classes. Each of these strings define a design variant ( “primary”, “secondary” and “critical” respectively).
2. Defines one attributes object which can contain any of the classes defined above.
3. Returns a JSX expression: <Component > which receives each of these classes defined as a value for its className property.

Enabling design variants

This component can be rendered under different design variants depending on the “primary”, “secondary” and “critical” props it receives.

Our button component also supports “small” and “base” design variants, but I removed them from the code snippet for simplicity.

⚠️ Design Variants of a component are different from the Theme: each of these <Button /> design variants should be available under a given theme:

2.2) Using custom CSS utility classes 🎨

To make components theme-able, we use custom css utility classes which are defined differently in different tailwind config files.

To see how this works we will focus on the theme-able “primary” button:

If we zoom on the primaryClasses definition, We have styles defined for each state our <Button /> can be in (default, hover, focus-visible and pressed).

Zooming in further on the 3 utility classes used for the primary <Button/> in a “default” state, we see that these utility classes simply apply the following styles:

1. background-colour
2. box-shadow
3. text-colour

If you are familiar with Tailwind, you would have noticed that these 3 utility classes are not the default tailwind utility classes, and you are right my friend ! 😉 Indeed, we are leveraging tailwind extendibility to extend it with our custom classes on top of the default classes Tailwind offers out of the box. This works particularly well for custom values such as “colour palettes” aka our own theme.

In our component library repository we define a tailwind.config.jsfile where we “tell” tailwind what each utility class (i.e. ‘bg-buttons/primary/fill/default’ etc.. ) should mean, and they each have a different meaning for each theme: one class multiple flavours 🍦.

Thanks to this file we are able to use the notation bg-[customColorClass] , text-[customColorClass]and shadow-[customBoxShadowClass]to apply each style defined in the tailwind.config.jsfile to the component. Then at build time, Tailwind generates the CSS file containing the styles defined in this tailwind.config.js file. So when our component renders, the browser will match the .bg-buttons/primary/fill/defaultclass with the CSS rule {background-color:#495ce9;} and render the following <Button />:

For another theme, we have another tailwind.config.js where the same custom classes are pointing to different values:

My primary button under the theme3 has a different background colour and text colour:

Each time we want to support an additional theme, we just need to add a new tailwind.config.jsfile for that theme.

💡 We have one component, using the same className value under each theme but we simply “pair” it with a different theme file (at build time) in order to render the <Button/> under the theme we want: one class, multiple flavours! 🍻

2.3) Utilizing default Tailwind CSS classes

There are scenarios where we actually want to use the default utility classes that Tailwind offers out of the box. Imagine you have a <Button /> component (hello again 👋 😁) that you would like to render with let’s say different border-radius between two themes. My theme1 <Button /> should have slightly rounded corners and I want my theme2 <Button /> to be rounder and maybe be uppercased and bold:

You wouldn’t want to have to write a custom class for each border radius and font weight the buttons should have under each theme. Some styles such as border-radius, font-weight, text-transform are so common that most websites only use a small variation of values these properties can have. Tailwind already comes equipped with the default classes to support these properties:

• Text Transform - Tailwind CSS
• Font Weight - Tailwind CSS

Instead of passing custom classes taking different meanings for each theme, we would like to simply inject different already defined classes for each theme that my <Button/> component should support.

Let’s take a look at the code again:

Notice that our <Button /> component can receive a theme property and whatever is held inside theme?.button will be applied to the Button className, effectively changing its style based on the theme props. 💡

🙋‍♂️ “ Excuse me“ …BUT, where is this prop coming from? does the application has to define a theme props and pass it into every single components it is using ? ? ? 🙀 🙀 🙀

The theme prop can still be defined in the theme files inside the component library so it can be maintained in one place an re-used in different frontend applications!

Let’s introduce some nuance: 💡 each of the themes we support is defined by not one but two files: one tailwind-config file (that we previously discussed) and one style-overrides file.

Let’s take a look at the style-overrides file for the theme1:

The same file for the theme2:

Multiple classes, multiple flavours 🌈 🍦🍦🍦

3) Applying a theme to a site:

So we have two files that fully define the style rules to achieve a specific “theme”:

• style-overrides.js which contains default Tailwind classes
• tailwind.config.js which contains custom utility classes

When we deploy a new instance of the front end application we specify the “theme” it should use as an environment variable and use dynamic import to require the appropriate files with a few dynamic imports:

💡 Using Next.js we can easily expose environment variables to the browser.

3.1) Injecting a theme prop

Based on the value of the NEXT_PUBLIC_THEME environment variable we can inject different `theme` objects inside our components at import time by wrapping each components we export from our component library with an injectTheme function.

The injectTheme function simply relies on dynamic import to apply the desired styleOverrides :

So every classes defined inside my theme1/style-overrides.js will be applied to my component via the “theme” prop effectively achieving conditional styling based on a “theme” required by the app.

3.2) Applying a Tailwind configuration file

We also have a “master” tailwind.config.js files in our frontend app which directly points out to the right config file defined in the component library:

When building the application, Tailwind will automatically generate the CSS files needed to apply the styles defined in the imported tailwind.config.js . The same custom class in our component will point to different styles.

Let’s visualize what has been said so far:

• Each theme folder contains one tailwind.config.js file and one style-overried.js file with classes name and classes value specific the the theme it defines.
• Our components are exported through one index.js file which injects a theme prop in each of our theme-able components.

1. We define a component once, in one place (can be in app or in external repo if the use case is justified for your needs). This component uses custom utility classes which are defined differently in different tailwind config files.
2. For each theme we have a tailwind.config.js which defines custom classes differently (one class which associated with different values achieve different styles)
3. For each theme we create a style-overrides.js which contains Tailwind default classes to be applied to our components (different classes achieving different styles).
4. We specify a theme value in our frontend application environment variables: NEXT_PUBLIC_THEME=theme1
5. At build time, our frontend application which is configured has tailwind installed will generate the appropriates styles based (defined in tailwind.config.js ) and inject the appropriate theme prop (defined in style-overrides.js) in the components it imports.

And voilà 🪄 🎩 🐇: 👏

The system is so flexible that we could have multiple application picking and choosing components and a theme from out component library:

4) Conclusion 🎬

Drawbacks ⚖️ :

• As you can imagine our theme files are way bigger than the small extract I have shared. Their length vary depending on how complex and specific the UI design is for a given theme but they are generally MASSIVE. Which means, the creation of a new theme to integrate with a new partner still requires intensive work driven by the Design team.
• Also the dynamic imports that the system is heavily based on and the way we integrate Tailwind with Next.JS means we have to re-build our application every time we want to switch between themes which adds an extra step in the release process.
• Currently, the complexity of the system and the size of theme files, are the biggest drawbacks we can honestly share: complex system means a lot of overhead for a new joiners to implement a new theme and lots of time spent implementing a new design (manual and error prone). Which can impact the speed at which we can integrate with new partners.

Advantages ✨:

• The system is incredibly flexible: we can achieve every single design requirements, style variations to meet the demands of our partners without having to develop a different application.
• It is predictable and reusable, the themes and components created are reusable across different Frontend apps and app instances, no matter how the application evolves.
• The main advantage of the current system, something that we often overlook in our quest for improvement: it works! We have a system that allows us to develop theme-able white label applications, yes there is room for improvements but currently this system powers every single Frontend app instances for each white-label app we develop. 👊

Future thoughts 🔮

🎬 As I write these lines, our Component Library is undergoing a massive update, we are moving away from JavaScript and Tailwind CSS in favour of TypeScript and Styled Components with Bit.dev as a library manager which will allow huge simplification of the current system, theming granularity at a component level and at runtime! Stay tune for more tech updates from Koodoo. 🤘

Let’s give back to Caesar what is Caesar’s: I am not the creator of the system presented here, merely the user and messenger. A massive thank you to all the people at Koodoo who contributed and are contributing to building great things.

I hope that sharing our experience as a development team will help you and your team succeed whatever your mission might be. 🚀 🌕

Take Care and Stay Awesome ✌️!

How do we approach theming for white-label applications? was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

It all started in Madrid, after finishing my undergraduate degree in Industrial Electronics and Automation Engineering, my first job was actually working as a Business Analyst. To be honest, I didn’t really have a career path in mind, and that was the first job offer I received. I didn’t really know much about it but I knew that I enjoyed maths and tackling problems by using analytical thinking, so I decided to give it a go. Fast forward a few months into the role, and I realised that I loved working with data: exploring it, designing tests to validate its veracity and looking for answers, trends and patterns. I also figured out that I prefer work of a more technical nature.

Serendipitously, around this time I discovered that there was a “Data Science” career path which combined Maths and Computer Science, and I realised that was exactly what I wanted to do. To pursue my goal, I enrolled into an MSc in Computer Science and Artificial Intelligence at the University of Nottingham.

Finding Koodoo

Toward the end of the program in 2019, I attended an inspiring talk that was being given by the former CTO of Koodoo, a Fintech start-up looking to transform the mortgage industry. I added him on LinkedIn and soon after this, he invited me to their office in Nottingham where I met the team. I really enjoyed the atmosphere and was excited at the prospect of working for such a driven, young tech company. The selection process was amazing, especially the last stage, which consisted of a two-day hackathon. Not only did I learn a lot, I also got to meet interesting people and had a lot of fun.

When I first joined the team, everyone was very welcoming and friendly. Being the first Data Scientist in the company was very challenging, but I had a lot of support from everybody. I was very excited to be part of a team with such skilled people that I could learn a lot from and were always willing to help. An exciting aspect of working at such a young company is that you feel your work matters and you’re able to see its impact in the company’s progress.

Hackathons and more

A very cool part of the Koodoo culture are the hackathons, in which we all work together on a challenge using tools and frameworks that aren’t part of the company’s day-to-day tech stack. In one very memorable challenge, we built a model to predict the probability of our mascot, Kenny the koodoo, surviving poacher attacks.

Aside from the hackathons, I really like that we are encouraged to learn new things in our daily work and look for new technologies that best suit the projects we are working on. At Koodoo we work hard but it’s not all just about that, we have fun too! We’ve done a lot of things together such as go-karting, spinning, yoga, bungee fit and recently an offsite in the countryside! Even during the lockdown we found exciting virtual activities, such as murder mystery, whiskey tasting or painting a ceramic Kenny.

What’s next?

I have been at the company for two years now and recently got promoted to Senior Data Scientist. To say the time has flown by would be an understatement. I’ve grown a lot, both personally and professionally and worked on very interesting and engaging projects, some of which I have gotten to see be applied in the real world, while others are still in development or at very early stages. I’m looking forward to growing and leading the Data Science team at Koodoo and can’t wait to see what lies ahead of this fast growing company of amazing Koodoods!

Growing with Koodoo: My Journey as a Data Scientist was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

Growing pains

One of the many challenges that this new level of scale brings us as a tech company, is retaining our ability to deliver at pace whilst extending the number of contexts, dimensions and channels the different teams within the company must operate on. Richard Hackman’s famous team communication diagram quite effectively displays how this manifests itself within growing teams by clearly surfacing the exponential growth of communication channels as numbers within an org increase.

This growth in complexity can be even more pronounced when coupled with a software delivery process that heavily relies on effective and clear communication happening between the right parties at the right time.

Breaking down the development workflow

One of the key requirements to creating an effective delivery process is having a thorough and clear understanding of how the team delivering the work are likely to structure their development. A combination of rich literature on well defined (and refined) design principles made available through various mediums, a good amount of proliferation in cloud services and an industry wide embrace for open source software has thankfully brought about some level of convergence in the components that together form a robust software delivery workflow.

• Structured change management and auditing capabilities

Software development teams need a convenient way which enables them to quickly and reliably see how the code has changed over time, in particular what changed and at what point. This is especially crucial for enabling reliable rollbacks if (when) things go wrong.

• Facilitating the generation of common code segments with internal modules, harnesses and templates

One of, if not, the only guaranteed strategy known for being effective when it comes to preventing software defects is to not writing any software at all. With libraries and frameworks being at the helm of most production apps, a lot of code nowadays is actually setup of boilerplate code or configuration. Creating easy to use code generating harnesses, using easily duplicated code templates or creating internal libraries to allow developers to not to have to worry about this at all are all common and well understood practices within software development teams.

• A Technical design and documentation process

A good way to measure the developer user experience of a software system itself is to judge how easy it is for a new member of the team to own and deliver a code change to production. The key differentiator here is almost always the levels and forms of up to date documentation covering the system and how to build against it.

• Continuous Integration and Continuous Deployments

Frequent releases should be the norm, which almost requires a high degree of automation for modern technology stacks due to the distributed nature of most newly built systems. Thankfully, CI/CD is now fairly common practice, with most technology service providers offering a range of tools, frameworks and integrations for your build technology and deployment methodology of choice.

• A robust peer review process

People often overstate the purpose of pull requests by focusing on approving, or declining and critiquing code changes and sure, that’s certainly a large part of the deal. But there’s also something about general team awareness of how the code is being developed and a familiarity in reading how the code is being constructed that even a passive contribution to a PR helps build and maintain across the team.

• A robust QA process

We come fully equipped with a test driven development process, automated testing, dedicated testing environments, user acceptance testing sessions with stakeholders and still we manage to release software with bugs. There is no right or wrong amount of testing, and it all depends on the specifics of your org, project and team but a QA process as a whole is basically a non-negotiable for most modern tech companies.

• Monitoring and Debugging tools

A common yet often fatal flaw I’ve observed in software teams is overly siloed team functions with a hard handover or “throw it over the fence” approach to delivery. Most commonly, you see this in the form of a development team producing code for a product feature to then have this sent to a testing team which hopefully passes some QA bar to then finally be deployed by a release team. What this often turns into is a complete lack of wider ownership and teams narrowly focusing on their individual functions causing issues to fall by the cracks that software bugs often love to creep into.

One of the ways to combat this is to allow system health and system monitoring to be a team wide activity, hopefully detached from hard deliverables as to allow this to be something any engineer is empowered to engage in.

• Integrations with task management and tracking tools

Save some of the video call exhaustion by allowing your stakeholders, project managers and anyone else who might be interested, to easily understand the status of the project and how it’s most likely to pan out going forward - instead of having another meeting.

• Unopinionated code formatting tools

Another time saver! This is isn’t so much about sticking to the “right” way to write and structure code but more about leveraging standardisation to allow developers to rapidly parse code that has a familiar structure.

Putting it all together using automation within GitHub’s toolset

GitHub have spent the last few years expanding their developer tools to nicely accommodate more and more of the software development process. This feels like a sensible direction given that so much of the developer workflow is entrenched in version control and the code itself which naturally sits quite nicely in GitHub’s favour!

Let’s breakdown a few of the key features to demonstrate how they can empower a realistic use case when assembled together with a few other powerful tools.

Our example use case: Building a web application with our 🔥 workflow

Let’s take the common example of a business who needs to create a simple user data capture form in the style of a single page web application.

A fictional company (Koo2 ©) needs to build an application, which their users can access and use to submit their details. This web application will present the user with a series of questions, to then capture the user’s submitted answers and then finally securely store this user’s information in some fashion for later usage.

• Breaking down and detailing the work via issues and using labels to keep things tidy 🕋

Issues are a great way to define and categorise granular tasks. Project managers and/or engineers can easily create formatted documents using markdown, categorise and label tasks with things like priority and complexity, assign ownership, raise discussion points and tie these tasks back to a wider set of deliverables via milestones and projects.

Labels are also great for detailed search, as you can essentially filter down task boards and progress trackers by any category that you choose to define.

• Organising the Project using GitHub’s automation tools to allow tasks to track themselves 🚀

This is where things start to get a bit more interesting. There are two key features about GitHub projects in particular that I really like.

1. Linking repositories to projects means they automatically get added to your progress board.
2. You can use project settings to allow these to automagically update the status of a task upon key events like pull requests being approved or branches being merged.

• Using Milestones to structure progress 📈

Milestones are a great way to “bundle” related tasks together to form broader deliverables and to track the progression rate of high level features.

Simply link the repository to the milestone and GitHub updates the status of the task in the milestone for you. 🤖

This gives us a really solid template to work from as the development team can now place their core focus on technical delivery by allowing their tools to facilitate project management and coordination with other team members.

• Using GitHub Actions to automate the build and release process 📦

In order to fulfil our ambitions of creating a complete developer workflow, we’ll need to bring in a few more tools and tricks to round out our build process. We’ll then use GitHub actions to string this all together.

Workflow components

1. Conventional commits to formally version code changes. This is a really useful tool which facilitates the use of predefined commit message conventions in order to better communicate expectations to potential contributing team members.
2. Jest to run unit tests
3. QAWolf to run automated UI tests
4. Submitting changes for peer review
5. Chromatic and Storybook to help the team review and visualise in-progress visual changes
6. Lighthouse in order to audit the app for performance, accessibility, progressive web app friendliness, and SEO suitability
7. ZAP Scan to ensure the app is keeping in line with OWASP
8. Release 🎉

Putting our workflow into action

Let’s start with the task of adding a telephone number question input to our Koo2 app.

Most development teams use some variation of a branch based workflow to manage multiple and frequent changes to the code base. A great way to ensure that you’re getting the most out of this is to use a tool like commitizen to help us structure each commit in this way without having to think too hard about it.

Once the code required to service our new telephone question screen has been added and corresponding unit or component tests have been written, the branch can be pushed up to the build server where we let our GitHub actions automatically kick in. Here’s exactly what’ll happen in sequence once we submit our pull request for peer review.

1. The project board automatically picks up the change and updates itself with the task status

2. Unit tests and automated tests are ran to check everything works as expected

3. Our UI components are rendered in Storybook to allow the team to visually review the changes and easily inspect what’s new at an interface level

4. A ZAP scan is executed to ensure no major security vulnerabilities are compromising our system

5. A lighthouse report is produced to ensure that our app is as performant and as accessible as possible. You also get a nice diff of how these latest changes impact the app’s lighthouse metrics.

It’s completely up to your team what the bar is but this should give you a rough flavour of what a set of criteria for a good workflow could look like.

The final piece of our workflow is to allow the team to review and approve/decline the changes and for the pull request to be merged. Once this is done, the project board will once again automatically update the status of this task as completed and slot it in the right column. 🏁

All of this — automated via GitHub action scripts and commonly provided jobs to allow you to quickly compose the right workflow for your project! 🙏

Here’s a (simplified) sample of what these actions can actually look like at a code level.

name: Run Security Scan

on: push

jobs:

  zap_scan:

    runs-on: ubuntu-latest

    name: Scan the webapplication

    steps:

      - name: ZAP Scan

      uses: zaproxy/action-full-scan@v0.2.0

      with:

      target: "https://uri.to.your.app/"

name: Deploy Story Book

on: push

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

       - uses: actions/checkout@v1

       - run: npm install

       - uses: chromaui/action@v1

name: Test and Build

on: push

jobs:

  test:

    runs-on: ubuntu-18.04

    steps:

      - uses: actions/checkout@v2

     - run: npm install && npm install -g @lhci/cli@0.5.x

     - name: Create production build

     run: npm run build

     - name: Run lighthouse audit

     run: lhci autorun

Using automation to power a next-gen development workflow was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

Intro: Starting from Monday 5th October, Koodoo’s product team ran a Google Ventures Design Sprint, focusing on a new product we’ve been looking to test and launch for a while, but haven’t had the bandwidth to give the time and effort that it deserves. It was our first ever Google Ventures Design Sprint, and we learned loads.

What’s a Google Ventures Design Sprint?

Great video, thanks Jake Knapp! If videos aren’t your thing, here’s a quick overview of the 5 day process and what it aims to achieve:

Tip 1: Expert interviewees don’t need to be members of your team/company

The problem area that we were addressing was one that our team was very familiar with, so we decided to look further abroad and ask if other people in the industry would help be our experts. That way we could validate or invalidate our assumptions, and hopefully learn something new. For example, we had:

• Head of Mortgages from a Top 10 UK lender
• Head of Mortgages Products and Pricing at a leading UK specialist lender
• Head of Product from a leading software provider to a large proportion of the UK mortgage market
• CEO from a leading open banking FinTech

Honestly, at first I was a bit sheepish about asking people if they’d be experts in our process. Fortunately, people love being asked for their expert opinion, and we only asked for 30 minutes each. We got great insights and thoughts from all of our experts, who were really happy to help.

Tip 2: In B2B companies, involving your business customers in the design sprint is incredibly powerful if you can manage it

We are a bit unique in that we work incredibly closely with all of our partners, to the point that they often view us as an extension of their own team. Nevertheless, some of our expert interviewers were actually customers, and some of our Friday user tests were also potential customers.

On reflection, it was the quickest consultative sales cycle we’ve ever done, starting with “understand your customers pain points and needs” on Monday, and ending with “present them with a prototype of a product that addresses them” by Friday, with a clear idea on whether they want to buy it or not.

Tip 3: Choose your sprint medium carefully, and in advance

Ok, this is more practical, but it’s an important one. My team pointed out that there were already some great remote design sprint templates out there that we could utilise, rather than trying to reinvent the wheel.

We used the ‘official’ template on Mural. (https://design-sprint.com/remote-design-sprint-template/) — which was awesome because it had the entire process, instructions and resources already set up for you, and the collaboration settings like timers, voting, and ‘following users’ were perfect for the design sprint. Arguably, it was easier to run remotely than in person!

Tip 4: Be realistic — allow for ‘business’ time with clear boundaries and breaks

As much as you’re meant to be 100% focused on the design sprint for a week between 10–5pm, when you’re a small product team in a scaling startup in the middle of two major launches, having a no-distraction week just isn’t possible.

We accepted this from the start, and carefully planned the design sprint around the commitments in the diary that we couldn’t miss. We also accepted that not everybody would be needed for every part of the design sprint, and the flexibility worked out pretty well, and we managed to deliver on our launch. Boy it was a tough week though.

Tip 5: The design sprint week is just the beginning — have a plan for how the outputs feed into your wider strategy

This is the most important one for me. Ask yourself: What’s next after the design sprint? How will we take the learnings and the outputs and progress them to the next stage of sales or development?

Rightly or wrongly, before we even started the design sprint, we had agreed to unveil a new product at an industry webinar a few weeks after the sprint. We just needed to work out what that product was and how it looked, which is what the design sprint was for.

Having a clear ‘next stage’ after the design sprint gave us even more focus, and was really helpful in deciding scope. When considering whether to include features in our prototype, we could make sensible decisions such as ‘we don’t need that as a feature to test our sprint hypotheses this week, but we’ll want to put that in the prototype before the big reveal in a few weeks’ time’.

In summary, a design sprint can be a powerful tool for a B2B business, providing you frame it correctly. Before you launch one, you’ll want to make sure that you:

• Have a clear vision for how the design sprint feeds into your wider product strategy
• Know who your business customers are and how you can involve them in the design sprint process (arguably this takes more planning and effort than the B2C flavour)
• Frame the output of the design sprint to customers as something that can be ‘bought’— as well as learning what works and what doesn’t, you’ll want to get that magical early product validation that it is something that your customers find valuable enough to pay for, before you spend precious time and money building it.

5 tips for running a remote Google Ventures Design Sprint for a B2B company was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is the second in a series of articles on why the use of formal specification languages — and specifically the language TLA+ — isn’t a completely mad idea for startups. In fact, I made the case in the first article that they could actually prove to be a match made in heaven.

You may agree or disagree with my claim at your own discretion. But I will plough on and start working through a problem using TLA+, and we’ll see if it helps or hinders.

Caveat emptor

Let’s clear one thing up from the start: I’m not going to attempt to teach you about the theory of TLA+ or how to use it. I’m also not going to make any further attempts to sell its merits to you, beyond what I wrote in the first article.

At the time of writing, I have learned what I consider to be the minimum amount necessary to roll my sleeves up and make a start. I have read Hillel Wayne’s book, Practical TLA+, I have worked through Leslie Lamport’s Video Tutorials, I have installed the relevant tools, and I have watched and read a few interesting blog posts and conference talks.

I have a background in Computer Science and a reasonable head for mathematics, but I think any logically-minded person could get to the same stage as I am currently at, with a little application.

From this point on, I’ll dive straight into describing the problem domain and attempting to model it in TLA+. I’ll talk you through my thought processes as I go along, and will add the occasional explainer for certain important constructs, but otherwise will assume you know what they mean.

The Elevator Pitch

Our problem domain will be elevator control software. Over on this side of the pond we call them lifts.

Why do I think this is an interesting problem to model?

1. Everyone reading this, with the possible exception of claustrophobes, will have used an elevator. Even the claustrophobes will understand the basics of how an elevator operates.
2. At its simplest, the control software for elevators should be pretty straightforward to model, so we can start with some easy but valid examples (e.g. 1 car, 2 storeys).
3. However, the problem gets exponentially more complex as you add more cars, more storeys and more safety features. This should allow us to validate that TLA+ is indeed capable of modelling these more complex scenarios without brain-melting amounts of extra effort.
4. They are a nice example of a finite state machine, which TLA+ is ostensibly good at modelling.
5. We can make suitable abstractions without compromising the usefulness of the solution. For example, we can model the logic about how calls to the elevator are received and serviced, without having to worry about the mechanics of how the elevator actually moves — gears, pulleys, power, door mechanisms, etc. We can reasonably assume that someone else has got all that covered.

Agreed? OK, let’s get stuck in.

The entry-level elevator

Leaving aside the simplest possible elevators, such as manually operated ones or stairlifts, the entry-level elevator that would benefit from control software would be one that:

• Has a single car
• Travels between just two floors/storeys (I’ll use the words interchangeably, sorry!)
• You can press a button from either floor to call the car (and even if it’s in use, it remembers your call request)
• Once inside the car, you just press a ‘go’ button and don’t have to select the destination floor
• Doesn’t have any pauses built into its behaviours (allowing passengers time to enter and exit)

We might visually represent it like this:

(American readers will be happy with the numbering above, but may not realise we Europeans call the storey at ground level the “ground floor” or simply “0”. I prefer the European convention, but we’ll go with the American convention for one simple reason: TLA+ sequences are 1-based!).

You might at this point wish to politely point out that elevators without doors are a little dangerous. But they wouldn’t be the first — I spent many a happy afternoon hopping on and off the paternoster elevator during my university years in Sheffield. For now, let’s accept it as a valid simplification.

Let’s make a start

Let’s start writing our TLA+ spec. We’ll start by trying to define our constants, variables and initial state. Let’s say the set of known Storeys is a subset of the set of Integers, with the car’s initial location being at an arbitrary storey.

We’ll prefix our state formulas and actions with EC for “Elevator Controller”.

CONSTANTS Storeys

VARIABLES carLocation

ASSUME Storeys \subseteq Int

ECInit == carLocation = CHOOSE s \in Storeys : TRUE

Remember that the CHOOSE operator indicates that an arbitrary value could be selected for carLocation from the set of available storeys. This is not the same thing as saying it WILL select one of those values or telling it HOW to select one— we are building a specification to check, not code to execute.

UPDATE: Following helpful feedback from the TLA+ community, it was pointed out that the use of the CHOOSE operator here could mask an error, as it may leave some states unexplored (it will fix the carLocation to an arbitrarily chosen value). Instead, we can simply use carLocation \in Storeys to explore all possible starting states.

Are we happy with that? Well, for one thing, it assumes the system is starting up with the car positioned at a storey and not between two storeys. Probably a reasonable assumption for the time being. Perhaps we should’ve called the carLocation variable carLastHaltedLocation, but let’s keep it simple for now!

What else can we assume about our starting state? We can assume something about the car’s movement. For now we will define the car’s potential movement states as “idle”, “going up” or “going down”, which we will represent numerically as 0 for idle, 1 for going up and -1 for going down.

The changed bits of the spec now look like this:

VARIABLES carLocation, carTravelStatus

ECInit ==
    /\ carLocation \in Storeys
    /\ carTravelStatus = 0

We can also assume something about the status of the two ‘call’ buttons on the walls and the ‘go’ button inside the car, namely that they are all in a ‘clear’ state.

VARIABLES carLocation, carTravelStatus, callRequest, goRequest

ECInit ==
    /\ carLocation \in Storeys
    /\ carTravelStatus = 0
    /\ callRequest = [s \in Storeys |-> 0]
    /\ goRequest = 0

I’m not going to explain every concept or construct as we go along, but this one, or a variant of it, is something you will see a lot of in TLA+ specs:

callRequest = [s \in Storeys |-> 0]

callRequest is here defined as a function where each value of set Storeys maps to the value of 0. As the set Storeys currently only contains the values 1 and 2 for our simple elevator, this might be written as follows: callRequest[1] = 0 and callRequest[2] = 0.

This is an example of a very elegant operator in TLA+, which enables you to describe something fairly complex about the properties of the system you are modelling without having to worry about how you might implement it in code.

What’s next?

We’ve defined a fairly rudimentary starting state. Now we will go about identifying some potential next states (known as “actions” in TLA+).

Car is called

The first ‘next state’ action we will describe is that the elevator is called from the other floor. Visually we could represent this as follows (a button is lit up after being pressed):

Here’s how we’ll write this in TLA+:

ECNextCall(s) ==
    /\ callRequest[s] = 0
    /\ callRequest' = [callRequest EXCEPT ![s] = 1]
    /\ UNCHANGED << carLocation, carTravelStatus, goRequest >>

Let’s break this down into plain English as best we can.

callRequests[s] = 0 means that, for the storey our elevator is being called from, the callRequest record has a ‘before’ value of 0 (i.e. it wasn’t already called).

callRequest’ = [callRequest EXCEPT ![s] = 1] means that the elevator hasn’t been called from any other storey, only s, so the value of the callRequest[s] will be 1.

The UNCHANGED line means that none of our other variables are modified.

So essentially what we have described here is that one possible next state is that a call request is made, turning the 0 to 1 in the relevant callRequest record, and nothing else changes in the process.

Service a call

Another ‘next state’ action we will describe is that the elevator proceeds to the storey from which it has been called:

In our specification, we now need to reflect the fact that the car is moving in this state:

ECNextServiceCall(s) ==
    /\ carLocation # s
    /\ carTravelStatus = 0 
    /\ carTravelStatus' = IF s > carLocation THEN 1 ELSE -1
    /\ UNCHANGED << callRequest, goRequest, carLocation >>

What does this mean?

carLocation # s means that the car’s current location is not the same as the storey it was called from.

The two conditions for carTravelStatus mean that the car was not already moving, and that it either goes up or down depending on whether the call came from the upper floor or the lower floor.

The UNCHANGED bit means that the callRequest remains in place, and carLocation remains unchanged, until the elevator gets there (and goRequest is also unaffected).

Car arrives after call

Our next potential action will describe the car arriving at the requested floor, as shown by:

We will specify this in TLA+ as:

ECNextArriveCall(s) =
    /\ carLocation # s
    /\ carTravelStatus # 0
    /\ callRequest[s] = 1
    /\ carLocation' = s
    /\ carTravelStatus' = 0
    /\ callRequest' = [callRequest EXCEPT ![s] = 0]
    /\ UNCHANGED << goRequest >>

Breaking this down:

carLocation before entering this state was NOT the storey being arrived at (s), but after entering this state it is.

carTravelStatus # 0 describes that the car was in motion, but upon arriving carTravelStatus’ = 0 means it then stops moving.

callRequest was 1 for the target storey before the car arrives, but becomes 0 after the car arrives; all other callRequest records remain unchanged.

Go request

So people can request the car from another storey, but passengers can’t yet tell it to go once they get in! So let’s visualise that:

We will specify this as follows:

ECNextGoRequest ==
    /\ goRequest = 0
    /\ carTravelStatus = 0
    /\ goRequest' = 1
    /\ carTravelStatus' = IF carLocation = 1 THEN 1 ELSE -1
    /\ UNCHANGED << carLocation, callRequest >>

So when the passenger hits the Go button, if it wasn’t pressed already, the car starts moving towards its destination.

Oh wait. There might be a flaw in this. Just by starting to write out the action formula, and identifying the preconditions (unprimed variables) and postconditions (primed variables) of the action, it made me realise something: what if I got in the car, and before I could hit the Go button, someone else on the other floor hit the Call button? Should I then be able to hit Go anyway and see it light up? I think I should.

The point here is not that we need to find the perfect solution right away, but the act of attempting to write the specification has forced me to think about edge cases or “non happy path” behaviours. It’s a perfectly valid behaviour for an elevator — and one that is no doubt happening all over the world right now as we speak — for the car to start moving towards another storey before the passenger has managed to select their preferred destination. TLA+ helps us to reason about these behaviours in a formal way.

For now, let’s split out the Go request from the servicing of the request:

ECNextGoRequest ==
    /\ goRequest = 0
    /\ goRequest' = 1
    /\ UNCHANGED << carTravelStatus, carLocation, callRequest >>

Translated, this now means the goRequest moves from a 0 to 1 when entering this state, and that’s it. We’re assuming nothing else about the location or travel status of the car, or any call requests made from the storeys.

Service the Go request

So now we can have an unfulfilled Go request, we need an action where that request is serviced — i.e. the elevator heads to its requested destination.

ECNextServiceGoRequest ==
    /\ goRequest = 1
    /\ carTravelStatus = 0
    /\ carTravelStatus' = IF carLocation = 1 THEN 1 ELSE -1
    /\ UNCHANGED << goRequest, carLocation, callRequest >>

That is: given a go request and a non-moving car, in this state the elevator will start moving up or down, depending on the current location.

Car arrives after Go request

Similar to the call request, we will specify the action where the car arrives after fulfilling its go request. Note that in this action and the previously described action, we did not specify (s) behind the action name. This is because it does not need to be parameterised for the storey — there’s only one go button, whereas there are n call buttons (where n=2 in our simple elevator system).

ECNextArriveGoRequest ==
    /\ carTravelStatus # 0
    /\ goRequest = 1
    /\ carLocation' = IF carLocation = 1 THEN 2 ELSE 1
    /\ carTravelStatus' = 0
    /\ goRequest' = 0
    /\ UNCHANGED << callRequest >>

As the elevator arrives from servicing a go request, the carLocation will flip from either storey 1 to storey 2, or vice versa.

The carTravelStatus will change from moving (not 0) to not moving (0).

The goRequest will be cancelled once the car arrives; callRequests remain unchanged.

Putting it all together

We’ve so far specified an elevator system that has one car, travelling between two storeys, which can be called by waiting passengers, will move to service such a call, and will cancel the call request once it has arrived.

If a passenger enters the elevator car and hits the Go button, the car will move to the other storey, and when it arrives, the ‘go’ request will be cancelled.

The full next-state formula

Given all the individual actions described above, our full next-state formula can be defined as follows:

ECNext ==
    \/ \E s \in Storeys :
        \/ ECNextCall(s)
        \/ ECNextServiceCall(s)
        \/ ECNextArriveCall(s)
    \/ ECNextGoRequest
    \/ ECNextServiceGoRequest
    \/ ECNextArriveGoRequest

vars == << carLocation, carTravelStatus, callRequest, goRequest >>
Spec == ECInit /\ [][ECNext]_vars

In case you weren’t already aware, the indentation in TLA+ is significant. The above means that our universal next state (ECNext) is a logical disjunction between the three possible actions parameterised by a storey identifier (elevator is called) and three possible actions without a storey identifier (elevator is asked to go by a passenger inside it).

The construct \E s \in Storeys : can be read as “there exists a value s in the set of all Storeys where…”. The TLC model checker will interpret this construct by attempting to fulfil the next state using any valid value from the set Storeys.

Invariants

We also want to describe in a formula all of the things that should remain true in all states of our system. We’ll start simple, as follows:

ECTypeOK ==
    /\ carLocation \in Storeys
    /\ carTravelStatus \in {-1, 0, 1}
    /\ callRequest \in [Storeys -> {0, 1}]
    /\ goRequest \in {0, 1}

The above is pretty uncontroversial. We’re checking that the car is always at a valid floor, that it’s always either stationary, going up or going down, that the callRequests are from the valid combination of call requests for our known floors, and that the Go request is either on or off.

These aren’t particularly taxing — we’ll have a go at making those a bit more meaningful later.

Does it work?

We’re ready to give our specification a spin. I won’t share the complete source code, as I think there’s more value in you putting it together yourself and understanding each bit at a time :)

Here’s how your model might look:

When we run this through the model checker, it works! We get 90 states and 32 distinct states. We have a working elevator!

What have we learned?

This was a pretty simple elevator, and only our first iteration.

But despite this, I think that just going through the process of identifying the different significant components of our system, and considering how that translates to variables and state changes (actions), helped me to conceptualise my system better.

We’ve made several important simplifications, such as not modelling doors, and keeping to one car and two storeys. By identifying those simplifications and attempting to codify them in a TLA+ specification, I feel I have a better understanding of the dimensions along which my system is going to get more complex.

Although I didn’t talk you through every step of my thought process, I found the construction of the next-state formulas (“actions”) to be particularly useful. In my first attempt, I started writing the ECNextGoRequest state formula with a behaviour in mind that as soon as the elevator passenger hit the Go button, it would set off for its destination. However, just by starting to write down the conditions of this action formula, I realised that there was a perfectly valid edge case behaviour I’d missed, and this led to the addition of the ECNextServiceGoRequest action.

The very act of trying to describe your system in unambiguous terms is itself a very thought-clarifying process. This is why many advocates of TLA+ consider the journey of formal system specification to be just as important as the destination.

There were other micro-decisions like this that I’ve not documented in this article which helped me conceptualise my system.

There were also decisions I’m not happy with yet: for example, the formulas for servicing/arriving for calls are very similar in nature to those for Go requests, and I wonder if I should refactor them... but then I am also aware that I’m not trying to write clean code here, I’m trying to model a system’s intended behaviours with as much clarity as possible. So the jury’s out on that one! I’m sure the dilemma will evolve as we add complexity to the system.

A couple of gotchas

There were a couple of things I noticed were wrong as I was writing my specification. Did you notice them too?

I’ll let you try to find them. If you spotted them straight away, then well done, you are clearly able to reason about multivariate state machines better than most! But even if you are feeling smug about that, I hope you can also see that spotting anomalous behaviours in a system will only get exponentially harder as we increase the complexity. After all, this is a really, really simple elevator!

If you didn’t spot them, sorry but I’m not going to reveal them yet. I want to see if the next iteration of our specification helps us to tease out these anomalies.

The model checker didn’t spot these gotchas because our model is currently very naive. Our invariant check formula only checks for things that really ought to be true unless something went badly wrong (e.g. we somehow managed to send our elevator to floor 3 even though we don’t have one).

It doesn’t check for more subtle behaviours that might result in our elevator behaving erratically or counterintuitively for the passengers. For these we need more sophisticated checks — and this is where the T in TLA+ comes in. We need temporal checks (i.e. things that we want to be true across an end-to-end behaviour, rather than true simply for all reachable states).

This will be the subject of the next blog post in this series.

TLA+ for startups (part 2) was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is the start of my personal and professional journey into the formal specification language TLA+. Before we dive into the details, I should probably begin by explaining my motivation for creating this series of articles.

Startup life: right thing, right time, done right

In my professional life, I build and run software development teams that create business systems using some of the latest technologies and methodologies. The systems we build are complex, but not Apollo programme or nuclear power plant complex. Thousands of lives may not depend on us writing robust, reliable and correct code; but if we write brittle, unreliable and faulty code, the company’s reputation will suffer, our clients’ reputation will suffer, and we will lose money.

The quality of the systems we build could make the difference between us winning in our chosen business domain and failing, badly. As I work in startups, marginal losses from poorly thought-out business strategies, poor tactical choices, or badly written code can take you very quickly indeed to the end of the road.

So there is a very real incentive in my world to create software systems that are right. Now there’s a funny word. That could mean a lot of different things to a lot of people. At one end of the spectrum, I could spend millions (somebody else’s millions, that is) creating a software solution that fully solves every significant problem in my company’s chosen business domain… only to find that there is no market appetite for 90% of what we’ve built, and as a result we will never come close to recovering the cost of the build.

Or I could create a super-lean, MVP solution to a very specific problem, promote it aggressively to gain traction in the market quickly… only to find that the shortcuts we made in getting there quickly come home to roost, while I watch a competitor coolly and calmly launch their product three months later that fixes all the shortcomings in our solution.

In short, the reason why startup life is a lot harder than it looks is that you generally have one shot at getting it right. And that means you have to build the right thing, and you have to build that thing right. Oh, and you have to do all that at exactly the right time.

Pragmatism is King

Common sense would have it that, to hit the sweetspot in the middle of the Venn diagram above, the startup tech lead has to be supremely pragmatic. If you think you can succeed in the startup world by overburdening your team with detailed processes, design frameworks and formal practices, you will have a very rude awakening. You have to be lean and mean; fast and furious. You have to be the gazelle to the corporate dinosaur; the speedboat to the corporate oil tanker.

Conventional wisdom would tell you that formal specification languages are wholly unsuited to startup life

If common sense tells you that you have to be fast, lean and supremely pragmatic, then conventional wisdom would also tell you that formal specification languages are wholly unsuited to startup life. It would probably be safe to assume that, on a continuum of the amount of effort invested in the design stage of software, most people would place formal specification languages way over on the right. Startups should be picking from somewhere near the left, and ought to be leaving formal specification languages to the superbrains designing missile targeting systems for fighter jets.

But is that true?

Luck be a lady tonight

Thinking about the Venn diagram and the continuum diagram together, we have a contradiction. On the one hand, we’ve identified that startups typically have one shot at getting it right (right thing, right time, done right). But on the other hand, conventional wisdom tells us that we need to do it with almost the lowest possible amount of investment in the design stage (also known as the thinking stage).

In other words, if we are to succeed, we’re going to need to get very, very lucky.

So what are you, our long-suffering startup tech lead, to do? Should you gradually and gently be moving rightwards on the continuum of pain? Maybe at first asking your team to sketch out their designs on a whiteboard before writing code? Then when that no longer feels fit for purpose, employ a BA to start writing something that at least looks a bit more thought-out? And then maybe 12 months later give one of your best developers an “architect” title and ask them to start drawing proper diagrams? You vaguely remember that formal specification module you did for a semester on your CS degree all those years ago, and you tell yourself that maybe you’ll find a use for it one day… but of course you’re not building software for controlling the coolers in nuclear reactors so… y’know.

While you are pondering your journey along the continuum of formal design, there’s a pretty decent chance that you have been distracted by some pretty major firefights in v1 of your solution; the lead developer you would’ve given the architect title didn’t turn up to work three weeks ago last Monday and you haven’t seen her since; the client you were counting on winning won’t sign the contract because they kept getting timeouts on your demo environment.

Perhaps all this could have been avoided if you had done a bit more design upfront, but hindsight is a wonderful thing, and frankly you didn’t have the time.

Before you know it, your startup dream is lying in tatters.

As I say, you’re going to need a lot of luck.

Thinking is underrated

That was a lot of preamble to bring me to the real point of this first article in the series ‘TLA+ for startups’.

I guess the title gives it away. I would like you to throw out your preconceptions about formal specification languages. Despite what you might think, they’re not just reserved for arcane computer science problems or hyper-critical systems.

Most importantly of all, TLA+ helps you THINK about the problem you are trying to solve

Although it builds on a rich history of formal specification theory and practice, TLA+ has been designed for solving real-world computing problems. But most importantly of all, TLA+ helps you THINK about the problem you are trying to solve.

It can be applied to a wide range of computing problems from simple algorithms through to large scale distributed architecture designs. It does not require years of training or a PhD to get started, just a grounding in some relatively straightforward mathematical concepts.

I believe that TLA+ enables software engineers and systems analysts, for the first time, to practically and formally reason about the code they are going to write before they write it.

The formally part I will leave to a later article, or indeed point you to some of the links sprinkled throughout this or later articles. Other people far smarter than me can explain why formal reasoning about systems using the universal language of mathematics is an incredibly powerful and useful thing to do.

The very act of attempting to describe the properties of some code you are planning to write is often enough to spark a new way of thinking about it

But practically, because despite what you might assume, it is definitely possible to get started with TLA+ quickly and start leveraging value from it right away. The very act of attempting to describe the properties of some code you are planning to write is often enough to spark a new way of thinking about it; to reveal a nuanced insight into the problem that you are trying to address; to tease out a logical flaw in your assumptions.

I often advise engineers on my teams to either sketch a design or write down in plain English the main tasks that they will need to complete before writing any code. The reason I suggest this is that doing so forces your brain to conceptualise the problem in a subtly different way, and the result will often be quite enlightening.

***In these two similar lectures (here and here), Leslie Lamport, inventor of TLA+, explains the importance of thinking above the code, and how TLA+ helps you to do that.***

Eating the elephant

You can start by using TLA+ or its alter-ego PlusCal to describe a small part of your system. Perhaps there is a short but non-trivial algorithm or logical flow in your system that you are pretty sure you can just go ahead and code, but you want to just validate your thinking on it before you do. Once you’ve got your head around the basic structures and semantics of TLA+, this would be a perfect candidate to get started on.

Importantly, you do not need to eat the whole elephant in one go. If your first use case for employing TLA+ in your design process is describing a high throughput, highly parallelised, distributed software architecture, you’re going to get your fingers burned. Or should I say you’re going to choke on a tusk.

Recalibrate your thinking

I would urge you to recalibrate your thinking about the role that formal specification languages can play in your design process. I would argue that TLA+ makes it possible for you to introduce some formality into your design process much, much earlier than before, and indeed I would recommend introducing it BEFORE considering other structured design practices such as UML.

I’m not arguing against using these practices — they can be extremely useful. I’m arguing for easing into the habit of formally describing the intended behaviours of your system so early on that it becomes second nature. It is something that you and your engineers and analysts can practically do before you need to consider more heavyweight, structured processes that will inevitably come as your company grows.

This series of articles attempts to make the case that TLA+ and startups are actually very happy bedfellows

In short, this series of articles attempts to make the case that TLA+ and startups are actually very happy bedfellows. It gives you a toolset by which you can improve your thinking and reduce your chances of making those critical design mistakes early on, with surprisingly low upfront investment. For the specific challenges that startups face, as discussed at the top of this article, that little bit of extra thinking, done in the right way, could be the difference between glory and ignominy.

*** In this video, Hillel Wayne (author of Practical TLA+ and the LearnTLA+ website), does a very good job of demystifying the core concepts of TLA+ and demonstrating how it can be used practically for smaller problem domains.***

What to expect

Now I’ve made the case for tech startups considering adding TLA+ into their armoury, in subsequent articles I will get practical. I’m going to build up an example of a real-world system that everyone can relate to, one that is simple to understand but a little more difficult to reason about. I’ll use TLA+ to help me do so.

I am definitely not an expert on TLA+, and might never be. Rather than just talking the talk, I am going to attempt to walk the walk of proving that TLA+ can be usefully employed at an early stage of system design thinking, with an appropriate amount of time investment for a small business, and can grow with you as your system matures.

I may fail in my quest. But hey, I work in startups, so I’m not scared of that as long as I’ve given it my best shot!

A few important links

Leslie Lamport’s official video course

Leslie Lamport’s TLA+ Hyperbook

Hillel Wayne’s Learn TLA+ website

The TLA+ Google Groups community

Leslie Lamport’s seminal work, Specifying Systems, also available in PDF format here

I’ll introduce more links as we go along, but these are, in my opinion, the building blocks upon which you should begin your TLA+ journey. Also buy Hillel Wayne’s excellent book.

Go to Part 2 >>

TLA+ for startups (part 1) was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.

<< Back to part 1

<< Back to part 2

PART 3: Getting the job

Before the interview

So you’ve started hitting some of those sweet career goals, you’re making a name for yourself in the tech community as a bit of a badass, you’ve crafted a killer CV, and you’ve got yourself that plum interview. Now what?

OK, so first of all do a bit of research about the interview. Find out what the interview structure is and in particular whether there will be a technical assessment and what sort of assessment. More on that shortly.

Do at least some basic research on the company. You don’t need to be able to reel off facts about profits and what their first office dog was called. But at least be able to describe in a sentence or two what they do and why you find that super interesting.

Find out who is interviewing you. Look them up and try to assess how technical they are from their online presence or previous jobs. Do not attempt to connect with them on LinkedIn.

Have a look at Glassdoor. It might give you some clues about the culture, but also there are sometimes reports about what the interview experience was like.

Prepare some answers to behavioural questions. These are the sorts of things where you are asked how you have handled yourself in certain situations. They’re straight out of the corporate interview playbook, and you can train yourself to answer them better. Find a list online somewhere, write down bullet points against each, and just memorise as many of the bullet points as you can. Get a friend to randomly ask you similar questions until you’re confident you’re remembering enough of the bullet points.

But the main thing to remember about these behavioural questions is not that there is a right and wrong answer. Instead, view them as an opportunity to sell some of your achievements or knowledge. If you’re asked some random question like “how do you deal with conflict”, don’t answer that in the abstract, “err I try not to raise my voice” or “I’m a black belt in krav maga”.

Instead, use it as an opportunity to say something like, “I was working in a team where we had a disagreement about using SQL Server or Mongo. I could see the pros and cons of each, but one guy was arguing loudly for Mongo, so I spent half an hour writing the pitch for SQL, and we presented our boss with both options”…. or something along those lines.

And here’s the thing: it doesn’t even matter if you’ve used a bit of poetic licence. That exact scenario may never have happened in the way you describe it. As an interviewer, I don’t care. I’ve asked a question, you’ve engaged with it, you’ve managed to bring a technical angle into it, we may get to talk about that technical subject later, and I’ve learned that you understand the importance of not bringing a knife to a fist fight. Everyone is happy.

Some other prep you should do. Read your own CV carefully before you go in. Partly to remind yourself how awesome you are, and partly to remind yourself what you’ve said. I’ve lost count of the times I’ve asked someone in an interview about something they’ve claimed to be an expert in on their CV, only for them to tell me that they’ve not really used it. Those interviews didn’t last very long.

OK, listen carefully to the next three pieces of advice.

In preparation for the interview, write down the key projects that you have worked on in the last couple of years. Then write down what your contribution was that made it a success, and write down what you learned from that project.

You may think it’s pointless writing this down because it’s all in your head and you won’t forget. Well in fact, the act of writing something down accesses a different part of your brain and forces you to structure your thoughts. You are then more likely to remember it when asked about it — rather than looking like a fool, you’ll be able to crisply and eloquently describe these previous projects and what you gave to them and took from them.

Which leads me to the next thing: can you draw the architecture of the last project you worked on in 60 seconds? You would not believe the number of times I have asked someone to draw a simple visualisation — ANYTHING — of a system they were supposedly a key contributor to, and they can’t do it. With a whiteboard marker in their hand and an empty whiteboard in front of them, no matter how comfortable I try to make them feel, they turn into a blithering idiot. It might be stage fright, but what comes across is that they have never attempted to explain their work to another human being.

You might think you know in your head how your system is put together, but you will be proved wrong the first time you attempt to actually draw it in boxes and arrowed lines. So think about which project you are going to talk about the most in your interview, and practice drawing a diagram that represents it the best. And practice it again.

It might be a physical architecture diagram, or a logical system diagram, or a data flow diagram, or a sequence diagram, or a use case diagram. That’ll depend on your job and what points you want to get across. But it needs to be obvious to the interviewer that it comes very naturally to you to be able to visualise and explain a system you have worked on.

The third thing: you will often be asked what you would do differently if you had the chance for a do-over on a particular project. Think about this one in advance. Knowing what you know now, would you choose different tech or make different architectural choices? Would you put a greater emphasis on some non-functional aspect such as monitoring or performance testing? Why didn’t that happen first time around? Was it an oversight or were someone’s arguments to management not sharp enough?

I’m telling you to think about this not just so you can prepare a well-rehearsed answer. After all, you may not even get asked the question. But even just by asking yourself this question, you are training yourself to think about how you can learn from your mistakes or experiences. It may trigger a thought process about best practices and how to win the argument for adopting them.

So those last few things I mentioned are about demonstrating that you can see the bigger picture. You can move comfortably between the concrete and abstract details, and you can demonstrate ownership and personal accountability through being able to describe, visualise and reflect upon the projects you have contributed to. These all help me as an interviewer to feel confident in your ability to be net positive contributor if you join the team.

During the interview

OK, those were my tips for interview prep. Now a few words about the interview itself. I won’t dwell on this because there’s reams of stuff written on this topic, but here are a few quick pointers on what I value.

Turn up on time. I had an interviewee arrive 10 minutes late and offer no apology or explanation. I asked him, “did you have trouble finding us?”, “oh no, it was easy”. “OK, did you have a long way to come?, “no, I just live round the corner!”. Bad impression from the off.

Be polite and professional. Even if you know they have a very casual dress code, that’s not a reason to turn up in your favourite 20 year-old Napalm Death t-shirt. Little things like this matter. I once interviewed a guy who had a bag with him, and he left it open on the floor between us. I could see one condom sitting proudly at the top of his bag. Just one. Ribbed. I still wonder exactly how he thought that interview was going to pan out.

Ask about the tech culture. They should be selling this to you, but if not you should ask. Ask what they do to encourage and support the team keeping on top of the latest practices and technologies, and what they do to share knowledge in the team.

Don’t ask questions that sound like you’re a jobsworth. If you’re asking in the interview whether you can finish at 4pm every day, you may already be talking yourself out of it. If you have a specific requirement such as childcare commitments, it’s much better to bring this up once you have an offer but before you start, because they’ll be more psychologically committed to you as a candidate by then.

Remember that they want you to succeed. In most cases, they will be willing you to do well and hoping you are the right person for the job. They’ve already taken time out of their day to speak to you and have already rejected a bunch of other CVs. They’ve seen something in you they like. Take a positive mindset into the interview.

Unfortunately, there are bad interviewers. I said at the top of this talk that we all make snap judgments, and sadly that can work against you or for you. Some other bad types of interviewers are:

• The one that’s trying to catch you out or make you feel small. Usually this is because they have are having marital problems
• The one that persists with a specific question because there’s a particular thing they seem to want to hear
• The one who talks about themselves the whole time
• The one who is super friendly but doesn’t ask you any probing questions you can use to bring out your best

The best you can do in these cases is be polite and patient, but look for opportunities, little openings, to turn the conversation in a direction you want to take it. Have those bullet points about yourself and your projects that I talked about at the ready. It may or may not work, but this is where the prep pays off in an unexpected way.

Speaking of bad interviewers, you do unfortunately still get otherwise sane people asking you in interviews what your spirit animal is, or what kitchen utensil you’d like to be reincarnated as, or asking you to estimate how many grains of sand there are in the Sahara. One guy on my team had to talk for 5 minutes about a rock that was placed on the desk in front of him.

I have to admit to having tried all these things in the past. They might tell me something about your reasoning skills or your sense of humour, but I’ve concluded they are usually pretty pointless. But play them with a straight bat and answer them as best you can, because if you laugh in their face you will probably insult them, because they obviously think it’s a really clever question.

Ace the interview

Right, so I’ll repeat a few points here, but for me these things are key to delivering a great interview, rather than a decidedly OK interview.

I keep talking about having a point of view. Don’t be afraid to let that come out. Take the initiative in the interview and set out a narrative, a theme or common thread around which you can build your answers. You might want to make the case, for example, for automating as much as you can in the development pipeline. Lay that out as something you are passionate about early on, and keep referring back to that in your answers to subsequent questions. It is great to hear when someone has an opinion on the state of tech or the industry, and can speak passionately and informatively about it.

Listen to and answer the questions put to you. In doing so, try to work out why they were asking that. What were they really trying to get out of you by asking that question?

But then use their questions as springboards to get across the points you want to make that help you sell your skills and experience. Think of it like the tennis player who uses the power of the opponent’s serve to generate a cracking return, and then adds a bit of spin on top as well.

Expect the unexpected. That’s an awful cliché, but here’s what I mean. Let’s say they ask you about something on your CV that you weren’t expecting to be asked about, whether it’s a particular framework you’d forgotten about or something more leftfield. The natural response is to go on the defensive.

But again, think of these as an opportunity. Even if you give a mediocre answer, you’ve still got a free hit for you to bring up some of the attributes or skills that YOU want to talk about.

This is where it really helps if you have practised those bullet points about what you’re good at and what you’ve achieved. Because you’ll often find opportunities suddenly arising at the most unexpected time to get across some point you wanted to make, and you’ll have those little phrases and examples at the tip of your tongue just when you need them.

Try to balance confidence with humility. It’s a very British thing. We like people who are capable and intelligent, but we don’t like them to show off about it. A bit of self-deprecating humour can go a long way, used judiciously. You want to get across the message that “I’ve got this. But I don’t take myself too seriously, so other people will go along with me”.

If you’re going for a senior role, I read a great article about what companies are looking for, whether they realise it or not, when they say they want a senior.

Firstly, they want someone who is a skilled mentor. It’s not just about bringing mad skills; you need to be excited about and able to transfer those skills to more junior team members.

Secondly, they want someone who is an accelerator. Are you someone who makes things go faster, because you’re always looking at ways to optimise and improve? Or are you going to keep things as they are, or worse slow things down? Every manager in the world thinks the dev team aren’t delivering fast enough. So they want an accelerator.

Thirdly, they want someone with perspective. This often means experience, but you can gain perspective with every new thing you learn. There are always at least two sides to every story, and being able to balance off competing priorities using experience and insight is a valued skill.

Be comfortable visualising technical concepts you are talking about. Don’t be afraid to ask if you can jump up and draw it on a whiteboard. If you ask them, rather than wait to be asked, if you can draw it, you will give them a warm fuzzy feeling that you have a good handle on the big picture and are a natural explainer.

Interviewers for dev positions will listen carefully to your answers about technical debt and non-functional requirements. It’s a sore subject in most teams, and usually a source of tension between product and tech. The trick is not to come down hard on one side of the argument or guess what side you think they are likely to be on, but to demonstrate (ideally with examples) that you realise it’s a balancing act. It shows maturity and good judgment.

Nail the tech test

The tech test is where the chickens on your CV can come home to roost.

There are various flavours of technical test, and I’ve tried them all at various stages. Right now, I do a combination of a simple whiteboard test in the first interview stage to check you have got the rudimentary thinking skills, and a more in-depth coding exercise with the team if you get through to the second stage.

I’ll go through the main types of tech test you might encounter:

Standard screening test before you get an interview. I think these are generally a bad idea — it’s like they’re trying to put you off the company. I can’t give you any specific advice on how to approach these ones, other than that you can get better at them with practice.

At-home tests after you’ve already had a positive first interview. I’ve used these before, and they can be pretty useful. What I’m generally looking for here is that you a) understood the thing I’m asking you to do, and that means it’s OK for you to come back and ask questions about the challenge; b) can write solid and elegant code; and c) understand the importance of good housekeeping.

So take a bit of care with your solution, don’t rush through it. And for that last point, be sure to comment your code appropriately, even if you aren’t a big believer in doing that; write unit tests that pass; and commit to whatever repo you are using as though you were working on a team project. Clear some time in your weekend to work on it, because if you tell me you were busy and did a quick hack, I’ll assume you’re not that bothered about the job.

Locked away like a hostage in a meeting room for an hour with a challenge and a laptop. For these, before you start, ask the interviewer what success looks like; what are they are most interested in seeing from you? Are they more interested in having something working, something complete, or something well-written?

• Realistically, they might tell you to use your own judgment, but even asking them sends a good signal. If they do say that, tell them you’ll focus initially on having something working.
• In which case, you need to be disciplined about continuously compiling and running, so spend a few minutes at the beginning making sure you are set up for that.
• If they want something complete, it’s pretty much a test of your ability to hit a deadline. In this case, take a few minutes at the start to plan out your hour, and give yourself milestones to hit.
• If they want something well-written, take a few moments to consider what you want to showcase. Look for clues that suggest what they want to see — maybe it’s a particular code structure or implementation pattern. If you just dive in without considering what an elegant solution might look like, you will probably just write bad code.

Whatever your approach, explain at the end what approach you took and any assumptions or shortcuts you made.

Coding in front of a technical interviewer. For this one, you want to appeal to their instincts as a peer. They will, or at least should, appreciate you doing things like writing unit tests, perhaps even following a TDD style, observing concepts such as single responsibility principle and patterns such as dependency inversion.

They will probably also admire your pragmatism if you say, “Oooh I bet there’s an NPM package for this, can I have a look?”. In any case, the most important thing is to talk them through what you are thinking. Explain your reasoning, and if they guide you down a different path, be sure to listen.

Whiteboard coding. Don’t be deceived into thinking that you’ve dodged a bullet by not having to write working code. A good interviewer in a software company will actually ask you to solve a particularly thorny question in this format because it means you can focus on logic and reason and fundamental computer science concepts, without getting bogged down in the syntax of a particular language.

• Remember that — don’t get bogged down into writing working code. It’s a whiteboard, not an IDE. Write it in pseudo-code, or if you are more comfortable, write it in your favourite language but tell them you aren’t going to get hung up on semicolons
• If they ask, “are you happy with your solution?”, that’s often code for them saying they think there is a mistake. If you can’t see it, I’d be impressed if you started writing some pseudo tests for your pseudo code. Because this simultaneously shows you understand the importance of validating your code AND it may actually help you tease out the logical flaw if there is one.
• Also, don’t be afraid of just scrubbing it and starting again — it’s a whiteboard, that’s what they’re designed for. If you are really stuck in a rut, think about it as a TDD problem. Tell them you’re going to break it down into the smallest unit of a problem, write the simplest case that will pass, and then build on it. If you are still stuck, ask them for a clue.

As you go through your tech test, remember we’re looking for people who, in the words of Joel Spolsky, are smart and get things done. Focus on what the problem is they are asking you to solve, listen to what they are trying to guide you towards, explain your thinking, and prioritise getting to a working solution.

Thanks for listening, and I hope you found some of that useful. And of course I would be stupid not to use this opportunity to tell you: I’m hiring!

(Opinions are those of the author, not the company. All images used are copyright of the original publishers, who are too numerous to track down given the sheer volume of memes in this talk!)

CTO Secrets: How to get the best companies fighting to hire you (part 3 of 3) was originally published in Koodoo on Medium, where people are continuing the conversation by highlighting and responding to this story.