Software Engineering

Management

Management

Questions for architecture

A cheat-sheet to help drive effective outcomes and facilitate inter-departmental communication.

image.png

Business Questions

Please describe the high-level vision of the business proposal, the problems it solves and goals it supports.

What business benefits do you anticipate from your proposed architecture?

How do you propose to measure those benefits?

What are the risks and risk mitigation strategies to this architecture?

What changes should we make, at an organisational level, to support this project?

What are the priorities for delivery? Can this list form the basis of the Epics in an Agile environment?

How is this architecture future-proofed? How easy it is to adapt the architecture to changing business needs?

Application Questions

Can you describe the data and application architectures in your proposal?

Variants

Look for:

Delivery Practices

What is your plan for migrating from the current architecture to the proposed one?

How engaged is the implementation team?

How do you plan to govern the implementation of the architecture?

What is the plan for user acceptance testing?

Management

Questions for Engineering Leadership

A cheat-sheet to help drive effective outcomes and facilitate inter-departmental communication.

Technology

Current Projects

Assessing Performance

Architecture

Architecture

Technical Architect Responsibilities

A Misconception

1257d64b-ce58-4e35-bb9f-9b115809f32a.pngIf you want to build a house, an architect drafts the blueprint while a craftsman lays the bricks following that plan.

Similarly, in software, a developer may pen the code but it's not natively understood by computers. A compiler (or interpreter) translates this code into machine language for execution. This step is aptly named "build."

The developer is the true technical architect, crafting the blueprint that the compiler then brings to life.

So if the developer is the architect, what then is a technical architect’s job?

The Elucidator

ae737d63-f2b1-43e9-a155-28c93784ae23.png

Architects engage with users, developers, and business stakeholders to gather insights and perspectives that might not be immediately apparent. Engaging stakeholders is key to understanding the strategic context that might impact the project.

As business processes are mapped out, architects might discover novel ways of re-engineering them for better outcomes.

Architects rely on current state analyses to translate high-level business goals into tangible, technical requirements and actionable tasks.

The Translator

9bc9c95f-7280-4ae1-912a-f85ff4e1c9d8.png

The translation from a product specification to a technical specification requires a unique blend of skills.

The architect serves as a crucial bridge that can perform this duty, ensuring that technical solutions are aligned with business objectives and that the product team fully understand any technical constraints and the choices that might affect timelines or deliverables.

Softer skills like clear communication, negotiation, and stakeholder management are essential here.

Architects cooperate with multiple departments and play a part in planning and estimation. Understanding both the business and technical domains allows them to serve both sides. They will also play a crucial role in assessing the impact and feasibility of new feature requests.

An architect who can code can quickly create prototypes to validate their assumptions, ensuring that the business architecture aligns with what is technical feasible.

Architects need more technical skills AND more soft skills than senior developers

The Facilitator

5960bcc4-3046-4e46-b215-2041b2c60212.png

Rather than dictate, the architect should guide and mentor. Their role is to help the team to make technical decisions that align with the project’s goals, scope, and delivery schedule.

They should communicate the technical vision to the team and help the team understand how their work contributes to that vision. They should provide detailed documentation and diagrams, that help both software and infrastructure engineers understand what needs to be built and why.

Technical architects are charged with evaluating the business requirements, finding technical solutions and actively leading the technical vision to success.

The Developer

2b4bc590-613c-4fde-9329-074c8dc7db97.png

A well-thought-out architecture accommodates for future growth, making it easy to scale the application. It optimises resource usage, lowering costs, it keeps data secure, makes the system more resilient to failures and can serve as a roadmap for the entire team.

Done poorly, inadequate architecture leads to technical debt, code that cannot handle peak loads effectively, exposure to data breaches, poor development velocity, increased operational costs and customer dissatisfaction.

Given the severity of these extremes, it is important that an architect know where their design is accelerating the team and where it is under-performing.

How?

“A software architect who is not in touch with the evolving source code of the product is out of touch with reality”

Craig Larman & Bas Vodde - creators of Large-Scale Scrum

An Ivory Tower

3f850884-db87-4170-a341-8b2a6cdb6e96.pngThe term "Ivory Tower Architect" is used to describe a technical architect who operates at a high level, often disconnected from the realities of the codebase.

