Building software most of the time feels like following a cooking recipe. For designing software solutions from scratch, we could also have some guidelines to help us through the process, ending up with a "recipe for creating successful high-level software solutions".
- Introduction
- Motivation
- Final considerations
- References
- Conclusion
Introduction
The present document intends to serve only as a guide for future high-level solution creation processes, every solution is unique, but the rationale to understand might include common steps.
This document will expose a common lifecycle that may be present in most of the cases when we onboard a new project, based on personal experience and other’s experiences. In addition, will be mentioned some edge cases making the guide more flexible.
Motivation
Among the duties of a solution architect, it’s included helping in the new clients’ onboarding process, understanding needs, answering questions from the technical perspective, and finally, come up with a high-level solution plan. The process is an iteration of steps from understanding the client’s requirements, to design a solution. To ease that process, this document will include a common recipe applicable as the basis for your next project.
High-level solution creation recipe
This section will elaborate on the creation of a solution and proposes a series of steps that can be followed to develop a successful solution.
Conceptual solution process
Captures a big-picture vision of the whole solution.
Understand the problem
The first step, and the most critical, it’s to understand what the end-users require to solve in the project. As a solution architect, you need to understand it intimately, because you will need to be able to answer questions throughout the process. In particular, you need to answer the “why” and “what” questions. Eventually in the flow, you will answer the “how” question.
A good approach to understanding the problem, it’s to gather all the possible information from the end-users. This includes talking with the end-users, having them exposing their desired workflow in order to understand the problem and how the solution should work.
While doing so, remember that most people can only think of a high-level “wish list”, it’s expected that the architect asks the correct questions, to understand the high-level “why” concern, helping you to make fast, calculated decisions during the build process, and eventually, together come up with a more defined solution.
Tips
- Take notes, those are your best friends.
- Understand “why” are we trying to solve and “what” will be the outcome result.
- Don’t be afraid to ask questions, this will reflect you are following the idea, and more importantly, you’re becoming an expert in the business.
- When you are listening to the problem, and you realize it’s too complex, apply the “divide and conquer” approach.
- Listen to the end, you’ll need every single piece of information to come up with a solution proposal.
- Sometimes our end-users will need some guidance through the process of understanding the problem.
Capture security implications
One of the biggest aspects of designing a solution, it’s understanding and complying with any security implication driven by the business requirements, mostly related to data.
The first layer of implications is to build the data warehouse for the solution. There are some aspects we should consider before making the decision:
- Is there any contractual requirement that limits where the data should live?
- Is there any legal data restriction?
- Should we comply with any security protocol to store data?
By answering these questions we can determine:
- If we’re allowed to use cloud services or must be an on-premise solution.
- It will tell us about the target zone where the application could be deployed.
- If we’re allowed to store raw data, or we should limit the data we can save.
- If we should comply with any data certification or we can use another service to solve that part.
Secondly, the authentication process. Shall we manually save credentials into our database? Could we instead rely on a service to fulfill this? Those are some of the questions we should answer for our final proposal.
Finally, if we’re designing a solution that will be plugged into an existing environment, it’s important to know if there is any restriction to monitor the logs produced, this consideration becomes more important when the solution is running in production.
Tips
- Collaborate with the end-users, since they are the business experts they well know or at least have an idea of any security restriction.
- Learn from other experiences. Research other solutions looking for known lessons about security implications.
Understand current technology situation
A well-designed solution takes into consideration a variety of aspects prior to design the actual solution. The solution architect may face one of these scenarios:
- The client hasn’t an IT team. The solution should be developed from a greenfield environment, building a technology vision along with the solution.
- The client already possesses an IT team. The solution architect should talk to the team, align technical expectations, understand limitations and share the tech philosophy.
- Under this scenario, it’s important to keep in mind that (unless the current technology status is not optimal) we’re here to collaborate, and not trying to reinvent the wheel. Our solution implemented must work consistently with the current elements in the environment.
Tips
- If there is an existing IT team, schedule some time to work with them to learn how they work and the team’s dynamic.
- If there is no team, but there is a technical counterpart, schedule a meeting to gather information, ask about previous considerations or any vision in the long term. All the information collected should be used when we’re designing the high-level solution.
Logical solution process
Describes software components, how the information flows, and control flows among the components within the system.
Evaluate existing solutions in the market
Regardless of how unique you think your problem or solution is, it’s likely that someone has attempted to solve it before.
Look for similar products in the market, find existing architectures, read or ask what your peers have said about other solutions, and check with your stakeholders to see if they know similar approaches.
Tips
- List what works and what doesn’t work from other solutions, learn from other’s mistakes.
Prepare the data structure
Software solution process is all about solving problems, automate repetitive tasks and produce useful output for the end-users. How your data flow is structured dictates how your solution should look in the end.
Data structures refer to how your data will flow within your solution. Initially, we should ask:
- How is our data captured?
- For instance: user input, service communication, data ingested, process transformation.
- What would be the output of that data?
- For instance: process transformation, consumed by another service, reports.
Organizing our data may include distinct structures. The most important is how you will organize your database. The first step, even before choosing the approach and the engine, it’s to define the entities, and for that, we’ll use all the information gathered from the previous conceptual process.
Identifying entities
What is an entity? It’s something you want to store data about. We can think of entities as tables in our database, and eventually design our solution to use it.
We’ll analyze the business requirements, and working out the nouns in the sentences. What are our nouns? They are things or objects. Nouns will be table representations, each one could be a potential table in our final database design.
Once we finalized to identify all the nouns, it’s time to define what properties we want to store about those entities.
Tips
- With practice, from the conceptual process, we would be able to highlight the tables in the middle of the brainstorm.
- Study existing solutions. There are some business scenarios with a well-defined recipe in terms of data structure that we can try to adapt to our purposes.
- Explore the best relation approach for your final data, determine why relational/non-relational is the best option for you.
- Start simple, let your data grow along with your solution.
- Be careful when our solution requires consuming data from third-party service, this could lead potentially to synchronization problems or data corruption.
Enterprise Vs Startups
The “how” may vary if your solution is targeted for an enterprise business or a startup. These are some aspects we should take into consideration, depending on the target.
For enterprise business
- The planning of the project could be in longer-term and may involve multiple teams. Identifying bigger elements and think ahead about microservices could result in benefits for the overall interaction.
- The lifetime expected for the solution may be longer, so analyze all the internal and external interfaces, be prepared for creating a solution that could support/solve problems in the future.
- The business should know more about the “why” and the “what”. Take advantage of that and plan ahead in the future.
- Your stakeholders could expect more detailed documentation about your solution.
For startups
- The main goal at the beginning is to prove the concept. So plan your solution to solve the most urgent problems.
- The lifetime expected is shorter in comparison with an enterprise solution. Don’t be afraid of designing new solutions every 6 months, that means our application has grown enough and end-users ask for more.
- The business requirements could be limited. We should expect to shape some knowledge along with the stakeholders. Design your solution complexity level to scale with your business. Under this scenario, simplicity is better than complexity.
- Don’t over complicate your solution. Deliver just enough design.
Identify how you will solve the problem
At this stage, after you’ve become familiar with the “what” and the “why”, the “how” is the next logical question. Start from the top: what are you building? How will users interact with your solution? What functionality will the users require? etc.
One common technique is to apply Conway’s law, which is the idea that organizations that design systems are constrained to produce designs that are copies of the communication structures of these organizations. Basically, the elements of your solution should communicate as the organizational structure.
As you peel through the layers, you’ll find that most of your potential features can be categorized/grouped into different types of deliverables. Features can be categorized as one of the following:
Infrastructure
Required for the solution to get started. E.g. data modeling, security, authentication, storage, environment.
Pre-requisite features
These are user-level management features. Maintenance tasks. E.g. user management, configuration settings, profiles.
Transactions
The core of your solution, as these are activities your solution is automated around. E.g. Bookings through our system, sales for our customers, cancellations, reminders, activities that save time and money.
Business results
This is where users can realize the solution has worked for them. E.g. Reports, metrics, automated procedures, automated alerts.
Once the features are categorized, you can start making technology decisions. You’ll have to decide things like buying versus building, which platform to build on, whether you’ll use pre-built open-source solutions or if you’re going to build it yourselves, etc.
Tips
- You must begin by imagining the end, then reverse-engineer your way.
- Define your functional and non-functional requirements.
Design the high-level solution
The final step is to produce documentation with your solution in a proper and understandable format. There are several techniques we can explore and leverage to produce the solution documentation. Among the approaches, we can use one of the following methodologies:
- Togaf.
- Viewpoints and perspectives.
- C4 model.
- Arc42.
Regardless of the approach chosen, the delivered documentation is expected to be useful and readable for different groups of stakeholders, technical and non-technical. As the final output, we should provide a high-level solution architectural documentation, that must elaborate on the functional and non-functional requirements and presents a high-level view of all the elements that will interact to make up the solution.
Tips
- Practice just enough documentation.
- The initial solution must not be the final version, it’s preferred to implement continuous architecture.
Final considerations
Monitoring, telemetry, and KPIs
Once you designed your solution, it’s time to work on improving the platform. To deliver your solution to production-ready is just the first step, afterward will be necessary to learn from the user in order to understand what would generate more value for coming releases.
Your software architecture should take in mind to instrument your applications. Define with your team how to prevent issues/bugs even before they happen or the user notices. Work with your stakeholders and define useful metrics to measure your business success.
Conclusion
When we are designing a new solution, the first step is understanding the problem and how to solve it. This guide should be read just like a to-do list for understanding and onboarding a new project in the practice.
References
- https://www.forbes.com/sites/forbestechcouncil/2016/10/19/a-four-step-process-for-building-a-software-solution-from-scratch/?sh=25c8e3595ef5
- https://www.mitre.org/sites/default/files/publications/pr-17-4589-guide-for-creating-useful-solution-architectures.pdf
- https://gohighbrow.com/identifying-entities/
Top comments (0)