While working as a developer, I was always frustrated that functionalities were not fully defined, specification either did not exist or was poorly written, the documentation (comments, migrations, API docs, ER diagrams, architectural overview) was prehistoric and outdated. I wasted a lot of time finding out all the necessary information, and often I didn’t get it. Then I would embark on coding something on my own, which didn’t always bear fruit. My assumptions were not always correct, which would result in me having to rework part of the logic.
I have worked in companies and as a freelancer, in large teams, small groups and as an individual. What I also noticed was that there was not much uniformity among the projects within the firm.
On the other hand, developers coded components that were not reusable. Technologies, stacks and tools were chosen based on current hypes so that everyone is working with cutting-edge technologies. People always assume that it speeds up the software development process and increases the quality of output. But is that really the case?
The more I brainstormed, the more I became interested in the role of properly setting up the projects before programming; trying to correct things I diagnosed as issues during programming (be it programming as a solo developer or in a group of multiple people). From time to time, there was a Frontmen or Team Lead involved, who would organize the team, assisting with writing functionalities, tests and helping younger colleagues to polish their skills.
However, there was always a lack of “something”. That’s why I think a software architect is a necessary component in the software development process.
What is the definition of Software Architect?
“A software architect is an expert-level software developer who communicates with businesses and clients to design and execute solutions with a team of software engineers. A software architect makes executive software design decisions. They often act as a designer, developer and communicator. ” — Indeed
…or if we take a look at the Wikipedia:
“A software architect is a software development expert who makes high-level design choices and tries to enforce technical standards, including software coding standards, tools, and platforms.” — Wiki
Does the Software Architect write code?
In the situation I find myself in — less often. There are many other responsibilities that a software architect does, and yes, ‘programming’ is on the menu, but to a lesser extent and as needed.
A software architect spends far less time writing code than software developer, as they have a fairly different role. Both of them exist in the software development eco-system, but the first primarily focuses on transferring business requirements to functional, the latter is more oriented towards transferring functional requirements to code.
A Software Architect often makes things easier for developers by writing high-level pseudocode, proof of concept for an external service or for a 3rd party API. This speeds up the time a developer would “lose” reading all the documentation. (in quotes, because reading any documentation is very likely not a waste of time).
I am currently in the position of a software architect. For me, this is a position that includes:
- Working with the client — Together with the project manager, I participate in daily activities in the form of transferring business requirements into functional requirements. I participate as a link that connects the development team, the client and the product. In daily or weekly briefing, I try to bring the project issues and the current state of the product closer to the client. This helps us all make good and timely decisions. Mostly the output of this is a Functional Requirement Document along with the weekly updates
- Working with the design team — once the scope of the project is determined, use cases are defined, very often it is necessary to create wireframes — initial system sketches/mockups to see the framework, and visually understand whether all use cases and functionalities are covered. To create wireframes, it is always good to consult with the design team, who most likely have a greater amount of knowledge in this domain than I do
- Organizing processes with a project manager — when setting up and maintaining a project, processes and tools are often chosen to facilitate development, progress monitoring, estimation and bottlenecks
- Individual work — writing documentation, creating APIs, creating a database and often researching new technologies
- Proof of concept — so that developers become efficient as soon as possible and do not worry too much about project documentation and external services documentation
- Working with developers — participating in the more complex tasks, with the emphasis on ensuring that the task is successfully understood, and that the resulting outputs are known. This item sometimes includes writing code, pseudocode, auxiliary diagrams, and giving exact examples
As I have already gone through a number of projects, I have internally put together the stages of each project (regardless of the product development method). I divided it into:
- Pre-Development (Scoping)
- Wireframing & Functional Requirements Document (FRD)
- API & Database Design
- Technology Stack
- Development & Quality Assurance
- Post-Development (Maintenance)
Responsibilities are different across different phases of the project.
- Pre-Development (Scoping)
The Pre-Development stage can be considered as the initial stage of the project. The project can be already ongoing (e.g. we inherited the code from another company, client reached us along the way, or client needs our expertise to work on a particular segment / module of the project). Also, the idea can be completely new and we need to start the project from the start.
This stage always starts with the kick-off meeting.
Usually, there are two kick-off times. One is internal — between our team members. Often, we receive some form of documentation, which needs to be analyzed so we are prepared for the meeting. That is what is discussed at the meeting.
Second one is with the client — it is an introductory meeting in which we meet our clients, exchange basic information and introduce ourselves. The client often tells us where the idea came from and more about the project.
After the initial kick-offs, we usually set weekly meetings with the client that last between 30 and 60 minutes. The intention is to gather information on what needs to be done on our side. We have to gather the client’s business requirements and scope them in order to understand what type of application they need (web, mobile, IoT). We need to understand what are our responsibilities on the project.
- Comprehend the scope of the project.
- What are the functionalities?
- Discuss user stories with the help of the PM
- Define features and functionalities — define project scope
- Define roles
- Define 3rd party integrations (at least bigger one, such as Zoom, Google Maps, Slack, Stripe, etc.)
In this phase, my responsibilities would divide between the kick-off meeting, weekly meetings and items to do in between the two meetings.
- read the documentation (if there is one)
- be an active listener
- Weekly meetings:
- prepare for the upcoming meeting (individual or with the PM)
- discuss the idea with the client while noticing the functional and logical components of the system
- make notes, understand deliverables for the next meeting
- ask questions and ask for clarifications
- be sure that both sides (Company and Client) understand what are the next steps
- In between meetings:
- research the topics that you do not understand
- ask other architects for their insights and opinion if needed
- research about potential 3rd party integrations
- include Project Manager in your research conclusions
- Wireframing & Functional Requirements Document
Once the project is defined up to the point both sides are comfortable going forward, most of the projects will have at least one, if not both deliverables needed (Wireframes and FRD).
First on the list is functional requirements documents. Functional requirements document is a document that defines general purpose, architectural overview, application roles and application functionalities. It encourages the idea of having feature sets, user stories, references (with 3rd party integrations), roles and architecture all in one place. This helps both sides to be sure they are on the same level and that nothing is missing.
Wireframing, on the other hand, is the initial process of content management on the platform(s). It helps:
- both parties to understand and precisely define what type of content will be displayed on each screen
- both parties to be certain that the app workflow is fluent
- client to understand how the app will be used
- architect to understand components of the project
- designer to have a general idea of what the app should look like
- project manager and developers to give a better estimation
Wireframing is a semi-creative process in which an architect (and sometimes project manager) sketches the application while going through the already defined functionalities.
During this phase, there are certain responsibilities that an architect needs to follow:
- create wireframes
- explain your ideas on a weekly call
- discuss the ideas
- guide the client through each screen and through each workflow
- adapt the wireframes based on client’s needs and feedback
- focus on the workflow, not on all the details
- note down any potential issues in the workflow that could affect other stages of the project (e.g. missing workflow to “Restore Password”)
- API & Database Design
While design team creates the clickable demo based on the wireframes, software architect focuses on the initial project setup — database design and Application Programming Interface (API) based on the functional requirement document.
Designers use the previously created wireframes and make them alive. Most often they create one initial page with 2–3 color schemes or 2 differently designed screens before moving forward. Once the client confirms the correct design path, the designer creates the rest of the screens.
Throughout this phase, software architect needs to:
- be available to the design team and to the client for potential inquiries
- start designing database
- start creating Application Programming Interface (API)
- Technology stack
While the design team is in the process of creating screens and clickable demo, software architect can start researching and making decisions on the project architecture. This might involve senior developers for their expertise to detect possible flaws and decide which practices to follow and design patterns to use. You need to define which technology stack will be used. The decision should be based on several factors:
- Project complexity
- Clients input
- Our resources expertise (developers)
- Comfort level
Note — it is important to understand your company’s and developer strength and weaknesses. What benefits do you have if cutting-edge technologies are used if no one can implement them and reap their benefits?
It is often not necessary to put the project and team at risk of failure, just to use and learn latest technologies. Everything has its time and place.
Except for choosing the stack, the software architect should finish designing the database and have the majority of the API defined.
In this phase, software architect will have to:
- choose the tech stack
- finish database architecture (modelling)
- finish API
This phase starts when we have a defined feature set and when we communicate with the client that we will proceed with development. Most often, the project manager finds an available resource that is familiar with the technology we will be working with.
Using the feature set, wireframes and available designs, with the help of project manager and the architect, developer(s) provide a document that includes effort in days or hours per task, feature and total. Based on the estimation document and its certainty, a timeline is created.
In this phase, the collaboration between Software Architect and Development Team is important. It’s software architect responsibility to:
- explain the project idea to developers
- guide developer through the wireframes
- assist developer and make any necessary clarifications
- if the estimates are too excessive or too small, try to figure out why — maybe there was a misunderstanding
P.S. Don’t treat estimates as hard deadlines. It won’t work.
- Development & Quality Assurance
Once the project scope is defined, wireframes are done, designs are ready, project estimation and cost is provided and approved, you are good to go to start the development process. The initial phase (also) includes:
- staffing and finding appropriate resources
- setting up the project — this includes a whole variety of tasks, depending on the project — getting necessary credentials and API keys, setting development server, CI/CD, testing environment, code standards, aligning expectations
- choosing proper management and code versioning tools
- choosing a proper project methodology (Waterfall, V-Model, Agile methodologies)
- transferring feature sets and tasks into management tool
6.1. Features, Tasks and Progress
When everything is ready, we finally start coding. Project manager and software architect need to get along and prioritize tasks, developers have to write logic and code, and the quality assurance team needs to verify each and every task that is developed before marking it as “done”.
This is a long process that lasts from a few weeks to a couple of years, depending on the scope and length of the project. Since it is a long-term thing, it is necessary that both PM and SA track progress on the project.
If there are delays, it should be noted and communicated properly to the client — why it happened and by how much it will postpone the release.
It is important that tasks are written clearly by an architect and project manager, and understood clearly by the developer.
It is up to the architect to explain a complex workflow in a precise and a clean way (not necessarily, but preferably — write tasks with detailed explanation, workflows, diagrams and pseudocode). (P.S. This rule applies if there is no dedicated team lead on the project.)
The better the task is explained and the simpler the workflow is (following the best practices), the easier the implementation will be.
However, not every task needs to be explained in detail. A lot of tasks are self explanatory and are repeatable on a lot of projects. In such a case, a brief explanation is enough.
6.2. Quality Assurance
Each task that is implemented, needs to be properly tested by the Quality Assurance team. If there is a complex workflow, or an unusual situation, it is often recommended that PM and SA give a detailed explanation of what are the inputs and what is the expected output.
For a non-common case, it is recommended to give additional input, make clarifications and state what is expected in order for the QA team to test the product properly.
Surely there will be end-cases you will not be able to find, but the general idea is to create a fluent user experience.
6.3. Weekly meetings
Most of the time, we will set up a weekly meeting with the client during development in which our side needs to update the client with the project progress, raise any issues and concerns and mark change requests.
It is important that any change requests made by the client during this phase (after estimation) is noted down, and if it is an added work that may cause delays from the initial estimates you have it properly documented.
6.4. Releases, builds, versions
It is recommended to have alfa/beta builds released incrementally / iteratively. This helps both sides to track the progress and mark potential issues and change requests early.
On another note — release dates should be communicated properly.
As this could potentially be a long process, it requires software architect’s attention. You’ll have to:
- prioritise tasks
- where needed, assist developers by creating detailed workflows, diagrams, pseudocode for an efficient implementation
- prepare documentation and help regarding 3rd party integrations (sometimes with the proof of concept and a little bit of coding). You can also help with unknown packages and libraries if there’s time for it.
- regularly communicate with the project manager
- raise concerns about delays and implementation/integration issues early
- Post-Development (Maintenance)
The product is done. The project is (almost) over. What is often left is the maintenance. Frequently, the company stays with the client for some time in order to maintain the product and make minor (or major) changes. This can even evolve into Phase 2 or 3 of the project in which you start over with Project Phase 1 (Scoping).
Most of the time, your task here will be to:
- reply to emails
- fix bugs, make smaller changes, assure that the product is functional
The position of software architect is demanding, if we take into account that there is social interaction, it requires a good team spirit and understanding for others, good technical background and willingness to constantly learn new things. The main obstacles for a person to run for the position of software architect would, in my opinion, be the following:
- good self-organizing skills are needed — it is easier when you are assigned a defined task for which you need to find a solution, than to create and provide both tasks and solutions on your own.
- it requires constant interaction with people and fine soft skills
- the fear that ‘you may not know enough’ to be in such a position — but this is a great opportunity to learn and develop it ‘enough’
- writing a lot of documentation
- work on multiple projects at once
- greater responsibilities if the project fails
What does a software architect position look like in your environment?