Architects without developer experience might not have first-hand knowledge of the challenges related to implementation, scalability, and deployment.

Architects who are more theoretical can sometimes propose solutions that seem more complex than necessary, without clearly defined benefits.

Being distant from the daily nuances of implementation could lead to a disconnect with development teams, potentially resulting in miscommunication and conflicts.

Without direct involvement, these architects might find it challenging to identify where potential issues originate, whether in execution or design.

A Pathway Forward

11f3d1b7-7e2a-46d1-b0c7-83d11176b929.png

  1. Architects should always write some code, if only occasional prototyping.
  2. Architecture should never "hand off" to engineering. Use architects as pair programming mentors, design workshop coaches, etc ...
  3. A software architect is expected to be an active member of the Scrum team. This means participating in all the usual ceremonies.

Examples from Industry

Aaron Boodman, Google engineer.

Does Google employ software architects? Not really. Google doesn't consider that a separate skill. As you advance in your engineering career at Google, you may find yourself leading projects and this naturally involves more design and less coding. But nobody’s sole job is to “architect software”. Every engineer shares that responsibility.

Bob See, Principal Recruiter, Google Engineering

“Architect" positions/titles don't actually exist at Google. The engineering culture at Google is actually a bit allergic to the idea of people making technical architecture decisions and then expecting other people to do the coding/implementation.

From Apple's current job pages

In this role, you will be a member of the Platform Architecture team, working with hardware and software engineering groups to shape the architecture of Apple's future System-on-Chips (SoC). ... We are looking for SoC architects with a passion to innovative new hardware concepts and model them in C++/Python to demonstrate their value and impact.

From Microsoft's current job pages "Azure Solutions Architect"

Technical experience and knowledge of architecture, solution development and deployment techniques ...Ability to lead a multidisciplinary technical team, provide clear direction and take accountability for technical project outcomes

Gergely Orosz, the "pragmatic engineer"

neither Uber nor Skype/Microsoft have hands-off software architects

Architecture

Diagramming - How to

We aim for effective communication. The following questions and pointers assist to provoke reflection on ensuring the proposed outcomes from undertaking this work are met:


SDLC

SDLC

Diligence

User Interface Testing

We transform our user stories in Jira into a test plan. The test plan is then scripted to provide an automated, system-level testing of the user interface and overall customer experience. This can be run headlessly in an automated pipeline.

As with the code-level tests above, system-level tests are written to prove the existence of bugs before they are fixed. In this way we build a library of tests that grow over time and provide ever more reassurance.

User Acceptance Testing

We test the system in real-world scenarios with real-world users, to validate that it meets their requirements and expectations.

Non-functional Testing

Some or all of the below may be necessary

Bug reporting

Bug reports should include the following attributes to assist in understanding and speedy resolution:


SDLC

Develop

SOLID Principles:

YAGNI, ‘You ain’t gonna need it’:

Good developers will often:

There are many excellent development practises that contribute to clean and dry code (see below) but that can also be time-consuming and may not ultimately be needed. We aim to balance these against the YAGNI principle.

DRY, “Don’t repeat yourself”:

We look for opportunities to reduce the amount of code we write by encapsulating functionality into discreet, reusable functions. We balance this against the YAGNI principle.

Documenting / Commenting

Informative comments provide help to the next developer to work on an area of code, even when that developer is the original author at some point in the future. We write comments because we recognise that reading code is harder than writing it.

Complex areas of code are especially important to comment, often noting the paths not taken. Public APIs are specified using Open API (swagger).

TDD

Test driven development front-loads the overhead of testing and lowers the overall cost of development. We identify errors early and at a time then the code has been freshly written.

Unit tests provide evidence that a single unit of code works, typically in isolation. Integration tests, sometimes called “sociable unit tests”, provide evidence that a whole sequence of code works together.

When bugs are found we write new automated tests that prove the bug exists before we fix it. Although our initial testing is included in the cost of the story or task in Jira, bug reports that have been promoted beyond a developer environment are triaged via a new ticket in Jira.

Our pipeline collects test-coverage metrics when it executes our tests so that we can monitor and improve on this.

GIT Source Control

Semantic Versioning:

