I attended a Conference sometime back and what one of the speakers majored on left a mark on me. Architectural designs shape the flow and the project, embodying technical decisions while at it and laying the ground work for the long term sustainability and adaptability of the Systems.

Those decisions can be as simple as choosing a code style to more important ones, such as which architectural style is ideal or which database type. After months of engineering, remembering the rationale behind a decision can be tricky because more context is needed that influenced the decision.

Below is a framework that can be used for Architectural decisions:

1. Discussions.

When requirements come, we need to discuss them first. We have weekly recurring places for conversation, where we discuss spikes, challenges, and decisions.

Some discussions lead to the Request for Comments (RFC) process.

2. Request for comments.

In this process, we create RFC documents, which are formalized approach to proposing changes, improvements, or the introduction of new features within a project. These documents have the following structure:

🔹 Summary- What is it about.

🔹 Scope- What is our scope.

🔹 Participants- Who work on this.

🔹 Status-In which status is this in.

🔹 Proposal- the central part, what we propose as the solution.

🔹 Pros/Cons- What are the pros/cons of our approach.

🔹 Alternatives- What are alternatives to our Proposal.

🔹 Questions — If some open questions exists.

🔹 Conclusions — What we conclude at the end.

The RFC process usually goes in three steps:

1. Creation of the RFC.

2. Comments.

3. Conclusion.

When working on RFC, we also include two things:

🔸 Internal Tech Radar (This works similarly with Thoughworks radar).

🔸 Internal Tech Standards (e.g how do we do logging, exception handling, etc).

3. Architectural Decisions Records.(ADR).

When a conclusion from RFC exists, they are used to create ADRs. ADRs are documents that capture essential decisions about a Software System’s Architecture. Usually, we store it in the codebase, close to the issues that they describe. They record the decision itself, the context in which it was made, the factors considered, the expected impact. By providing a historical record, ADRs help communicate decisions to stakeholders, ensure consistency in decision-making, and promote transparency and accountability.

ADRs usually have the following structure:

🔹 Title.

🔹 Status.

🔹 Context.

🔹 Decisions.

🔹 Consequences.

Once the process is completed, requirements implementations can then proceed.

Thank you stopping by and see you in the next one.

Special credits to @milan_milanovic on X(Formerly Twitter)