Architecture decision records (ADR) in Microservices - System Design Exercise

Design: Architecture Decision Records (ADR) System

In scope: ADR creation, storage, versioning, search, collaboration, and API access. Out of scope: Automated ADR generation or integration with CI/CD pipelines.

Functional Requirements

FR1: Allow teams to create, update, and view architecture decision records.

FR2: Support linking ADRs to specific microservices or projects.

FR3: Enable search and filtering of ADRs by date, status, or tags.

FR4: Provide version history for each ADR to track changes over time.

FR5: Allow collaboration with comments and approvals on ADRs.

FR6: Ensure ADRs are accessible via a web interface and API.

Non-Functional Requirements

NFR1: Handle up to 500 concurrent users editing or viewing ADRs.

NFR2: API response time p99 under 150ms.

NFR3: System availability of 99.9% uptime.

NFR4: Store up to 10,000 ADRs with version history.

NFR5: Secure access with authentication and role-based authorization.

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

Key Components

Web frontend for ADR management and collaboration

Backend API service for CRUD operations and business logic

Database for storing ADR content, metadata, and versions

Authentication and authorization service

Search engine or indexing service for fast filtering

Notification or collaboration service for comments and approvals

Design Patterns

Event sourcing or versioning pattern for ADR history

CQRS (Command Query Responsibility Segregation) for separating reads and writes

Microservice architecture for modular ADR management

Role-based access control (RBAC) for security

API gateway for routing and security

Reference Architecture

  +----------------+       +----------------+       +----------------+
  |  Web Frontend  | <---> |  API Gateway   | <---> | Auth Service   |
  +----------------+       +----------------+       +----------------+
          |                         |
          v                         v
  +----------------+       +----------------+       +----------------+
  | ADR Service    |       | Search Service |       | Notification   |
  | (CRUD + Logic) |       | (Elasticsearch)|       | Service       |
  +----------------+       +----------------+       +----------------+
          |
          v
  +----------------+
  | Database       |
  | (PostgreSQL)   |
  +----------------+

Components

Web Frontend

React or Angular

User interface for creating, viewing, editing, and collaborating on ADRs.

API Gateway

Kong or NGINX

Routes requests, handles authentication, and enforces security policies.

Auth Service

OAuth 2.0 / OpenID Connect

Manages user authentication and role-based authorization.

ADR Service

Node.js/Express or Spring Boot

Handles business logic, ADR CRUD operations, versioning, and linking to projects.

Search Service

Elasticsearch

Indexes ADR metadata and content for fast search and filtering.

Notification Service

RabbitMQ or Kafka

Manages comments, approvals, and collaboration notifications.

Database

PostgreSQL

Stores ADR content, metadata, version history, and user data.

Request Flow

1. User logs in via Web Frontend, which authenticates through Auth Service via API Gateway.

2. User requests to create or update an ADR; request goes through API Gateway to ADR Service.

3. ADR Service validates request, stores ADR and version info in Database.

4. ADR Service sends update events to Notification Service for collaboration updates.

5. Search Service indexes new or updated ADR metadata asynchronously.

6. User queries ADRs via Web Frontend; API Gateway routes search requests to Search Service.

7. Search Service returns filtered ADR list; Web Frontend displays results.

Database Schema

Entities: - ADR: id (PK), title, status, created_at, updated_at, project_id, current_version_id - ADRVersion: id (PK), adr_id (FK), content, version_number, created_at, author_id - Project: id (PK), name, description - User: id (PK), username, email, role - Comment: id (PK), adr_id (FK), user_id (FK), content, created_at Relationships: - One Project has many ADRs - One ADR has many ADRVersions - One ADR has many Comments - One User can author many ADRVersions and Comments

Scaling Discussion

Bottlenecks

Database write contention when many users update ADRs simultaneously.

Search Service latency with growing ADR volume and complex queries.

Notification Service overload with high collaboration activity.

API Gateway becoming a single point of failure or bottleneck.

Solutions

Use database sharding or partitioning by project to distribute load.

Implement caching for frequent ADR reads and optimize Elasticsearch indexing.

Scale Notification Service horizontally and use message queues for load leveling.

Deploy multiple API Gateway instances with load balancing and failover.

Interview Tips

Time: Spend 10 minutes understanding requirements and clarifying scope, 20 minutes designing components and data flow, 10 minutes discussing scaling and trade-offs, 5 minutes summarizing.

Explain importance of versioning ADRs for traceability.

Discuss role-based access control for security.