We use git commit tagging to designate versions according to semver principles.

Feature Branching:

Developers create feature branches named after their ticket

Avoiding ‘fox-trot’ Merges:

We rebase our feature branches on top of the master branch and then merge the feature branch back into the master. This ensures that origin/master is always the 1 parent in every merge.

Pull Requests and Peer Review:

Github supports a peer review process that our developers use to validate each other’s code before we merge it into the master branch. This process help raise the quality of the code written and can prevent errors and misunderstandings from entering the main work stream.

Security

Common Principles


SDLC

Deploy

CI/CD

Branch Protection

The master branch of the project is projected from direct changes. Changes can only be merged into the master branch, and then only when certain conditions are met.

Feature Branch Triggers

Code can be pushed to a feature branch without consequence. Raising a pull request should do the following:


    The PR name is linted against a Jira ticket.

    The code is compiled.

    The code is subject to static analysis for security purposes.

    The unit and integration tests are run.We only run in-process tests here. Some integration tests may be run later.


    Code coverage is collected

    A new artifact is created for this build.


    *A new resource group is created in the cloud and the artifact + any requisite data is deployed there using IaC.

    *The system tests are run against the newly created environment.Integration tests that require an environment will be run here.


    *Code coverage is collected

    * Branch-level deployment is an advanced strategy and a good target to aim for.

    Pushing to a feature branch with an outstanding Pull Request re-runs the above checks.If branch-level development is present the testing environment can be safely torn down.


    Master Branch Triggers

    The code can be merged to the master branch with at least 1 acceptance in the PR process. Merging into master triggers the same actions as above but with deployment to UAT

    Release Management

    Creating a new tag for a commit on master that matches the semver pattern triggers several sequential actions:

      The Staging environment for this project is updated with the infrastructure code from the tagged commit.

      The artifact that was created for the tagged commit is deployed to Staging. This process can be triggered manually by specifying the commit to deploy, which facilitates a rollback if we deploy malfunctioning code.

      Infrastructure as Code

      Our infrastructure is written in declarative yaml, it is executed as part of our pipeline and stored in source control.

      Monitoring

      Logging in the Cloud

      In a cloud environment it can be very challenging to debug software. We should implement detailed logging across the system, both to monitor healthy activity and to shine a light on errors. We will utilise the cloud provider's native logging services for this

      Health Checks

      Health checks ensure the system is up and responding, and may be used to verify specific system functionalities.

      Alerting

      If an error occurs, or a health check fails, an alert should be triggered to notify the relevant team members as soon as possible

      SDLC

      Design

      Baseline Technical Specifications

      Where an existing solution is already in place, analyse its implementation, assess the strengths and weaknesses of the implementation, and decide if any parts can be reused. Do this from a technical and user-oriented perspective.

      Identify the architecture patterns, technologies used, data flows, security measures and so on.Identify 3 party interactions and their mechanisms.


      rd

      Target Technical Specifications:

      Provide technical solutions that fulfil the agreed requirements. Identify software languages, service interactions, database choices, cloud providers, third party suppliers and other strategic choices.

      APIs may also be defined here with the understanding that these are prone to change as the project progresses.

      Security is planned from the outset, including where data will be stored and encrypted, defensive network topologies and both authorisation and authentication are considered.

      Robustness is planned from the outset, with redundancy in storage and infrastructure across multiple zones or regions. Traffic management, load balancing and DNS records all contribute to this.

      Scalability is planned from the outset, either with serverless infrastructure, VM scale-sets or containers and container orchestration. Database partitioning should be considered.

      Where there is more than one viable solution, a list of the pros and cons should be collated.

      Engage the development team early in this process, their input will ensure the design is technically feasible and utilises their skills effectively. Defining the technical architecture should be a collaborative process, with developers having the opportunity to propose their own solutions and clarify their understanding.Technical architecture is a guide for development, not a rigid plan. Allow for flexibility of implementation but ensure the overall structure and principles are adhered to.


      Gather Team and Stakeholder Feedback

      Technical assistance is offered to the wider team and key stakeholders to guide them through the implications of the choices they make at this level. The pros and cons of the viable solutions must be discussed and a strategy chosen that is aligned to achieving both technical feasibility and financial sustainability.