Highlight separation of concerns with microservices.

Describe how search indexing improves user experience.

Address scaling challenges and realistic solutions.

Practice

1. What is the main purpose of an Architecture Decision Record (ADR) in microservices projects?

easy

A. To document important architecture decisions and their reasons

B. To write detailed code for each microservice

C. To track bugs and issues in the system

D. To monitor server performance metrics

Solution

1. Step 1: Understand the role of ADRs

   ADRs are used to record key architecture decisions and why they were made.

2. Step 2: Differentiate ADRs from other documents

   ADRs are not for code, bugs, or performance monitoring but for decision documentation.

3. Final Answer:

   To document important architecture decisions and their reasons -> Option A

4. Quick Check:

   Purpose of ADR = Document decisions [OK]

Hint: ADRs capture decisions, not code or bugs [OK]

Common Mistakes:

• Confusing ADRs with bug tracking
• Thinking ADRs are code documentation
• Assuming ADRs monitor system metrics

2. Which of the following is the correct basic structure of an ADR document?

easy

A. Title, Status, Context, Decision, Consequences

B. Title, Code, Tests, Deployment, Logs

C. Summary, Bugs, Fixes, Performance, Metrics

D. Introduction, User Stories, UI Design, API Endpoints

Solution

1. Step 1: Recall ADR standard sections

   ADRs typically include Title, Status, Context, Decision, and Consequences.

2. Step 2: Eliminate unrelated structures

   Options with code, bugs, or UI design are unrelated to ADR format.

3. Final Answer:

   Title, Status, Context, Decision, Consequences -> Option A

4. Quick Check:

   ADR structure = Title, Status, Context, Decision, Consequences [OK]

Hint: Look for Context and Consequences in ADR structure [OK]

Common Mistakes:

• Mixing ADR with test or deployment docs
• Confusing ADR with bug reports
• Including UI design in ADR

3. Given this ADR excerpt:

Title: Use REST for service communication
Status: Accepted
Context: Need simple, stateless communication
Decision: Use REST over HTTP
Consequences: Easier integration but higher latency

What is the main consequence documented here?

medium

A. REST requires stateful connections for speed

B. REST causes stateless communication to fail

C. REST reduces integration complexity and latency

D. REST leads to easier integration but higher latency

Solution

1. Step 1: Read the Consequences section carefully

   The consequence states "Easier integration but higher latency".

2. Step 2: Match the consequence with options

   REST leads to easier integration but higher latency matches exactly; others contradict the text.

3. Final Answer:

   REST leads to easier integration but higher latency -> Option D

4. Quick Check:

   Consequence = Easier integration, higher latency [OK]

Hint: Focus on Consequences section for effects [OK]

Common Mistakes:

• Ignoring the 'higher latency' part
• Assuming REST reduces latency
• Confusing stateless with stateful

4. You find an ADR with this status:

Status: Deprecated

What does this status indicate about the decision?

medium

A. The decision is newly proposed and under review

B. The decision is no longer recommended or used

C. The decision is currently active and enforced

D. The decision has been accepted but not implemented yet

Solution

1. Step 1: Understand ADR status meanings

   "Deprecated" means the decision is outdated and should not be used.

2. Step 2: Compare with other statuses

   New proposals are "Proposed", active ones "Accepted", so deprecated means no longer recommended.

3. Final Answer:

   The decision is no longer recommended or used -> Option B

4. Quick Check:

   Status 'Deprecated' = Not recommended [OK]

Hint: Deprecated means outdated, avoid using [OK]

Common Mistakes:

• Confusing deprecated with accepted
• Thinking deprecated means new proposal
• Assuming deprecated means pending

5. Your team must decide between using REST or gRPC for microservice communication. You want to document this choice clearly for future reference. Which is the best way to use an ADR in this situation?

hard

A. Write code samples for both REST and gRPC without explanation

B. Skip documentation and decide by majority vote only

C. Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice

D. Create a bug report to track this decision

Solution

1. Step 1: Identify ADR purpose for decision documentation

   ADRs should explain context, decision, and consequences clearly.

2. Step 2: Evaluate options for documenting architecture choices

   Only Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice uses ADR properly; others ignore documentation or misuse formats.

3. Final Answer:

   Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice -> Option C

4. Quick Check:

   Use ADR to document decision and consequences [OK]

Hint: Use ADR to record context, decision, and consequences [OK]

Common Mistakes:

• Skipping documentation
• Confusing ADR with bug reports
• Only writing code without explanation