That matters because OpenClaw is self-hosted, multi-channel, open source, and built around agent workflows such as sessions, tools, plugins, and multi-agent routing. It feels less like a toy chatbot and more like an operator-controlled agent runtime.

In this guide, you'll do three things. First, you'll learn what OpenClaw is and why developers are paying attention to it. Second, you'll get it running the beginner-friendly way through the dashboard. Third, you'll walk through an original design contribution: a proposed OpenClaw-to-A2A plugin architecture and a proof-of-concept relay that shows how OpenClaw’s session model could map to the A2A protocol.

That last part is important, so I want to frame it carefully. The A2A integration in this article is not presented as a built-in OpenClaw feature. It's a documented architecture proposal built on top of the extension points OpenClaw already exposes.

Prerequisites

This guide is beginner-friendly for OpenClaw itself, but it assumes a few basics so you can follow the architecture and proof-of-concept sections comfortably.

Before you continue, you should be familiar with:

• Basic JavaScript or Node.js (reading and running scripts)

• How HTTP APIs work (requests, responses, JSON payloads)

• Using a terminal to run commands

• High-level concepts like services, APIs, or microservices

You don't need prior experience with OpenClaw or A2A. The setup steps walk through everything you need to get started.

Table of Contents

1. What OpenClaw Is

2. Why OpenClaw Is Getting So Much Attention

3. What the A2A Protocol Is

4. How OpenClaw and A2A Relate

5. What You Need Before You Start

6. Install OpenClaw

7. Run the Onboarding Wizard

8. Check the Gateway and Open the Dashboard

9. Use OpenClaw as a Private Coding Assistant

10. Understand Multi Agent Routing

11. Where A2A Could Fit Later

12. A Proposed OpenClaw to A2A Plugin Architecture

13. Build the Proof of Concept Relay

14. How the Proof of Concept Maps to a Real OpenClaw Plugin

15. Security Notes Before You Go Further

16. Final Thoughts

What OpenClaw Is

According to the official docs, OpenClaw is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, Discord, iMessage, and a browser dashboard to AI agents.

That wording is useful because it tells you where OpenClaw sits in the stack. It's not just a model wrapper. It's a Gateway that handles sessions, routing, and app connections, while agents, tools, plugins, and providers do the actual work.

Here is the simplest mental model:

If you're new to the project, this is the practical way to think about it:

• your chat apps are the front door

• the Gateway is the traffic and control layer

• the agent is the reasoning layer

• the model provider and tools are what let the agent actually do work

That's one reason OpenClaw feels different from a normal browser-only assistant.

Why Developers Are Paying Attention to OpenClaw

OpenClaw is getting a lot of attention for a few reasons.

The first reason is control. The docs position OpenClaw as self-hosted and multi-channel, which means you can run it on your own machine or server instead of depending on a fully hosted assistant.

The second reason is that OpenClaw already looks like an agent platform. The docs talk about sessions, plugins, tools, skills, multi-agent routing, and ACP-backed external coding harnesses. That's a much richer story than “ask a model a question in a web page.”

The third reason is workflow fit. A lot of people don't want another inbox. They want an assistant that can live in the tools they already check every day.

There's also a broader industry trend behind the hype. Developers are actively looking for ways to connect multiple agents and multiple tools without giving up visibility into what's happening. OpenClaw sits directly in that conversation.

What the A2A Protocol Is

A2A, short for Agent2Agent, is an open protocol for communication between agent systems. The A2A specification says its purpose is to help independent agent systems discover each other, negotiate interaction modes, manage collaborative tasks, and exchange information without exposing internal memory, tools, or proprietary logic.

That last point matters. A2A is about interoperability between agent systems, not about exposing all of one agent's internals to another.

A2A introduces a few core concepts that are worth learning early:

• Agent Card: a JSON description of the remote agent, its URL, skills, capabilities, and auth requirements

• Task: the main unit of remote work

• Artifact: the output of a task

• Context ID: a stable interaction boundary across multiple related turns

A2A tasks follow a fairly clean lifecycle:

The A2A docs also explain that A2A and MCP are complementary, not competing. A2A is for agent-to-agent collaboration. MCP is for agent-to-tool communication.

That distinction is useful when you compare A2A with OpenClaw, because OpenClaw already has strong local tool and session concepts.

How OpenClaw and A2A Relate

OpenClaw and A2A are not the same thing, but they line up in interesting ways.

OpenClaw already documents several features that point in a multi-agent direction:

• multi-agent routing for multiple isolated agents in one running Gateway

• session tools such as sessions_send and sessions_spawn

• a plugin system that can register tools, HTTP routes, Gateway RPC methods, and background services

• ACP support and the openclaw acp bridge for external coding clients

But it's still important to stay precise here.

OpenClaw documents ACP, plugins, and local multi-agent coordination today. The docs I checked do not describe native A2A support as a first-class built-in capability.

That means the honest claim is this:

OpenClaw can be meaningfully connected to A2A in theory because the architectural pieces line up, but the A2A bridge still has to be built.

ACP versus A2A

ACP and A2A solve different problems.

ACP in OpenClaw today is about bridging an IDE or coding client to a Gateway-backed session.

A2A is about one agent system talking to another agent system across a protocol boundary.

That difference is one reason I prefer the phrase plugin bridge here instead of native A2A support.

What You Need Before You Start

The easiest first run does not require WhatsApp, Telegram, or Discord.

The OpenClaw onboarding docs say the fastest first chat is the dashboard. That makes this a much more approachable beginner setup.

Before you start, you'll need:

1. Node 24 if possible, or Node 22.16+ for compatibility

2. an API key for the model provider you want to use

3. If you're on Windows, WSL2 is the recommended path for the full experience. Native Windows works for core CLI and Gateway flows, but the docs call out caveats and position WSL2 as the more stable setup.

4. about five minutes for the first dashboard-based run

Step 1: Install OpenClaw

The official getting-started page recommends the installer script.

On macOS, Linux, or WSL2, run:

curl -fsSL https://openclaw.ai/install.sh | bash

On Windows PowerShell, the docs show this:

iwr -useb https://openclaw.ai/install.ps1 | iex

If you're on Windows, the platform docs recommend installing WSL2 first:

wsl --install

Then open Ubuntu and continue with the Linux commands there.

Step 2: Run the Onboarding Wizard

Once the CLI is installed, run the onboarding wizard.

openclaw onboard --install-daemon

The onboarding wizard is the recommended path in the docs. It configures auth, gateway settings, optional channels, skills, and workspace defaults in one guided flow.

The most beginner-friendly choice is to keep the first run simple. Don't worry about chat apps yet. Get the local Gateway working first.

Step 3: Check the Gateway and Open the Dashboard

After onboarding, verify that the Gateway is running.

openclaw gateway status

Then open the dashboard:

openclaw dashboard

The docs call this the fastest first chat because it avoids channel setup. It's also the safest way to start, because the dashboard is local and the OpenClaw docs clearly say the Control UI is an admin surface and should not be exposed publicly.

The beginner setup flow looks like this:

If you can chat in the dashboard, your day-zero setup is working.

Step 4: Use OpenClaw as a Private Coding Assistant

The best first use case is not to drop OpenClaw into a public group chat.

Use it as a private coding assistant in the dashboard.

For example, try a prompt like this:

I am building a small Node.js utility that reads Markdown files and generates a table of contents. Turn this idea into a project plan, a README outline, and the first five implementation tasks.

That kind of prompt is ideal for a first run because it gives you something concrete back right away.

You can also use it to:

1. turn rough notes into a plan,

2. summarize a bug report into action items,

3. draft a README,

4. propose a folder structure, or

5. write a safe first implementation checklist.

That is already enough to make OpenClaw useful before you touch any advanced protocol work.

Step 5: Understand Multi Agent Routing

Once the basic setup is working, it helps to understand OpenClaw’s local multi-agent model.

The docs describe multi-agent routing as a way to run multiple isolated agents in one Gateway, with separate workspaces, state directories, and sessions.

That means you can imagine setups like this:

• a personal assistant

• a coding assistant

• a research assistant

• an alerts assistant

OpenClaw already has a model for that:

You don't need to set this up on day one.

But it matters for the A2A discussion, because once you understand how OpenClaw routes work between local agents, it becomes much easier to think about routing work to remote agents through a protocol like A2A.

Where A2A Could Fit Later

A2A could fit into OpenClaw in two broad ways.

Option 1: OpenClaw as an A2A Client

In this model, OpenClaw stays your personal edge assistant.

It receives a request from the dashboard or a chat app, decides the task needs a specialist, discovers a remote A2A agent through an Agent Card, sends the task, waits for updates or artifacts, and translates the result back into a normal OpenClaw reply.

This is the cleaner story for a personal assistant. OpenClaw stays the front door, and A2A becomes a delegation path behind the scenes.

Option 2: OpenClaw as an A2A Server

In this model, OpenClaw exposes some of its own capabilities to other agents.

A plugin could theoretically publish an A2A Agent Card, advertise a narrow skill set, accept A2A tasks, and map those tasks into OpenClaw sessions or sub-agent runs.

That's technically plausible because the plugin system can register HTTP routes, tools, Gateway methods, and background services.

It's also the riskier direction for a personal assistant, which is why I think client-first is the right starting point.

A Proposed OpenClaw to A2A Plugin Architecture

This section is my original contribution in the article.

I think the cleanest first architecture is not a full bidirectional bridge. It's a narrow outbound delegation plugin that lets OpenClaw call a small allowlist of remote A2A agents.

The design goal is simple:

Reuse OpenClaw for user-facing conversations and local tool access, but use A2A only when a remote specialist agent is the best place to do the work.

Here is the architecture I would start with:

Why This Design is a Good Fit for OpenClaw

This proposal is grounded in extension points OpenClaw already documents.

A plugin can register:

• an agent tool for delegation,

• a Gateway method for health and diagnostics,

• an HTTP route for future callbacks or webhook verification, and

• a background service for cache warming, task subscriptions, or cleanup.

That means the bridge doesn't have to modify OpenClaw core to be credible.

The Mapping Table

The most important design decision is how to map OpenClaw’s session model to A2A’s task model.

Here is the mapping I recommend:

This is the key architectural claim in the article:

Treat the OpenClaw session as the long-lived conversational boundary, and treat each remote A2A task as one delegated execution inside that boundary.

That preserves both sides cleanly.

The Design in One Sentence

The a2a_delegate tool should:

1. resolve an allowlisted remote Agent Card,

2. reuse an existing A2A contextId for the current sessionKey when possible,

3. create a fresh remote Task for the new delegated turn,

4. normalize remote artifacts back into a simple local answer, and

5. never expose the whole OpenClaw Gateway directly to the public internet.

I like this design because it is incremental, testable, and consistent with OpenClaw’s personal-assistant trust model.

Build the Proof of Concept Relay

To make the architecture concrete, I built a small proof-of-concept relay.

https://github.com/natarajsundar/openclaw-a2a-secure-agent-runtime

It's intentionally small. It doesn't try to become a full production plugin. Instead, it proves the hardest conceptual part of the bridge: how to map one OpenClaw session to a reusable A2A context while creating a fresh A2A task per delegated turn.

Here's the repository layout:

openclaw-a2a-secure-agent-runtime/
├── README.md
├── package.json
├── examples/
│   └── openclaw-plugin-entry.example.ts
├── src/
│   ├── a2a-client.mjs
│   ├── agent-card-cache.mjs
│   ├── demo.mjs
│   ├── mock-remote-agent.mjs
│   ├── openclaw-a2a-relay.mjs
│   ├── session-task-map.mjs
│   └── utils.mjs
└── test/
    └── relay.test.mjs

The PoC does six things:

1. fetches a remote Agent Card from /.well-known/agent-card.json,

2. caches it with simple ETag revalidation,

3. records local sessionKey to remote contextId mappings,

4. sends an A2A SendMessage request,

5. polls GetTask until the task finishes, and

6. converts the remote artifact into a local text answer.

Run the Demo

The repo uses only built-in Node.js modules.

cd openclaw-a2a-secure-agent-runtime
npm run demo

The demo spins up a mock remote A2A server, delegates one task, delegates a second task from the same local session, and shows that the same remote contextId is reused.

The Core Relay Idea

This is the important logic in plain English:

1. look up the most recent remote mapping for the current OpenClaw sessionKey

2. reuse the old contextId if one exists

3. create a fresh A2A Task for the new request

4. poll until that task becomes TASK_STATE_COMPLETED

5. turn the returned artifact into a normal text result that OpenClaw can send back to the user

That makes the bridge predictable.

Here's a shortened version of the relay logic:

const previous = await sessionTaskMap.latestForSession(sessionKey, remoteBaseUrl);
const contextId = previous?.contextId ?? crypto.randomUUID();

const sendResult = await client.sendMessage({
  text,
  contextId,
  metadata: {
    openclawSessionKey: sessionKey,
    requestedSkillId: skillId,
  },
});

let task = sendResult.task;
while (!isTerminalTaskState(task.status?.state)) {
  await sleep(pollIntervalMs);
  task = await client.getTask(task.id);
}

return {
  contextId,
  taskId: task.id,
  answer: taskArtifactsToText(task),
};

That's the heart of the design.

Why This Repo is a Useful Proof of Concept

A lot of “integration” articles stay too abstract. This repo avoids that problem in three ways.

First, it makes the session-to-context mapping explicit.

Second, it includes a mock remote A2A agent so you can test the flow without needing a large external setup.

Third, it includes a test that checks the most important invariant: repeated delegations from one local OpenClaw session reuse the same A2A context.

That is the piece I most wanted to make concrete, because it is where architecture turns into implementation.

How the Proof of Concept Maps to a Real OpenClaw Plugin

The proof of concept is the relay core.

A real OpenClaw plugin would wrap that relay with four extension surfaces that the OpenClaw docs already describe.

1: A Delegation Tool

This is the main entry point.

A plugin would register an optional tool like a2a_delegate so the local agent can explicitly choose to delegate work.

That tool should be optional, not always-on, because remote delegation is a side effect and should be easy to disable.

2: A Gateway Method for Diagnostics

A method like a2a.status would let you inspect whether the relay is healthy, which remote cards are cached, and whether any tasks are still being tracked.

That is much better than asking the model to “tell me if the bridge is healthy.”

3: A Plugin HTTP Route

You may not need this on day one.

But once you move beyond polling and want push-style callbacks or webhook verification, a plugin route gives you the right boundary for that work.

4: A Background Service

A small service is a clean place to do cache warming, cleanup, or later subscription handling.

That keeps the tool path focused on delegation instead of maintenance work.

If I were turning this into a real plugin package, I would sequence the work in this order:

1. wrap the relay in registerTool,

2. add a small config schema with an allowlist of remote agents,

3. add a2a.status,

4. keep polling as the first async model,

5. add a callback route only if a real use case needs it.

That is the most practical path from theory to a real extension.

I tested the relay flow locally with the mock remote agent and confirmed that repeated delegations from the same local session reused the same remote contextId.

Security Notes Before You Go Further

This is the section you should not skip.

The OpenClaw security docs explicitly say the project assumes a personal assistant trust model: one trusted operator boundary per Gateway. They also say a shared Gateway for mutually untrusted or adversarial users is not the supported boundary model.

That has a direct consequence for A2A.

A2A is designed for communication across agent systems and organizational boundaries. That is powerful, but it is also a different threat model from a single private OpenClaw deployment.

So the safer design is not this:

• expose your personal OpenClaw Gateway publicly,

• let arbitrary remote agents reach it,

• and hope the tool boundaries are enough.

The safer design is closer to this:

This diagram shows two separate trust boundaries.

On the left is your private OpenClaw deployment. This includes your Gateway, your sessions, your workspace, and any credentials or tools your agent can access. This boundary is designed for a single trusted operator.

On the right is the external A2A ecosystem, where remote agents live. These agents may belong to other teams or organizations and operate under different security assumptions.

The key idea is that communication between these two sides should happen through a controlled relay layer, not by directly exposing your OpenClaw Gateway. The relay enforces allowlists, limits what data is sent out, and ensures that remote agents cannot directly access your local tools or state.

This separation lets you experiment with agent interoperability while keeping your personal assistant environment safe.

In plain English, keep your personal assistant boundary private.

If you experiment with A2A, treat that as a separate exposure boundary with its own allowlists, auth, and operational controls.

That is why the proof-of-concept relay in this article starts with an explicit remote allowlist.

Why This Design and Not the Other One?

A natural question is why this article proposes an outbound-only A2A bridge first, instead of immediately building a full bidirectional or server-style integration.

The short answer is that OpenClaw’s current design is centered around a personal assistant trust boundary, where one operator controls the Gateway, sessions, and tools. Introducing external agents into that environment requires careful control over what is exposed.

Starting with outbound delegation gives you a safer and more incremental path.

Outbound-only first means:

• preserving the personal-assistant trust boundary, so your local OpenClaw deployment remains private and operator-controlled

• avoiding exposing the OpenClaw Gateway as a public A2A server before you have strong auth, policy, and monitoring in place

• allowing you to test remote delegation patterns (Agent Cards, tasks, artifacts) without committing to full interoperability complexity

• keeping OpenClaw as the user-facing control plane, while remote agents act as optional specialists

This approach follows a common systems design pattern: start with controlled outbound integration, validate behavior and constraints, and only then consider expanding to inbound or bidirectional communication.

In practice, this means you can experiment with A2A safely, learn how the models fit together, and evolve the system without introducing unnecessary risk early on.

Final Thoughts

OpenClaw is worth learning because it gives you a self-hosted assistant that can live in the communication tools you already use.

The simplest beginner path is still the right one:

1. install it,

2. run onboarding,

3. check the Gateway,

4. open the dashboard,

5. try one private workflow.

That is already a real end-to-end setup.

A2A belongs in the conversation because it gives you a credible way to connect OpenClaw to remote specialist agents later.

But the most important thing in this article isn't the buzzword. It's the boundary design.

If you keep OpenClaw as the private user-facing edge and use a narrow plugin bridge for outbound delegation, the OpenClaw session model and the A2A task model can fit together cleanly.

That is the architectural idea I wanted to make concrete here.

Diagram Attribution

All diagrams in this article were created by the author specifically for this guide.

Further Reading

• OpenClaw docs home

• OpenClaw Getting Started

• OpenClaw Onboarding Wizard

• OpenClaw Multi-Agent Routing

• OpenClaw Session Tools

• OpenClaw Plugin System

• OpenClaw Plugin Agent Tools

• OpenClaw ACP bridge

• OpenClaw Security

• A2A specification

• A2A Agent Discovery

• A2A and MCP

• A2A protocol definition and schema

• A2A version 1.0 announcement

Personalization is one of the most requested features in AI-powered applications. Users expect an agent to remember their preferences, adapt to their style, and improve over time.

In practice, personalization is unfortunately also one of the fastest ways to break an otherwise working AI agent.

Many agents start with a simple idea: keep adding more conversation history to the prompt. This approach works for demos, but it quickly fails in real applications. Context windows grow too large. Irrelevant information leaks into decisions. Costs increase. Debugging becomes nearly impossible.

If you want a personalized agent that survives production, you need more than a large language model. You need a way to connect the agent to tools, manage multi-step workflows, and store user preferences safely over time – without turning your system into a tangled mess of prompts and callbacks.

In this tutorial, you’ll learn how to design a personalized AI agent using three core building blocks:

• Agent Development Kit (ADK) to orchestrate agent reasoning and execution

• Model Context Protocol (MCP) to connect tools with clear boundaries

• Long-term memory to store preferences without polluting context

Rather than focusing on setup commands or vendor-specific walkthroughs, we'll focus on the architectural patterns that make personalized agents reliable, debuggable, and maintainable.

Figure 1 — Personalization influences agent responses

Table of Contents

• Prerequisites

• What “Personalized” Means in a Real AI Agent

• How the Agent Architecture Fits Together

• How to Design the Agent Core with ADK

• How to Connect Tools Safely with MCP

• How to Add Long-Term Memory Without Polluting Context

  • Privacy, Consent, and Lifecycle Controls (Production Checklist)

• How the End-to-End Agent Flow Works

• Common Pitfalls You’ll Hit (and How to Avoid Them)

• What You Learned and Where to Go Next

Prerequisites

To follow along with this tutorial, you should have:

• Basic familiarity with Python

• A general understanding of how large language models work

• Optional: a Google Cloud account if you want to run an end-to-end demo. Otherwise, you can follow the architecture and code patterns locally with stubs. We’ll avoid deep infrastructure setup and focus on design patterns rather than deployment mechanics.

You don’t need prior experience with ADK or MCP. I’ll introduce each concept as it appears.

What “Personalized” Means in a Real AI Agent

Figure 2 — Keep preferences out of the prompt: agent ↔ tools across a protocol boundary

Before writing any code, it’s important to define what personalization means in an AI agent.

Personalization is not the same as “remembering everything.” In practice, agent state usually falls into three categories:

1. Short-term context: Information needed to complete the current task. This belongs in the prompt.

2. Session state: Temporary decisions or selections made during a workflow. This should be structured and scoped to a session.

3. Long-term memory: Durable user preferences or facts that should persist across sessions.

Figure 3 — Three kinds of agent state: context (now), session (today), memory (always)

Most problems happen when these categories are mixed together.

If you store long-term preferences directly in the prompt, the agent’s behavior becomes unpredictable. If you store everything permanently, memory grows without bounds. If you don’t scope memory at all, unrelated sessions start influencing each other.

A well-designed, personalized agent treats memory as a first-class system component, not as extra text added to a prompt.

In the next section, we'll look at how to structure the agent so these concerns stay separated.

By the end of this tutorial, you’ll understand how to design a personalized AI agent that uses long-term memory safely, connects to tools through clear boundaries, and remains debuggable as it grows.

How the Agent Architecture Fits Together

Figure 4 — Reference architecture: agent core + tools + memory service + orchestration runtime

The above diagram shows a high-level, personalized AI agent architecture. In it, an agent core handles reasoning and planning while interacting with a tool interface layer, a long-term memory service, and an orchestration runtime.

Let’s now understand the moving parts of a personalized agent and how they interact.

At a high level, the system has four responsibilities:

1. Reasoning – deciding what to do next

2. Execution – calling tools and services

3. Memory – storing and retrieving long-term preferences

4. Boundaries – controlling what the agent is allowed to do

A common mistake you’ll see is to blur these responsibilities together. For example, letting the model decide when to write memory, or allowing tools to execute actions without clear constraints.

Instead, you'll design the system so each responsibility has a clear owner. The core components look like this:

• Agent core: Handles reasoning and planning

• Tools: Perform external actions (read or write)

• MCP layer: Defines how tools are exposed and invoked

• Memory services: Store long-term user data safely

ADK sits at the center, orchestrating how requests flow between these components. The model never directly talks to databases or services. It reasons about actions, and ADK coordinates execution.

This separation makes the system easier to reason about, debug, and extend.

How to Design the Agent Core with ADK

Before we dive in, a quick note on what ADK is.

Agent Development Kit (ADK) is an agent orchestration framework – the glue code between a large language model and your application. Instead of treating the model as a black box that directly “does things”, ADK helps you structure the agent as a system:

• The model focuses on reasoning (turning user intent, context, and memory into a structured plan)

• Your runtime stays in control of execution (deciding which tools can run, how they run, and what gets logged or persisted)

In other words, ADK is what lets you take tool calling and multi-step workflows out of a giant prompt and turn them into a maintainable and testable architecture. In this tutorial, we’ll use ADK to refer to that orchestration layer. The same patterns apply if you use a different agent framework.

Note: The following code snippets are simplified reference examples intended to illustrate architectural patterns. They’re not production-ready drop-ins.

Once you understand the architecture, you can start designing the agent core. The agent core is responsible for reasoning, not execution.

A helpful mental model is to think of the agent as a planner, not a doer. Its role is to interpret the user’s goal, consider available context and memory, and produce a structured plan that can later be executed in a controlled way.

To make this concrete, the following example shows how an agent can translate user input and memory into an explicit plan. In practice, ADK orchestrates this using a large language model, but the important idea is that the output is structured intent, not side effects.

# Reference example for illustration.

from dataclasses import dataclass
from typing import List, Dict, Any

@dataclass
class Step:
    tool: str
    args: Dict[str, Any]

@dataclass
class Plan:
    goal: str
    steps: List[Step]

def build_plan(user_text: str, memory: Dict[str, Any]) -> Plan:
    # In practice, the LLM produces this structure via ADK orchestration.
    goal = f"Help user: {user_text}"
    steps = []
    if memory.get("prefers_short_answers"):
        steps.append(Step(tool="set_style", args={"verbosity": "low"}))
    steps.append(Step(tool="search_docs", args={"query": user_text}))
    steps.append(Step(tool="summarize", args={"max_bullets": 5}))
    return Plan(goal=goal, steps=steps)

This example illustrates an important constraint: the agent produces a plan, but it doesn’t execute anything directly.

The agent decides what should happen and in what order, while ADK controls when and how each step runs. This separation lets you inspect, test, and reason about decisions before they result in real-world actions.

When personalization is involved, this distinction becomes critical. Preferences may influence planning, but execution should remain tightly controlled by the runtime.

Again, we can consider the agent to be a planner, not a doer.

It should not:

• Perform side effects directly

• Write to databases

• Call external APIs without supervision

In ADK, this separation is natural. The agent produces intents and tool calls, while the runtime controls how and when those calls are executed.

This design has two major benefits:

1. Safety – you can restrict which tools the agent can access

2. Debuggability – you can inspect decisions before execution

When personalization is involved, this becomes even more important. Preferences influence reasoning, but execution should remain tightly controlled.

How to Connect Tools Safely with MCP

Figure 5 — Tool calls with guardrails: request → validate → execute → respond

Tools are how agents interact with the real world. They fetch data, generate artifacts, and sometimes perform actions with side effects.

Without clear boundaries, tool usage quickly becomes a source of fragility. Hardcoded API calls leak into prompts, tools evolve independently, and agents gain more authority than intended.

To avoid these problems, tools should be explicitly registered and invoked through a narrow interface. The following example shows a simple tool registry pattern that mirrors how MCP exposes tools to an agent without tightly coupling it to implementations.

# Reference example (pseudocode for illustration)

from typing import Callable, Dict, Any

ToolFn = Callable[[Dict[str, Any]], Dict[str, Any]]

TOOLS: Dict[str, ToolFn] = {}

def register_tool(name: str):
    def decorator(fn: ToolFn):
        TOOLS[name] = fn
        return fn
    return decorator

@register_tool("search_docs")
def search_docs(args: Dict[str, Any]) -> Dict[str, Any]:
    query = args["query"]
    # Replace with your MCP client call (or local tool implementation).
    return {"results": [f"doc://example?q={query}"]}

def invoke_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
    if name not in TOOLS:
        raise ValueError(f"Tool not allowed: {name}")
    return TOOLS[name](args)

The Model Context Protocol (MCP) provides a clean way to formalize this pattern. You can think of MCP the same way operating systems treat system calls.

An application does not directly manipulate hardware. Instead, it requests operations through well-defined system calls. The kernel decides whether the operation is allowed and how it executes.

In the same way, the agent knows what capabilities exist, MCP defines how those capabilities are invoked, and the runtime controls when and whether they execute.

This separation prevents several common problems, including hardcoded API details in prompts, unexpected breakage when tools change, and agents performing unrestricted side effects.

When designing tools, it helps to classify them by risk: read tools for safe queries, generate tools for planning or synthesis, and commit tools for irreversible actions. In a personalized agent, commit tools should be rare and tightly guarded.

Figure 6 — Observability around tool calls: logs, traces, timing, decision points

How to Add Long-Term Memory Without Polluting Context

Figure 7 — Memory admission pipeline: extract → filter/validate → persist asynchronously

Memory is where personalization either succeeds or fails.

You can start by storing everything the user says and feed it back into the prompt. This works briefly, then collapses under its own weight as context grows, costs rise, and behavior becomes unpredictable.

A better approach is to treat memory as structured, curated data so you can control what the agent remembers and why with clear admission rules. Before persisting anything, the system should explicitly decide whether the information is worth remembering. The following function demonstrates a simple memory admission policy.

# Simplified Reference Only
from typing import Optional, Dict, Any

def memory_candidate(user_text: str) -> Optional[Dict[str, Any]]:
    text = user_text.lower()

    # Durable
    if "for this session" in text or "ignore after" in text:
        return None

    # Reusable
    if "my preferred language is" in text:
        return {"type": "preference", "key": "language", "value": user_text.split()[-1]}

    # Safe (basic example; add PII checks for your use case)
    if "password" in text or "ssn" in text:
        return None

    return None  # default: don’t store

This policy encodes three questions every memory candidate must answer:

• Is it durable? Will it still matter in the future?

• Is it reusable? Will it influence future decisions meaningfully?

• Is it safe to persist? Does it avoid sensitive or session-specific data?

Only information that passes all three checks should become long-term memory. In practice, this usually includes stable preferences and long-lived constraints, not temporary instructions or intermediate reasoning.

Privacy, Consent, and Lifecycle Controls (Production Checklist)

Even if your admission rules are solid, long-term memory introduces governance requirements:

• User control: allow users to view, export, and delete stored preferences at any time.

• Sensitive data handling: never store secrets/PII. Run PII detection on every memory candidate (and consider redaction).

• Retention + consent: use explicit consent for persistent memory and apply retention windows (TTL) so memory expires unless it’s still useful.

• Security + auditability: encrypt at rest, restrict access by service identity, and keep an audit log of memory writes/updates.

Memory writes should also be asynchronous. The agent should never block while persisting memory, which keeps interactions responsive and avoids coupling reasoning to storage latency.

How the End-to-End Agent Flow Works

Figure 8 — End-to-end request lifecycle: user input → plan → tools → memory updates

At this point, you can trace exactly how memory and tools interact during a single request. With the individual components in place, it’s helpful to see how they work together during a single request. The following example walks through the full lifecycle of a personalized interaction, from user input to response.

# Reference example (pseudocode for illustration)

def handle_request(user_id: str, user_text: str) -> str:
    memory = memory_store.get(user_id)  # e.g., {"prefers_short_answers": True}
    plan = build_plan(user_text, memory)

    tool_outputs = []
    for step in plan.steps:
        out = invoke_tool(step.tool, step.args)
        tool_outputs.append({step.tool: out})

    response = render_response(goal=plan.goal, tool_outputs=tool_outputs, memory=memory)

    cand = memory_candidate(user_text)
    if cand:
        # Never block the user on storage.
        memory_store.write_async(user_id, cand)
    return response

At a high level, the flow looks like this:

1. The user sends a message.

2. Relevant long-term memory is retrieved.

3. The agent reasons about the request and produces a plan.

4. ADK invokes tools through MCP as needed.

5. Results flow back to the agent.

6. The agent decides whether new information should be persisted.

7. Memory is written asynchronously.

8. The final response is returned to the user.

Notice what does not happen: the model does not directly write memory, tools do not execute without coordination, and context does not grow without bounds. This structure keeps personalization controlled and predictable.

Common Pitfalls You’ll Hit (and How to Avoid Them)

Even with a solid architecture, there are a few failure modes that show up repeatedly in real systems. Many of them stem from allowing agents to perform irreversible actions without explicit checks.

The following example shows a simple guardrail for commit-style tools that require approval before execution.

# Reference example (pseudocode for illustration)

def invoke_commit_tool(name: str, args: Dict[str, Any], approved: bool) -> Dict[str, Any]:
    if not approved:
        # Require explicit confirmation or policy approval before side effects.
        return {"status": "blocked", "reason": "commit tools require approval"}

    # For example: create_ticket, send_email, submit_order, update_record
    return invoke_tool(name, args)

This pattern forces a clear decision point before side effects occur. It also creates an audit trail that explains why an action was allowed or blocked.

Other common pitfalls include over-personalization, leaky memory that persists session-specific data, uncontrolled tool growth, and debugging blind spots caused by unclear boundaries. If you see these symptoms, it usually means responsibilities are not clearly separated.

What You Learned and Where to Go Next

Personalized AI agents are powerful, but they require discipline. The key insight is that personalization is a systems problem, not a prompt problem.

By separating reasoning from execution, structuring memory carefully, and using protocols like MCP to enforce boundaries, you can build agents that scale beyond demos and remain maintainable in production.

As you extend this system, resist the urge to add “just one more prompt tweak.” Instead, ask whether the change belongs in memory, tools, or orchestration.

That mindset will save you time as your agent grows in complexity.

If you’d like to continue the conversation, you can find me on LinkedIn.

*All diagrams in this article were created by the author for educational purposes.

The Singleton Design Pattern is a creational design pattern that solves this problem by ensuring that a class has exactly one instance and provides a global point of access to it.

This pattern is widely used in mobile apps, backend systems, and Flutter applications for managing shared resources such as:

• Database connections

• API clients

• Logging services

• Application configuration

• Security checks during app bootstrap

In this article, we'll explore what the Singleton pattern is, how to implement it in Flutter/Dart, its variations (eager, lazy, and factory), and physical examples. By the end, you'll understand the proper way to use this pattern effectively and avoid common pitfalls.

Table of Contents

1. Prerequisites

2. What is the Singleton Pattern?

   • When to Use the Singleton Pattern

3. How to Create a Singleton Class

   • Eager Singleton

   • Lazy Singleton

   • Choosing Between Eager and Lazy

4. Factory Constructors in the Singleton Pattern

   • What Are Factory Constructors?

   • Implementing Singleton with Factory Constructor

5. When Not to Use a Singleton

   • Why Singletons Can Be Problematic

   • Scenarios Where You Should Avoid Singletons

   • General Guidelines

6. Conclusion

Prerequisites

Before diving into this tutorial, you should have:

1. Basic understanding of the Dart programming language

2. Familiarity with Object-Oriented Programming (OOP) concepts, particularly classes and constructors

3. Basic knowledge of Flutter development (helpful but not required)

4. Understanding of static variables and methods in Dart

5. Familiarity with the concept of class instantiation

What is the Singleton Pattern?

The Singleton pattern is a creational design pattern that ensures a class has only one instance and that there is a global point of access to the instance.

Again, this is especially powerful when managing shared resources across an application.

When to Use the Singleton Pattern

You should use a Singleton when you are designing parts of your system that must exist once, such as:

1. Global app state (user session, auth token, app config)

2. Shared services (logger, API client, database connection)

3. Resource heavy logic (encryption handlers, ML models, cache manager)

4. Application boot security (run platform-specific root/jailbreak checks)

For example, in a Flutter app, Android may check developer mode or root status, while iOS checks jailbroken device state. A Singleton security class is a perfect way to enforce that these checks run once globally during app startup.

How to Create a Singleton Class

We have two major ways of creating a singleton class:

1. Eager Instantiation

2. Lazy Instantiation

Eager Singleton

This is where the Singleton is created at load time, whether it's used or not.

In this case, the instance of the singleton class as well as any initialization logic runs at load time, regardless of when this class is actually needed or used. Here's how it works:

class EagerSingleton {
  EagerSingleton._internal();
  static final EagerSingleton _instance = EagerSingleton._internal();

  static EagerSingleton get instance => _instance;

  void sayHello() => print("Hello from Eager Singleton");
}

//usage
void main() {
  // Accessing the singleton globally
  EagerSingleton.instance.sayHello();
}

How the Eager Singleton Works

Let's break down what's happening in this implementation:

First, EagerSingleton._internal() is a private named constructor (notice the underscore prefix). This prevents external code from creating new instances using EagerSingleton(). The only way to get an instance is through the controlled mechanism we're about to define.

Next, static final EagerSingleton _instance = EagerSingleton._internal(); is the key line. This creates the single instance immediately when the class is first loaded into memory. Because it's static final, it belongs to the class itself (not any particular instance) and can only be assigned once. The instance is created right here, at declaration time.

The static EagerSingleton get instance => _instance; getter provides global access to that single instance. Whenever you call EagerSingleton.instance anywhere in your code, you're getting the exact same object that was created when the class loaded.

Finally, sayHello() is just a regular method to demonstrate that the singleton works. You could replace this with any business logic your singleton needs to perform.

When you run the code in main(), the class loads, the instance is created immediately, and EagerSingleton.instance.sayHello() accesses that pre-created instance to call the method.

Pros:

1. This is simple and thread safe, meaning it's not affected by concurrency, especially when your app runs on multithreads.

2. It's ideal if the instance is lightweight and may be accessed frequently.

Cons:

1. If this instance is never used through the runtime, it results in wasted memory and could impact application performance.

Lazy Singleton

In this case, the singleton instance is only created when the class is called or needed in runtime. Here, a trigger needs to happen before the instance is created. Let's see an example:

class LazySingleton {
  LazySingleton._internal(); 
  static LazySingleton? _instance;

  static LazySingleton get instance {
    _instance ??= LazySingleton._internal();
    return _instance!;
  }

  void sayHello() => print("Hello from LazySingleton");
}

//usage 
void main() {
  // Accessing the singleton globally
  LazySingleton.instance.sayHello();
}

How the Lazy Singleton Works

The lazy implementation differs from eager in one crucial way: timing.

Again, LazySingleton._internal() is a private constructor that prevents external instantiation.

But notice that static LazySingleton? _instance; is declared as nullable and not initialized. Unlike the eager version, no instance is created at load time. The variable simply exists as null until it's needed.

The magic happens in the getter: _instance ??= LazySingleton._internal(); uses Dart's null-aware assignment operator. This line says "if _instance is null, create a new instance and assign it. Otherwise, keep the existing one." This is the lazy initialization: the instance is only created the first time someone accesses it.

The first time you call LazySingleton.instance, _instance is null, so a new instance is created. Every subsequent call finds that _instance already exists, so it just returns that same instance.

The return _instance!; uses the null assertion operator because we know _instance will never be null at this point (we just ensured it's not null in the previous line).

This approach saves memory because if you never call LazySingleton.instance in your app, the instance never gets created.

Pros:

1. Saves application memory, as it only creates what is needed in runtime.

2. Avoids memory leaks.

3. Is ideal for resource heavy objects while considering application performance.

Cons:

1. Could be difficult to manage in multithreaded environments, as you have to ensure thread safety while following this pattern.

Choosing Between Eager and Lazy

Now that we've broken down these two major types of singleton instantiation, it's worthy of note that you'll need to be intentional while deciding whether to create a singleton the eager or lazy way. Your use case/context should help you determine what singleton pattern you need to apply during object creation.

As an engineer, you need to ask yourself these questions when using a singleton for object creation:

1. Do I need this class instantiated when the app loads?

2. Based on the user journey, will this class always be needed during every session?

3. Can a user journey be completed without needing to call any logic in this class?

These three questions will determine what pattern (eager or lazy) you should use to fulfill best practices while maintaining scalability and high performance in your application.

Factory Constructors in the Singleton Pattern

Applying factory constructors in the Singleton pattern can be powerful if you use them properly. But first, let's understand what factory constructors are.

What Are Factory Constructors?

A factory constructor in Dart is a special type of constructor that doesn't always create a new instance of its class. Unlike regular constructors that must return a new instance, factory constructors can:

1. Return an existing instance (perfect for singletons)

2. Return a subclass instance

3. Apply logic before deciding what to return

4. Perform validation or initialization before returning an object

The factory keyword tells Dart that this constructor has the flexibility to return any instance of the class (or its subtypes), not necessarily a fresh one.

Implementing Singleton with Factory Constructor

This allows you to apply initialization logic while your class instance is being created before returning the instance.

class FactoryLazySingleton {
  FactoryLazySingleton._internal();
  static final FactoryLazySingleton _instance = FactoryLazySingleton._internal();

  static FactoryLazySingleton get instance => _instance;

  factory FactoryLazySingleton() {
    // Your logic runs here
    print("Factory constructor called");
    return _instance;
  }
}

How the Factory Constructor Singleton Works

This implementation combines aspects of both eager and lazy patterns with additional control.

The FactoryLazySingleton._internal() private constructor and static final _instance create an eager singleton. The instance is created immediately when the class loads.

The static get instance provides the traditional singleton access pattern we've seen before.

But the interesting part is the factory FactoryLazySingleton() constructor. This is a public constructor that looks like a normal constructor call, but behaves differently. When you call FactoryLazySingleton(), instead of creating a new instance, it runs whatever logic you've placed inside (in this case, a print statement), then returns the existing _instance.

This pattern is powerful because:

1. You can log when someone tries to create an instance

2. You can validate conditions before returning the instance

3. You can apply configuration based on parameters passed to the factory

4. You can choose to return different singleton instances based on conditions

For example, you might have different configuration singletons for development vs production:

factory FactoryLazySingleton({bool isProduction = false}) {
  if (isProduction) {
    // Apply production configuration
    _instance.configure(productionSettings);
  } else {
    // Apply development configuration
    _instance.configure(devSettings);
  }
  return _instance;
}

Pros

1. You can add logic before returning an instance

2. You can cache or reuse the same object

3. You can dynamically return a subtype if needed

4. You avoid unnecessary instantiation

5. You can inject configuration or environment logic

Cons

1. Adds slight complexity compared to simple getter access

2. The factory constructor syntax might confuse developers unfamiliar with the pattern

3. If overused with complex logic, it can make debugging harder

4. Can create misleading code where FactoryLazySingleton() looks like it creates a new instance but doesn't

When Not to Use a Singleton

While singletons are powerful, they're not always the right solution. Understanding when to avoid them is just as important as knowing when to use them.

Why Singletons Can Be Problematic

Singletons create global state, which can make your application harder to reason about and test. They introduce tight coupling between components that shouldn't necessarily know about each other, and they can make it difficult to isolate components for unit testing.

Scenarios Where You Should Avoid Singletons

Avoid using the Singleton pattern if:

You need multiple independent instances

If different parts of your app need their own separate configurations or states, singletons force you into a one-size-fits-all approach.

For example, if you're building a multi-tenant application where each tenant needs isolated data, a singleton would cause data to bleed between tenants.

Alternative: Use dependency injection to pass different instances to different parts of your app. Each component receives the specific instance it needs through its constructor or a service locator.

// Instead of singleton
class UserRepository {
  final DatabaseConnection db;
  UserRepository(this.db); 
}

// Usage
final dbForTenantA = DatabaseConnection(tenantId: 'A');
final dbForTenantB = DatabaseConnection(tenantId: 'B');
final repoA = UserRepository(dbForTenantA);
final repoB = UserRepository(dbForTenantB);

Your architecture avoids shared global state

Modern architectural patterns like BLoC, Provider, or Riverpod in Flutter specifically aim to avoid global mutable state. Singletons work against these patterns by reintroducing global state.

Alternative: Use state management solutions designed for Flutter. Provider, Riverpod, BLoC, or GetX offer better ways to share data across your app while maintaining testability and avoiding tight coupling.

// Using Provider instead of singleton
class AppConfig {
  final String apiUrl;
  AppConfig(this.apiUrl);
}

// Provide it at the top level
void main() {
  runApp(
    Provider<AppConfig>(
      create: (_) => AppConfig('https://api.example.com'),
      child: MyApp(),
    ),
  );
}

// Access it anywhere in the widget tree
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final config = Provider.of<AppConfig>(context);

  }
}

It forces tight coupling between unrelated classes

When multiple unrelated classes depend on the same singleton, they become indirectly coupled. Changes to the singleton affect all these classes, making the codebase fragile and hard to refactor.

Alternative: Use interfaces and dependency injection. Define what behavior you need through an interface, then inject implementations. This way, classes depend on abstractions, not concrete singletons.

// Define an interface
abstract class Logger {
  void log(String message);
}

// Implementation
class ConsoleLogger implements Logger {
  @override
  void log(String message) => print(message);
}

// Classes depend on the interface, not a singleton
class PaymentService {
  final Logger logger;
  PaymentService(this.logger);

  void processPayment() {
    logger.log('Processing payment');
  }
}

// Easy to test with mock
class MockLogger implements Logger {
  List<String> logs = [];
  @override
  void log(String message) => logs.add(message);
}

You need clean, isolated testing

Singletons maintain state between tests, causing test pollution where one test affects another. This makes tests unreliable and order-dependent.

Alternative: Use dependency injection and create fresh instances for each test. Most testing frameworks support this pattern, allowing you to inject mocks or fakes easily.

// Testable code
class OrderService {
  final PaymentProcessor processor;
  OrderService(this.processor);
}

// In tests
void main() {
  test('processes order successfully', () {
    final mockProcessor = MockPaymentProcessor();
    final service = OrderService(mockProcessor); 

  });
}

General Guidelines

Use singletons sparingly and only when you truly need exactly one instance of something for the entire application lifecycle. Good candidates include logging systems, application-level configuration, and hardware interface managers.

For most other cases, prefer dependency injection, state management solutions, or simply passing instances where needed. These approaches make your code more flexible, testable, and maintainable.

Conclusion

The Singleton pattern is a powerful creational tool, but like every tool, you should use it strategically.

Overusing singletons can make apps tightly coupled, hard to test, and less maintainable.

But when used correctly, the Singleton pattern helps you save memory, enforce consistency, and control object lifecycle beautifully.

The key is understanding your specific use case and choosing the right implementation approach – whether eager, lazy, or factory-based – that best serves your application's needs while maintaining clean, testable code.

As an IT support officer, I can put myself in the perspective of a user and identify friction points, but this document had no visuals, no simplified explanations, just walls of backend jargon: service mesh, container orchestration, async queues, REST APIs… you name it.

I realized quickly: if someone like me struggles to understand this, so will PMs, frontend devs, new hires, and even other IT staff.

Here’s a practical guide for creating system architecture documentation that anyone on your team can read and use:

• Step 1: Show the System from Different Angles

• Step 2: Make Diagrams the Star

• Step 3: Translate Tech Into User-Relevant Outcomes

• Step 4: Make Communication Clear

• Step 5: Keep it Simple and Consistent

• System Architecture Documentation Tools for Teams

• Conclusion

Step 1: Show the System from Different Angles

A good architecture doc isn’t just a list of tech terms. Think about who is reading it:

A. Conceptual View (PM/UX/business folks)

• What the system does for the user.

• Example: “User Authentication System,” “Checkout Service”

• Focus on user value and business goals.

B. Component View (frontend developers/IT staff)

• How the parts interact.

• Example: “Web App calls API Gateway → Microservice → Database”

• Focus on data flow and system boundaries.

C. Operational View (backend/DevOps)

• Where the system runs and how.

• Example: servers, databases, cloud setup, scaling.

• Focus on infrastructure and deployment.

This way, everyone can find what’s relevant to their role without getting lost in technical weeds.

Step 2: Make Diagrams the Star

Words alone don’t cut it. Diagrams help people visualize the system, especially if they’re not experts.

Types of Diagrams to Include

• System Context Diagram: Shows the system and its external dependencies. UX/PM/IT staff can see how it touches users and other systems.

• Container Diagram: Shows main boundaries like “Web App,” “Auth API,” “Database.” Frontend and backend teams benefit.

• UML/Component Diagram: Shows internal structure or interactions. Mostly backend focus, but helps everyone understand flow.

Tip: Even a simple flowchart drawn in PowerPoint, Figma, or by hand is better than none. Clarity matters more than perfection.

Diagrams help:

• UX sees user impact.

• Frontend knows which services to hook up.

• Backend sees infrastructure and interactions.

• Everyone shares the same mental picture.

Example 1: System Context Diagram

This diagram illustrates who uses the system (a person on the web) and which external services it depends on, like Stripe for payments and SendGrid for emails. It doesn't show the internal workings of the system, just what it connects to.

Example 2: Container Diagram

This diagram illustrates the main components of the system: the Web App, which is the user interface; the Auth API, responsible for handling login and security; and the User Database, where user profiles are stored. The arrows indicate how these components interact with each other.

Practical Tip: Tools to Create Clear Architecture Docs.

Step 3: Translate Tech Into User-Relevant Outcomes

System architecture goes beyond databases and queues, focusing on making the product fast, reliable, and secure for users. Link technical requirements to outcomes everyone can understand:

Even a person with basic UX awareness can see why tech decisions matter.

Step 4: Make Communication Clear

One major source of confusion is how different parts of the system talk to each other. Spell it out:

a) Frontend ↔ Backend: Clearly explain how your frontend connects to the backend.

Example: “The website sends login requests to the Auth API.”

b) Backend ↔ Backend: Explain whether services communicate with each other instantly (synchronous) or through background tasks like message queues (asynchronous). This helps the team understand why some actions feel instant to users, while others take time.

Even non-backend readers can follow the flow and understand how it impacts the product.

Step 5: Keep it Simple and Consistent

• Use headings, bullet points, and a table of contents. Don’t write a novel.

• Keep names consistent: “User Service” in diagrams should match text labels.

• Explain the “why” behind major decisions:

“We chose a NoSQL DB for User Profiles because it requires fast read/write for non-relational data.”

Consistency and simplicity make the doc useful to everyone, not just backend experts.

System Architecture Documentation Tools for Teams

Great architecture documentation lives where your team already works and uses tools that are easy to update, share, and understand. Below are the common types of tools teams use, grouped by purpose.

Documentation Platforms (Where You Write the Full Doc)

You can use these tools to combine text, diagrams, and structure a document.

Google Docs
Simple, familiar, and collaborative. Supports real-time comments, edit history, and easy sharing. Perfect if your team already uses Gmail or Drive. Just paste diagrams as images.

Confluence
Common in larger companies. Integrates with Jira, supports page templates, and lets you embed diagrams. Good for structured knowledge bases.

Notion
Flexible workspace for small teams. Mix docs, tasks, and diagrams in one place. Great if your team uses Notion for other work.

GitHub/GitLab Wikis (with Markdown)
Ideal for engineering-heavy teams. Docs live next to your code, and you can include diagrams using simple code (like Mermaid). Changes are tracked like code.

Start with Google Docs if you’re unsure. A living doc people actually read is better than a “perfect” one no one opens.

Diagramming Tools (Where You Create Visuals)

These help you draw the architecture diagrams you’ll add to your documentation platform.

Draw.io
Free, browser-based, and drag-and-drop simple. No sign-up needed. Exports clean PNG/SVG files you can paste into Docs or Confluence. Great for C4-style diagrams (System Context, Container, and so on).

Figma
If your team already uses Figma for design, you can create architecture diagrams using basic shapes and arrows. Real-time commenting makes feedback easy. Just export as PNG for Docs.

Mermaid (Diagrams as Code)
Write simple text like User --> Web App, and it becomes a diagram. Works in GitHub, GitLab, and tools like Obsidian. Use the Mermaid Live Editor to design, then download and paste into Google Docs.

A Key Insight from Practicing Architects.

Avoid tools that only produce static images (like PowerPoint, Canva, or basic whiteboards) for anything beyond quick sketches. If the same service appears in three diagrams and you rename it, you’ll have to update all three manually, leading to outdated and inconsistent docs.

How They Work Together

1. Write your doc in Google Docs (or your team’s existing platform).

2. Create diagrams in Draw.io or Figma (or try Mermaid if you’re curious).

3. Paste the diagram into your doc, add alt text, and explain what it shows in plain language.

This combo gives you accessibility, collaboration, and maintainability without overwhelming you or your team.

Conclusion

You don’t need to be a senior engineer to write great architecture docs. You just need clarity, empathy, and the willingness to explain “why.”

Instead of relying on direct calls between components, event-driven systems communicate through events – messages that signal that something has happened.

JavaScript, with its inherently asynchronous nature and built-in event loop, is a natural fit for this paradigm. From browser interactions to backend microservices, event-based communication enables flexibility, performance, and maintainability across the entire stack.

This handbook explores how event-driven architectures work, how they can be implemented in JavaScript (both in Node.js and in the browser), and why they are foundational to building modern distributed applications.

Prerequisites: What you should already know

• JavaScript fundamentals (ES6+): modules, classes, closures, this

• Asynchronous JS: callbacks, Promises, async/await, and the event loop

• Node.js basics

Table of Contents

• 1. Introduction

  • What Is an Event-Driven Architecture?

  • Why JavaScript Naturally Fits This Paradigm

  • Event-Driven vs. Request-Driven Architectures

  • When It Makes Sense to Use an Event-Driven Architecture

  • When It Might Not Be the Right Choice

  • Typical Business Use Cases

• 2. Fundamentals of the Event Model in JavaScript

  • The Event Loop, Task Queue, and Call Stack

  • EventEmitter and the Pub/Sub Pattern

  • EventTarget, CustomEvent, and Browser Events

  • Putting It All Together

• 3. Publisher–Subscriber (Pub/Sub) Pattern

  • Concept and Advantages of Decoupling

  • Basic Implementation in Plain JavaScript

  • Limitations and When to Use a Library

  • Summary

• 4. Implementations in Node.js

  • How to Use the Native events Module

  • Real Example: Event-Oriented Microservice

  • Error Handling and Backpressure

  • How to Build an Event Bus Across Services

  • Summary

• 5. Event-Driven Microservices Architecture

  • Asynchronous Communication via Message Brokers

  • Example: Order → Inventory → Notification Flow

  • Designing Event Contracts (Event Schemas)

  • When to Use an Event-Driven Microservice Architecture

  • Summary

• 6. Frontend Applications and Events

  • Custom Events in the Browser

  • Event Communication in Modern Frameworks

  • Real-Time Architectures: WebSockets and Server-Sent Events

  • Summary

• 7. Event Sourcing and CQRS (Command Query Responsibility Segregation)

  • Event Sourcing: The Core Idea

  • Example: Reconstructing State from Events

  • CQRS: Command Query Responsibility Segregation

  • Difference Between Event Sourcing and Pub/Sub

  • When to Use Event Sourcing and CQRS

  • Summary

• 8. Benefits and Challenges

  • Benefits of EDA

  • Challenges of EDA

  • Summary

• 9. Real-World Use Cases

  • 1. Financial and Banking Systems

  • 2. E-commerce Platforms

  • 3. IoT and Sensor Networks

  • 4. Real-Time Analytics and Monitoring

  • 5. Social Networks and Messaging Apps

  • 6. Workflow Automation and Orchestration

  • Summary

• 10. Best Practices and Conclusions

  • 1. Version and Validate Events

  • 2. Design for Idempotency

  • 3. Keep Events Meaningful and Self-Contained

  • 4. Implement Robust Error Handling and Dead-Letter Queues

  • 5. Ensure Observability and Traceability

  • 6. Use Patterns for Reliability

  • 7. Choose the Right Broker for the Job

  • 8. Balance Event-Driven and Request-Driven Approaches

  • 9. Educate and Align the Team

  • 10. Start Small, Then Evolve

• Conclusion

1. Introduction

Software systems are becoming increasingly distributed, asynchronous, and complex. Traditional request–response architectures – where one component directly calls another and waits for a reply – often create tight coupling and limit scalability.

In contrast, event-driven architectures (EDA) embrace asynchrony by letting components communicate through events (messages that represent a change or an occurrence in the system). When an event happens (for example, “Order Created”), other parts of the system that care about that event can react to it independently, without knowing who triggered it or when.

This simple shift from commands to events has profound implications for scalability, resilience, and system design. It allows applications to evolve as loosely coupled collections of independent components that listen for and emit events, rather than monolithic blocks of code that depend directly on each other.

What Is an Event-Driven Architecture?

An event-driven architecture is a software design pattern where the flow of the program is determined by events. An event can be any significant change in state, like a user action, a message from another system, a sensor reading, or even an internal trigger like a database update.

In this model:

• Producers (also called emitters or publishers) generate and broadcast events.

• Consumers (or listeners or subscribers) react to those events asynchronously.

Unlike traditional request-driven systems, producers and consumers don’t directly call each other. Instead, they communicate through a mediator (like an event bus, queue, or topic), achieving loose coupling and higher flexibility.

Why JavaScript Naturally Fits This Paradigm

JavaScript was built around an event-driven model from its very beginning. In the browser, every user interaction – clicks, scrolls, network responses – is handled through events. The event loop, callback queue, and non-blocking I/O make JavaScript particularly well-suited for systems where many things happen concurrently.

In Node.js, this model extends to the backend. The EventEmitter API, asynchronous I/O, and the single-threaded event loop allow developers to write scalable services that handle thousands of concurrent connections efficiently. This makes JavaScript a natural language for implementing and experimenting with event-driven systems across the full stack, from the UI to distributed microservices.

Event-Driven vs. Request-Driven Architectures

Here’s a quick summary of the main features and differences:

Event-driven systems tend to perform better in environments that require real-time updates, asynchronous workflows, or high concurrency, such as financial transaction systems, IoT platforms, and analytics pipelines.

But adopting an Event-Driven Architecture is not a universal solution. It introduces its own complexities and is best suited to problems where loose coupling, scalability, and reactivity are primary goals.

When It Makes Sense to Use an Event-Driven Architecture

• Asynchronous or real-time requirements: When the system needs to react to changes instantly (for example, new data, user interactions, or external triggers).

• High scalability and resilience: When services must handle variable workloads independently, without blocking or waiting for each other.

• Microservices or distributed systems: When independent services must communicate without strong dependencies or shared state.

• Extensibility and flexibility: When you expect the system to evolve over time, adding new consumers without modifying existing producers.

• Data streaming or continuous processing: When the system processes streams of events (for example, telemetry, logs, or payments) rather than discrete requests.

When It Might Not Be the Right Choice

• Simple, synchronous applications: For small systems where interactions are linear (for example, a CRUD API or a small monolith), introducing an event bus may be unnecessary overhead.

• Strong consistency requirements; When the system must maintain a strict order of operations or immediate transactional integrity, asynchronous event flows can complicate data coherence.

• Limited observability or operational tooling: Debugging distributed events is harder – tracing and replaying events requires good logging and monitoring infrastructure.

• Team inexperience: If the development team is not familiar with asynchronous systems, event versioning, or message brokers, the cognitive load may outweigh the benefits.

Typical Business Use Cases

1. E-commerce platforms: Events like OrderPlaced, PaymentProcessed, ItemShipped trigger workflows across inventory, billing, and logistics services.

2. Financial and banking systems: Real-time updates of transactions, fraud detection, and asynchronous settlement processing.

3. IoT and telemetry processing: Devices emit data continuously. The backend aggregates, filters, and reacts to these events asynchronously.

4. Streaming analytics and monitoring: Continuous event ingestion from applications or sensors to update dashboards and trigger alerts.

5. Social networks and messaging apps: Notifications, chat updates, and activity feeds naturally map to event streams that multiple consumers can subscribe to.

6. Workflow orchestration systems: Each step in a process (for example, document signed, email sent, approval granted) triggers subsequent actions automatically.

Event-driven architectures change the way we think about program flow. Instead of pulling data or waiting for responses, components react to what’s happening in the system.

By leveraging JavaScript’s asynchronous foundations, like the event loop, promises, and non-blocking I/O, developers can build architectures that are more responsive, resilient, and scalable than traditional request-driven designs.

In the next section, we’ll dive deeper into how JavaScript’s event model works, exploring the event loop, the task queue, and the key mechanisms (like EventEmitter) that make this paradigm possible.

2. Fundamentals of the Event Model in JavaScript

JavaScript is inherently event-driven. From its earliest days in the browser to its modern incarnation on the server with Node.js, the language has been designed to handle asynchronous operations gracefully through events – signals that something has happened.

Understanding how this works under the hood is essential before applying event-driven principles to large systems.

The Event Loop, Task Queue, and Call Stack

At the heart of JavaScript’s concurrency model lies the event loop, a mechanism that enables asynchronous, non-blocking behavior in a single-threaded environment.

Let’s break it down:

1. Call Stack: This is where JavaScript executes code line by line. Each function call creates a new frame on the stack.

2. Task Queue (or Callback Queue): When asynchronous operations finish (like a setTimeout or a network request), their callbacks are queued here for later execution.

3. Event Loop: Constantly checks if the call stack is empty. When it is, the loop dequeues a task and pushes it onto the stack to execute.

This cycle repeats indefinitely – hence the term “event loop.”

console.log("A");

setTimeout(() => {
  console.log("B");
}, 0);

console.log("C");

// Output:
// A
// C
// B

Even though the timeout is 0, the callback runs after the synchronous code because it’s queued in the task queue and executed only when the call stack is clear.

This model allows JavaScript to remain responsive and non-blocking, even while performing I/O operations or waiting for user input.

EventEmitter and the Pub/Sub Pattern

Node.js exposes its event-driven core through the EventEmitter class – one of its most fundamental building blocks.

An EventEmitter lets objects emit events and subscribe to them. This mechanism forms the foundation for countless Node.js APIs, from HTTP servers to file streams.

Here’s a simple example:

const EventEmitter = require('events');
const emitter = new EventEmitter();

// Subscriber (listener)
emitter.on('dataReceived', (data) => {
  console.log(`Data received: ${data}`);
});

// Publisher (emitter)
emitter.emit('dataReceived', 'User profile loaded');

Output:

Data received: User profile loaded

Each event has:

• A name (string or symbol)

• A set of listeners (functions) that react to it

This is the classic Publisher–Subscriber pattern (Pub/Sub): components publish events, while others subscribe to react – without direct references to each other.

EventTarget, CustomEvent, and Browser Events

In the browser, the same concept exists through the EventTarget API. Every DOM element can listen for or dispatch events.

const button = document.querySelector('button');

button.addEventListener('click', () => {
  console.log('Button clicked!');
});

We can also create custom events to simulate our own event-driven behavior:

const userEvent = new CustomEvent('userLoggedIn', {
  detail: { name: 'Alice' }
});

document.addEventListener('userLoggedIn', (e) => {
  console.log(`Welcome, ${e.detail.name}!`);
});

document.dispatchEvent(userEvent);

Output:

Welcome, Alice!

This lightweight mechanism allows front-end applications to coordinate behavior across components without tight coupling.

Putting It All Together

Whether in the browser or Node.js, JavaScript’s asynchronous runtime and event-driven APIs form a natural foundation for building reactive, modular, and scalable systems.

In Node.js, nearly everything is an event emitter – HTTP requests, streams, process signals, and even errors. In the browser, events are how users and systems interact through clicks, network responses, and state changes.

This unified model across client and server is what makes JavaScript uniquely powerful for implementing end-to-end event-driven architectures.

In the next section, we’ll explore the Pub/Sub pattern in depth: we’ll understand its advantages, pitfalls, and how to implement it cleanly in plain JavaScript before scaling up to distributed systems.

3. Publisher–Subscriber (Pub/Sub) Pattern

The Publisher–Subscriber pattern, often abbreviated as Pub/Sub, is one of the most common and powerful foundations of event-driven systems. It defines how components can communicate asynchronously without knowing each other directly – a principle known as loose coupling.

In a Pub/Sub model:

• Publishers (or emitters) broadcast events.

• Subscribers (or listeners) register interest in those events.

• A broker (or event bus) acts as a mediator between the two.

This separation allows systems to evolve and scale independently: new subscribers can be added without changing the publishers, and vice versa.

Concept and Advantages of Decoupling

In traditional architectures, one component often depends directly on another:

function processOrder(order) {
  sendInvoice(order);
  notifyWarehouse(order);
}

Here, processOrder is tightly coupled to the functions it calls. If we later need to send a shipping confirmation or trigger analytics, we must modify processOrder again. This violates the Open/Closed Principle (open for extension, closed for modification).

In a Pub/Sub model, the same logic becomes event-driven:

const EventEmitter = require('events');
const bus = new EventEmitter();

bus.on('order:created', sendInvoice);
bus.on('order:created', notifyWarehouse);

bus.emit('order:created', { id: 42, items: 3 });

Now, processOrder doesn’t need to know who’s listening. It simply emits an event (order:created), and any number of subscribers can react to it – even ones that didn’t exist when the code was written.

Advantages:

• ✅ Loose coupling between components

• ⚙️ Easier extensibility: add new behaviors by adding listeners

• 🚀 Parallel evolution: teams can work on producers and consumers independently

• 🧩 Greater testability: events can be simulated in isolation

Basic Implementation in Plain JavaScript

While Node.js provides a ready-to-use EventEmitter, you can easily build a minimal event bus in plain JavaScript. This helps illustrate the underlying logic:

function createEventBus() {
  const listeners = {};

  return {
    subscribe(event, callback) {
      if (!listeners[event]) listeners[event] = [];
      listeners[event].push(callback);
    },
    publish(event, data) {
      (listeners[event] || []).forEach((callback) => callback(data));
    },
    unsubscribe(event, callback) {
      listeners[event] = (listeners[event] || []).filter((cb) => cb !== callback);
    }
  };
}

// Example usage
const bus = createEventBus();

function onUserRegistered(user) {
  console.log(`Welcome, ${user.name}!`);
}

bus.subscribe('user:registered', onUserRegistered);
bus.publish('user:registered', { name: 'Alice' });
bus.unsubscribe('user:registered', onUserRegistered);

This simple implementation already captures the essence of Pub/Sub:

• You can subscribe to an event.

• You can publish events with data.

• You can unsubscribe dynamically.

Limitations and When to Use a Library

While the above implementation works for small-scale use, real-world systems often require:

• Wildcard or hierarchical event names (for example, order.* or user.created)

• Asynchronous delivery (with message queues or brokers)

• Error handling and retries

• Event persistence or replay

• Cross-process or distributed communication

In those cases, using a dedicated library or broker is more appropriate.

Popular options include Node.js’s built-in EventEmitter for in-process events, RxJS for reactive programming and stream composition, and message brokers like RabbitMQ, Kafka, or Redis Streams for distributed, scalable architectures

Each of these tools extends the Pub/Sub model to handle larger scale, fault tolerance, and observability – essential features in modern distributed systems.

Summary

The Publisher–Subscriber pattern is the backbone of event-driven design. It transforms direct, synchronous function calls into indirect, asynchronous communications, allowing systems to evolve gracefully and handle change without friction.

In JavaScript, this pattern is everywhere – from browser DOM events to Node.js streams and microservice architectures.

In the next section, we’ll dive deeper into practical implementations in Node.js, exploring how the events module powers many of the platform’s most important features and how it can be extended to build robust, event-oriented systems.

4. Implementations in Node.js

Node.js was designed from the ground up around the event-driven paradigm. Its single-threaded, non-blocking I/O model allows it to handle thousands of concurrent operations efficiently – not by running code in parallel, but by reacting to events as they occur.

At the heart of this model lies the events module, which exposes the EventEmitter class used throughout Node’s core APIs, from HTTP servers to file streams.

How to Use the Native events Module

The EventEmitter class provides a standard way to emit and listen for events within a Node.js process.
It’s a lightweight yet powerful abstraction for asynchronous communication between components.

Let’s look at a simple example:

const EventEmitter = require('events');
const emitter = new EventEmitter();

// Register an event listener
emitter.on('user:login', (user) => {
  console.log(`User logged in: ${user.name}`);
});

// Emit the event
emitter.emit('user:login', { name: 'Alice' });

Output:

User logged in: Alice

Each EventEmitter instance maintains an internal map of event names to listener functions. Listeners can be added using .on() or .once() (for one-time execution), and events are triggered asynchronously with .emit().

Real Example: Event-Oriented Microservice

To see this in action, imagine a simplified order-processing microservice:

const EventEmitter = require('events');
const bus = new EventEmitter();

function createOrder(order) {
  console.log(`Order created: ${order.id}`);
  bus.emit('order:created', order);
}

function sendInvoice(order) {
  console.log(`Invoice sent for order ${order.id}`);
}

function updateInventory(order) {
  console.log(`Inventory updated for order ${order.id}`);
}

// Subscribe listeners
bus.on('order:created', sendInvoice);
bus.on('order:created', updateInventory);

// Simulate an order
createOrder({ id: 123, items: ['Book', 'Pen'] });

Output:

Order created: 123
Invoice sent for order 123
Inventory updated for order 123

Here, the microservice emits an order:created event whenever a new order is placed. Multiple listeners (invoice and inventory handlers) react independently – a miniature event-driven architecture in a single process.

This approach scales naturally as the system grows. New behaviors, like sending notifications or analytics tracking, can be added by simply subscribing new listeners.

Error Handling and Backpressure

In event-driven systems, error management is crucial because unhandled exceptions inside event listeners can crash the entire Node.js process.

To prevent this, Node provides built-in mechanisms:

1. Error events: You can emit and handle errors explicitly.

    const EventEmitter = require('events');
    const emitter = new EventEmitter();
   
    emitter.on('error', (err) => {
      console.error('An error occurred:', err.message);
    });
   
    emitter.emit('error', new Error('Database connection failed'));
   

   If an 'error' event is emitted without at least one listener, Node.js will throw it as an uncaught exception and terminate the process.

2. Backpressure management: In streaming scenarios, producers can emit data faster than consumers can handle.

   Node.js Streams solve this through backpressure, where consumers signal when they are ready for more data.

    const fs = require('fs');
    const readable = fs.createReadStream('large-file.txt');
    const writable = fs.createWriteStream('copy.txt');
   
    readable.pipe(writable); // Automatically manages flow control
   

   Under the hood, streams use event-based coordination (data, drain, end) to ensure stability even under heavy load.

How to Build an Event Bus Across Services

While EventEmitter works within a single process, real-world architectures often span multiple microservices or containers. In such cases, an external message broker (like RabbitMQ, Kafka, or Redis Streams) acts as a distributed event bus.

Each service becomes either:

• a producer (publishing events), or

• a consumer (subscribing and reacting).

Node.js integrates seamlessly with these systems using community libraries:

• amqplib for RabbitMQ

• kafkajs for Apache Kafka

• redis for Redis Pub/Sub

Example (simplified with Redis):

const { createClient } = require('redis');
const publisher = createClient();
const subscriber = createClient();

await publisher.connect();
await subscriber.connect();

subscriber.subscribe('user:created', (message) => {
  console.log(`New user event received: ${message}`);
});

await publisher.publish('user:created', JSON.stringify({ id: 1, name: 'Alice' }));

This pattern allows cross-service communication without tight coupling. Each service reacts to events asynchronously, whether it’s hosted locally or across a cluster.

Summary

The Node.js EventEmitter encapsulates the essence of event-driven design at the process level: lightweight, decoupled, and asynchronous. Combined with external message brokers, it becomes a powerful tool for building scalable, distributed event-driven systems.

Through events, Node.js applications can handle multiple concurrent workflows efficiently, maintain clear separation of concerns, and grow organically as the system evolves.

In the next section, we’ll extend this idea beyond a single application. We’ll explore Event-Driven Microservices Architecture, where multiple independent services communicate entirely through asynchronous event flows.

5. Event-Driven Microservices Architecture

As applications grow, a single event bus inside one process is no longer enough. When your system consists of multiple independently deployed services – each owning its own data and responsibilities – the Event-Driven Architecture becomes a natural fit for enabling asynchronous, decoupled communication.

In an event-driven microservice ecosystem, services don’t call each other directly through HTTP or RPC.
Instead, they publish and consume events through a message broker – a central medium that handles delivery, queuing, and persistence of messages between services.

Asynchronous Communication via Message Brokers

In a request-driven microservice system, one service directly invokes another via REST or gRPC:

Order Service  →  Inventory Service  →  Notification Service

Each call is synchronous, meaning the caller waits for a response. This creates coupling and potential cascading failures if one service is down or slow.

In an event-driven model, communication happens asynchronously through events:

Order Service  →  [Event Bus]  →  Inventory Service, Notification Service

The event bus becomes the backbone of the system. Each service publishes events and subscribes to those it needs, without knowing who will consume them.

This brings several advantages:

• ⚙️ Loose coupling: services don’t depend on each other’s availability

• 📈 Scalability: new consumers can subscribe without changing existing code

• 🔁 Resilience: temporary outages are absorbed by the broker’s queues

• 🧩 Extensibility: new workflows can be added just by listening to existing events

Example: Order → Inventory → Notification Flow

Let’s consider a practical scenario in an e-commerce platform:

1. Order Service publishes an order:created event when a user places an order.

2. Inventory Service subscribes to order:created and decrements stock.

3. Notification Service also subscribes to order:created and sends a confirmation email.

          ┌──────────────────────┐
          │   Order Service      │
          │ emits "order:created"│
          └──────────┬───────────┘
                     │
          ┌──────────▼───────────┐
          │     Event Bus        │
          │ (Kafka, RabbitMQ...) │
          └──────┬───────────────┘
      ┌──────────┴───────────┐   ┌────────────────────┐
      │ Inventory Service    │   │ Notification Service│
      │ updates stock        │   │ sends email         │
      └──────────────────────┘   └────────────────────┘

Node.js example (simplified with Redis):

// order-service.js
const { createClient } = require('redis');
const publisher = createClient();
await publisher.connect();

async function createOrder(order) {
  console.log(`Order created: ${order.id}`);
  await publisher.publish('order:created', JSON.stringify(order));
}

createOrder({ id: 42, items: ['Book', 'Pen'] });

// inventory-service.js
const { createClient } = require('redis');
const subscriber = createClient();
await subscriber.connect();

await subscriber.subscribe('order:created', (message) => {
  const order = JSON.parse(message);
  console.log(`Updating inventory for order ${order.id}`);
});

// notification-service.js
const { createClient } = require('redis');
const subscriber = createClient();
await subscriber.connect();

await subscriber.subscribe('order:created', (message) => {
  const order = JSON.parse(message);
  console.log(`Sending confirmation email for order ${order.id}`);
});

Each service is now independent. They communicate only through events, not direct calls.

Designing Event Contracts (Event Schemas)

In a distributed system, events are contracts – they define what information producers share and consumers rely on. Defining and maintaining these contracts carefully is crucial to avoid breaking downstream consumers.

A good event should:

• Contain enough context for consumers to act independently

• Use a versioned schema to evolve safely over time

• Include metadata like eventId, timestamp, and source

Example event schema (JSON):

{
  "event": "order:created",
  "version": 1,
  "timestamp": "2025-10-29T18:45:00Z",
  "data": {
    "orderId": 42,
    "userId": 123,
    "items": [
      { "sku": "BOOK-001", "quantity": 2 },
      { "sku": "PEN-003", "quantity": 1 }
    ],
    "total": 39.90
  }
}

Best practices:

• Use namespaced event types (order:created, payment:failed)

• Include a version number (v1, v2) to avoid schema drift

• Store events in a central registry (for example, JSON Schema repository)

• Log all events for auditing and debugging

When to Use an Event-Driven Microservice Architecture

Event-driven microservices are especially valuable when:

• Systems require real-time updates (for example, notifications, analytics)

• Components must operate independently and asynchronously

• The platform needs to scale horizontally across services

• New capabilities should be added without touching existing code

But this architecture also brings challenges:

• Harder to trace flows across multiple asynchronous hops

• Requires observability tools (logs, traces, metrics) to debug issues

• Event ordering and exact-once delivery can be complex

• Increased operational overhead from managing brokers and message queues

Summary

Event-driven microservices take the principles of the Pub/Sub pattern and scale them across distributed systems. By communicating exclusively through asynchronous events, services become autonomous, resilient, and extensible. This is ideal for modern cloud architectures and high-throughput applications.

In the next section, we’ll shift our focus to the front end and explore how event-driven principles power reactivity in browsers and frameworks like React and Vue, and how technologies like WebSockets and Server-Sent Events enable real-time user experiences.

6. Frontend Applications and Events

While backend systems use event-driven architectures to coordinate between services, frontend applications have relied on event-based programming since JavaScript’s creation. And again, every user interaction is handled through events.

Understanding how events flow in the browser, and how modern frameworks like React and Vue build upon this model, is key to creating responsive, decoupled, and real-time user interfaces.

Custom Events in the Browser

In vanilla JavaScript, every DOM element can emit and listen to events through the EventTarget API.
This mechanism is the foundation of how browsers handle user interaction and component communication.

Example – Basic Event Handling:

<button id="subscribeBtn">Subscribe</button>
<script>
  const btn = document.getElementById('subscribeBtn');
  btn.addEventListener('click', () => {
    console.log('User subscribed!');
  });
</script>

Here, the button acts as an event emitter. When the click event occurs, the listener function reacts. This is a simple example of publish-subscribe behavior within the DOM.

You can also define custom events to allow decoupled communication between components:

const userEvent = new CustomEvent('user:registered', {
  detail: { name: 'Alice', email: 'alice@example.com' }
});

// Listen for the event
document.addEventListener('user:registered', (e) => {
  console.log(`Welcome ${e.detail.name}!`);
});

// Dispatch it
document.dispatchEvent(userEvent);

Output:

Welcome Alice!

This approach allows different parts of the UI to react to user actions or system changes without directly calling each other.

Event Communication in Modern Frameworks

Modern JavaScript frameworks like React, Vue, and Angular abstract the native event system, but the core idea remains the same: components react to events.

React Example

React’s synthetic event system wraps the browser’s native events, providing a unified interface across browsers.

function NewsletterSignup() {
  function handleSubmit(e) {
    e.preventDefault();
    console.log('Newsletter form submitted!');
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Your email" />
      <button type="submit">Subscribe</button>
    </form>
  );
}

Behind the scenes, React uses an event delegation model: it attaches a single listener at the root and dispatches events down the component tree efficiently.

For cross-component communication, React developers often use:

• Context or state managers (like Redux, Zustand, or Recoil)

• Event emitter utilities (like mitt or nanoevents)

• Custom hooks for modular event handling

Example using a lightweight emitter (mitt):

import mitt from 'mitt';

export const bus = mitt();

Then anywhere in your app:

// Component A
bus.emit('theme:changed', 'dark');

// Component B
bus.on('theme:changed', (theme) => {
  console.log(`Theme updated to ${theme}`);
});

This simple event bus decouples components that don’t share a direct parent-child relationship.

Vue Example

Vue provides a native event system for child-to-parent communication and also supports global event buses.

<template>
  <button @click="notify">Notify Parent</button>
</template>

<script>
export default {
  methods: {
    notify() {
      this.$emit('user-registered', { name: 'Alice' });
    }
  }
};
</script>

The parent component can listen for user-registered and react accordingly. Vue 3 also supports custom event buses via external libraries like mitt, enabling component-to-component events without tight coupling.

Real-Time Architectures: WebSockets and Server-Sent Events

In modern web applications, the event-driven model extends beyond the client, connecting the front end and back end in real-time.

WebSockets

WebSockets provide a full-duplex channel between the browser and the server. This means both sides can send events at any time, enabling instant updates without polling.

Example:

const socket = new WebSocket('wss://example.com/socket');

socket.addEventListener('open', () => {
  console.log('Connected to server');
  socket.send(JSON.stringify({ event: 'user:joined', name: 'Alice' }));
});

socket.addEventListener('message', (msg) => {
  const data = JSON.parse(msg.data);
  console.log('New event from server:', data);
});

Use cases:

• Real-time chat applications

• Live dashboards

• Online multiplayer games

Server-Sent Events (SSE)

SSE is a simpler alternative when you only need one-way communication – from server to client – using standard HTTP connections.

const source = new EventSource('/events');

source.addEventListener('update', (e) => {
  const data = JSON.parse(e.data);
  console.log('Received update:', data);
});

SSE is ideal for live notifications, monitoring dashboards, and continuous data feeds.

Summary

The frontend world has always been event-driven – from DOM interactions to modern component frameworks and real-time connections.

By treating the UI as a system that reacts to events rather than polling for changes, we build interfaces that are more responsive, more modular, and easier to extend and integrate with event-driven back ends.

Whether you use CustomEvent, mitt, WebSockets, or SSE, the principle is the same: emit events, listen for changes, and let your app respond asynchronously.

In the next section, we’ll explore how these same principles extend into Event Sourcing and CQRS (Command Query Responsibility Segregation) – advanced architectural patterns that persist and reconstruct system state entirely through events.

7. Event Sourcing and CQRS (Command Query Responsibility Segregation)

Up to this point, we’ve explored events as transient messages that trigger behavior – signals passed between components or services. But in more advanced architectures, events can also become the source of truth for the system’s state itself.

This is where Event Sourcing and CQRS come into play.

These patterns are fundamental in systems that require auditability, replayability, and scalable state reconstruction, such as banking platforms, e-commerce systems, and workflow engines.

Event Sourcing: The Core Idea

In traditional architectures, a system stores only the current state: for example, a database row representing the latest balance of a user’s account.

In Event Sourcing, the system instead stores a series of events that led to that state. Each event represents a historical change, such as AccountCreated, FundsDeposited, or FundsWithdrawn.

When you need the current state, you don’t query a static record – you replay all relevant events in sequence.

Traditional Model:

Event-Sourced Model:

To calculate the balance, you replay the events:

0 + 300 + 200 = $500

This approach provides:

• 🧾 Full audit history: every state change is recorded

• 🔁 Replayability: rebuild state after crashes or schema changes

• 🧩 Temporal queries: know what the system looked like at any point in time

Example: Reconstructing State from Events

Let’s illustrate with a simple JavaScript implementation.

const events = [
  { type: 'AccountCreated', data: { id: 1, owner: 'Alice' } },
  { type: 'FundsDeposited', data: { id: 1, amount: 300 } },
  { type: 'FundsDeposited', data: { id: 1, amount: 200 } },
  { type: 'FundsWithdrawn', data: { id: 1, amount: 100 } }
];

function rebuildAccount(events) {
  let balance = 0;

  for (const event of events) {
    switch (event.type) {
      case 'FundsDeposited':
        balance += event.data.amount;
        break;
      case 'FundsWithdrawn':
        balance -= event.data.amount;
        break;
    }
  }

  return balance;
}

console.log('Current balance:', rebuildAccount(events)); // 400

Here, we never stored a static “balance” field. Instead, we reconstructed it from the sequence of past events – the same way a ledger works in accounting.

This technique is powerful for debugging, auditing, or migrating systems: you can replay all events in a new environment to rebuild state exactly as it was.

CQRS: Command Query Responsibility Segregation

CQRS (Command Query Responsibility Segregation) is a complementary pattern often used with Event Sourcing.
It separates the model for writing data (commands) from the model for reading data (queries).

• Commands modify system state by producing events (OrderPlaced, PaymentProcessed).

• Queries read data optimized for retrieval (for example, a denormalized “view” of orders).

This separation improves scalability and performance because the read and write sides can evolve independently – even use different databases.

Simplified diagram:

[User Action]
      │
      ▼
 ┌────────────┐
 │ Command API│  --->  emits --->  [Event Store]
 └────────────┘                      │
                                    ▼
                        ┌────────────────────┐
                        │  Read Model / View │
                        │ (e.g., MongoDB)    │
                        └────────────────────┘

Example (conceptual):

function placeOrder(order) {
  // Write model
  eventStore.push({ type: 'OrderPlaced', data: order });
}

function getOrdersView() {
  // Read model
  return eventStore
    .filter((e) => e.type === 'OrderPlaced')
    .map((e) => e.data);
}

Here, the event store acts as the single source of truth, while query views can be rebuilt or optimized as needed.

Difference Between Event Sourcing and Pub/Sub

It’s common to confuse Event Sourcing with simple event-driven messaging, but they solve different problems:

You can – and often should – use both together: an event-sourced service emits domain events to notify other systems.

When to Use Event Sourcing and CQRS

Use when:

• You need a complete audit trail or historical reconstruction.

• The business domain is complex and event-driven by nature (finance, logistics, IoT).

• The system requires high resilience and state recoverability.

Avoid when:

• You’re building a small, CRUD-oriented app with limited complexity.

• You don’t need event replay or full history, as it adds storage and operational overhead.

• Your team lacks experience managing distributed consistency and event evolution.

Summary

Event Sourcing and CQRS extend event-driven design to the data layer. Instead of only reacting to events, your system persists them and uses them as the foundation for rebuilding, auditing, and scaling.

This approach transforms your architecture from a static data store into a living timeline, where every change is captured as part of an ongoing story of the system’s behavior.

In the next section, we’ll analyze the benefits and challenges of event-driven architectures. We’ll explore why they scale so effectively, but also why debugging and observability can be tricky in large distributed environments.

8. Benefits and Challenges

Event-driven architectures offer remarkable scalability, resilience, and flexibility, qualities that make them a cornerstone of modern distributed systems. But these benefits come with trade-offs: debugging becomes more complex, data consistency is harder to guarantee, and operational visibility requires specialized tooling.

In this section, we’ll examine both sides — why EDAs are so powerful and what challenges teams face when implementing them.

Benefits of EDA

1. Scalability and Responsiveness

Event-driven systems naturally handle high concurrency. Because components react to events asynchronously, they can process workloads in parallel without blocking one another.

For example, in a retail platform:

• The Order Service publishes an event.

• The Inventory, Billing, and Notification services consume it concurrently.

This decoupling allows systems to scale horizontally, adding new consumers or instances without affecting existing ones.

Also, when combined with brokers like Kafka or RabbitMQ, EDAs can handle massive throughput while maintaining order and reliability.

2. Loose Coupling and Extensibility

In a traditional system, integrating new functionality often requires editing existing components. In an event-driven system, new consumers simply subscribe to existing events.

For instance, adding a new Analytics Service that listens for order:created events requires:

• No changes to the Order Service

• No disruption to other consumers

• No coordination between teams

This makes event-driven systems extensible by design, which is invaluable for large organizations with multiple teams or evolving business logic.

3. Resilience and Fault Isolation

Since communication is asynchronous, if one service fails, others can continue working. Events are buffered in the broker and delivered later.

This prevents cascading failures typical of tightly coupled, request-response systems. For example, if the Notification Service is down, orders can still be processed, and notifications will be sent once it recovers.

Many brokers also provide durable queues and retries, ensuring no event is lost even under heavy load or downtime.

4. Real-Time and Reactive Experiences

Event-driven systems power real-time applications, from chat apps and IoT platforms to fraud detection systems and live analytics dashboards.

Because events represent changes as they happen, they enable instant updates, alerts, and responsive UIs. When combined with technologies like WebSockets, Server-Sent Events, or GraphQL Subscriptions, the same model extends seamlessly to the frontend.

5. Auditability and Traceability

When paired with Event Sourcing, EDAs provide a complete audit trail of everything that has happened in the system. This is crucial for domains like finance, healthcare, or logistics, where compliance and historical accuracy are mandatory.

Challenges of EDA

1. Debugging and Tracing

Unlike synchronous systems, where a stack trace shows the full call path, event-driven systems are non-linear. An event may pass through multiple services, queues, and transformations before triggering an outcome.

This makes it difficult to answer questions like:

“Why did this event trigger twice?”
“Where did this data originate?”
“Which services consumed this message?”

To mitigate this, teams rely on distributed tracing tools such as:

• OpenTelemetry

• Jaeger

• Zipkin

• AWS X-Ray

• Kafka UI / Conduktor (for message inspection)

Embedding trace IDs in event metadata is a best practice that allows cross-service correlation of events.

2. Data Consistency

Because events are asynchronous, maintaining strict transactional consistency is challenging. For example, when an OrderPlaced event triggers multiple actions, those actions may complete at different times – or even fail independently.

To manage this, developers often use:

• Idempotent event handlers (safe to re-run)

• Outbox pattern (ensuring events are emitted only after successful database commits)

• Saga pattern (for distributed transactions and compensating actions)

These patterns add robustness but also increase system complexity.

3. Message Duplication and Ordering

In distributed systems, you must assume:

• Events may arrive twice (due to retries)

• Events may arrive out of order

Because of this, consumers need to be designed for idempotency and order independence. Many event stores or brokers (like Kafka) provide partitioning and offsets to preserve partial ordering, but global order is rarely guaranteed.

4. Operational Complexity

While adding a message broker improves decoupling, it also introduces new infrastructure to manage:

• Brokers and topics

• Retention policies

• Consumer groups

• Dead-letter queues (for failed messages)

Monitoring and maintaining these systems requires DevOps expertise and mature observability practices.

5. Team and Mental Model Shift

Event-driven systems require developers to think differently:

• Systems become reactive, not procedural.

• Data flows are eventual, not immediate.

• Debugging requires system-wide visibility, not local inspection.

For teams used to request-response logic, this transition can be difficult, requiring training, discipline, and careful design reviews.

Summary

Event-driven architectures offer:

• ⚙️ Scalability

• 🧩 Extensibility

• 🔁 Resilience

• ⚡ Real-time capabilities

But they demand:

• 🧠 Rethinking data flow

• 🔍 Better observability

• 🧰 Advanced tooling

When implemented carefully, EDAs unlock new levels of system flexibility and business agility, but success depends on balancing their power with strong governance, well-defined event contracts, and team alignment.

In the next section, we’ll look at real-world use cases, examining how leading industries like fintech, e-commerce, and IoT leverage event-driven architectures to achieve scale, responsiveness, and reliability.

9. Real-World Use Cases

Event-driven architectures are not just theoretical patterns. They power many of the systems we use every day. From instant payments to social networks, EDAs provide the backbone for handling real-time data, asynchronous workflows, and massive scalability.

Below are some of the most common and impactful use cases across different industries.

1. Financial and Banking Systems

Financial institutions rely heavily on asynchronous, reliable event flows to process millions of operations safely and in real time.

Typical Events

• TransactionInitiated

• FundsDeposited

• PaymentProcessed

• FraudAlertTriggered

How It Works

When a user initiates a payment:

1. The Payment Service emits a PaymentInitiated event.

2. The Fraud Detection Service subscribes to it, analyzing risk in parallel.

3. The Ledger Service records the transaction asynchronously.

4. The Notification Service sends confirmations.

Each component operates independently, and failures or slow responses in one don’t block others.

Benefits

• Real-time fraud detection

• Parallel transaction processing

• Clear audit trail for compliance (with Event Sourcing)

Example: Modern payment systems (like Revolut, Stripe, and PayPal) use event-driven microservices to orchestrate transactions securely and at scale.

2. E-commerce Platforms

E-commerce systems are naturally event-driven. Every customer action generates events that ripple across subsystems.

Typical Events

• OrderCreated

• ItemAddedToCart

• InventoryUpdated

• ShipmentDispatched

Event Flow Example

When a user places an order:

1. The Order Service emits OrderCreated.

2. Inventory Service reserves stock.

3. Billing Service processes the payment.

4. Shipping Service schedules delivery.

5. Analytics Service records metrics.

Each step occurs asynchronously, allowing thousands of orders to be processed concurrently.

Benefits

• High scalability during peak sales (for example, Black Friday)

• Fault isolation between modules

• Easy integration of new services (for example, loyalty or recommendation engines)

Example: Amazon and Shopify both use event-based pipelines for order management, tracking, and analytics.

3. IoT and Sensor Networks

In IoT ecosystems, thousands or millions of devices constantly emit data. Event-driven architectures are essential for ingesting, processing, and reacting to these streams efficiently.

Typical Events

• TemperatureMeasured

• DeviceConnected

• MotionDetected

• BatteryLow

Event Flow Example

1. Devices publish sensor data to a message broker (like MQTT, Kafka, or AWS IoT Core).

2. The Processing Service filters and enriches data.

3. Alert Services emit notifications if thresholds are crossed.

4. Analytics Pipelines store aggregated data for insights.

Benefits

• Real-time monitoring

• Predictive maintenance (based on event patterns)

• Scalable ingestion from thousands of sources

Example: Smart cities and connected vehicles use event-driven systems to react to sensor data in milliseconds, adjusting traffic lights, tracking fleets, or monitoring energy grids.

4. Real-Time Analytics and Monitoring

Modern analytics systems depend on stream processing, continuously ingesting and analyzing events to derive insights instantly.

Typical Events

• PageViewed

• UserLoggedIn

• MetricUpdated

Event Flow Example

1. Applications emit user interaction events to a message queue.

2. A Stream Processor (like Apache Flink or Kafka Streams) aggregates events in real time.

3. Dashboards and alerting systems consume processed results via WebSockets or APIs.

Benefits

• Live metrics and dashboards

• Early anomaly detection

• Continuous feedback loops for ML models

Example: Netflix uses event-driven data pipelines (built on Kafka) to monitor playback quality and deliver adaptive streaming experiences in real time.

5. Social Networks and Messaging Apps

Social platforms are fundamentally event-driven systems. Every post, like, message, or comment is an event that triggers updates across multiple systems.

Typical Events

• PostCreated

• MessageSent

• UserMentioned

• NotificationDelivered

Event Flow Example

When a user sends a message:

1. The Chat Service emits MessageSent.

2. The Notification Service alerts the recipient.

3. The Search Index Service updates conversations.

4. The Analytics Service logs engagement metrics.

Benefits

• Instant notifications and updates

• Asynchronous scalability across millions of users

• Modular and evolvable product features

Example: Slack, WhatsApp, and Facebook Messenger rely on distributed event buses to coordinate billions of message and presence events per day.

6. Workflow Automation and Orchestration

Workflow systems such as document approvals, CI/CD pipelines, or business processes are often built around events.

Typical Events

• TaskCreated

• TaskCompleted

• ApprovalGranted

• PipelineDeployed

How It Works

Each action in a workflow triggers the next step through events, allowing flexible orchestration without hardcoding dependencies. This makes it easy to reconfigure or extend workflows dynamically.

Example: GitHub Actions and Zapier use event-driven models to execute workflows automatically based on triggers (for example, a commit, file upload, or webhook).

Summary

Event-driven architectures power some of the most demanding digital systems in existence. Across industries, they provide:

• ⚙️ Scalable infrastructure for handling massive event streams

• ⏱ Real-time responsiveness to user and system actions

• 🧩 Modularity and evolution as systems grow by subscribing to new events

Whether in fintech, IoT, e-commerce, or analytics, EDAs have proven to be a flexible, future-proof foundation for building systems that react intelligently to change.

In the final section, we’ll synthesize the lessons learned, summarizing best practices, common pitfalls, and key takeaways for adopting event-driven architectures successfully in modern JavaScript ecosystems.

10. Best Practices and Conclusions

Event-driven architectures offer a flexible, scalable, and future-proof foundation for modern software systems. But their power comes with complexity: events are easy to emit but hard to manage at scale without discipline and consistency.

This final section distills practical best practices for designing and operating event-driven systems effectively, followed by a summary reflection on when and how to adopt this architecture.

1. Version and Validate Events

Events evolve over time as your system grows. Adding or changing fields can break consumers if versions aren’t managed carefully.

Best practices:

• Use explicit versioning in event names or schemas (for example, order:created.v2).

• Validate event payloads using JSON Schema or tools like ajv or Zod.

• Maintain a central event catalog or schema registry shared by all services.

This ensures backward compatibility and reduces surprises when consumers update at different times.

2. Design for Idempotency

In distributed systems, duplicate messages are inevitable – retries, network hiccups, or failovers can cause events to be processed multiple times.

Make consumers idempotent, meaning they can handle the same event repeatedly without unintended side effects.

For example:

if (!processedEvents.has(event.id)) {
  process(event);
  processedEvents.add(event.id);
}

Always include a unique event ID and check for duplicates before applying changes.

3. Keep Events Meaningful and Self-Contained

Each event should represent a domain-level change, not just a technical signal. Avoid overly generic messages like "update" or "dataChanged", as they make debugging and evolution difficult.

Good events:

• Describe what happened (not what to do).

• Include enough context for consumers to act independently.

• Avoid exposing internal database models directly.

Example:

{
  "event": "user:email:updated",
  "data": { "userId": 123, "oldEmail": "a@x.com", "newEmail": "b@x.com" }
}

This provides clear, business-oriented semantics.

4. Implement Robust Error Handling and Dead-Letter Queues

Not every event will be processed successfully. Network failures, schema mismatches, or transient service outages are inevitable.

Mitigation strategies:

• Use retry policies with exponential backoff.

• Send failed messages to a dead-letter queue (DLQ) for inspection.

• Build alerting and monitoring on DLQ metrics to detect recurring issues.

This ensures resilience and prevents message loss.

5. Ensure Observability and Traceability

Debugging asynchronous flows requires visibility. Embed tracing and correlation data into your events:

{
  "event": "payment:processed",
  "eventId": "9b7f...c0",
  "traceId": "c74d...d9",
  "timestamp": "2025-11-03T13:45:00Z"
}

Integrate with tools like:

• OpenTelemetry for distributed tracing

• Jaeger or Zipkin for visualization

• Kafka UI, Redpanda Console, or Conduktor for message inspection

This allows you to reconstruct event lifecycles across services, which is critical for debugging, compliance, and performance tuning.

6. Use Patterns for Reliability

Certain design patterns make large-scale event-driven systems more reliable:

Applying these patterns reduces race conditions and improves data consistency.

7. Choose the Right Broker for the Job

Different brokers serve different use cases:

Your choice depends on throughput, durability, and delivery guarantees.

8. Balance Event-Driven and Request-Driven Approaches

Event-driven systems excel in asynchronous workflows, but not everything should be event-driven.

Use synchronous APIs for immediate, transactional actions (for example, authentication, user profile lookup). And use events for background or decoupled processes (for example, analytics, notifications, async updates).

Combining both models yields the best balance of responsiveness and reliability.

9. Educate and Align the Team

Architecture is as much about people as it is about technology. Ensure developers share a common understanding of event naming conventions, schema versioning policies, error handling and retry rules, and ownership of producer and consumer responsibilities.

Without alignment, even the best tools lead to inconsistent, brittle systems.

10. Start Small, Then Evolve

You don’t need Kafka clusters or event sourcing to begin. Start small:

• Use Node.js EventEmitter or a simple in-memory bus for decoupling modules.

• Gradually evolve toward distributed brokers as complexity increases.

The key is incremental adoption – building understanding before scaling infrastructure.

Conclusion

Event-driven architectures fundamentally change how we design software. By focusing on what happens rather than what to do next, systems become more adaptable, reactive, and aligned with real-world processes.

In JavaScript – a language born from events – this paradigm feels especially natural. From browser interactions to Node.js microservices, event-driven thinking unifies the frontend and backend under a single principle: react to change.

When used wisely, EDA is not just a design pattern – it’s an architectural mindset that empowers systems to evolve continuously, communicate fluidly, and stay resilient in the face of complexity.

The first is general-purpose computing, where they handle a wide range of tasks, including running diverse applications and programs. Examples include laptops, desktops, servers, and supercomputers.

The second is embedded systems, which are specialized computers designed for specific functions. Commonly found in devices such as thermostats, refrigerators, cars, and other smart appliances, they rely on sensors to collect environmental data and execute their tasks efficiently.

The Role of Sensors

Sensors play a critical role in both types of computing. In embedded systems, sensors gather environmental data to help devices like autonomous vehicles, home appliances, and industrial machines perform tasks. In general-purpose computers, sensors primarily monitor internal conditions such as temperature and voltage, ensuring safe operation and preventing issues like overheating or electrical faults.

As Artificial Intelligence (AI) and the Internet of Things (IoT) evolve, sensors have become indispensable for gathering real-world data to support intelligent decision-making. Embedded systems leverage sensors to perceive their environment, transforming raw data into actionable insights that power automation and improve efficiency across industries.

This means that understanding sensor interfacing and designing robust sensor-driven software has become a vital skill for engineers and hobbyists alike.

Whether you're a beginner or experienced engineer, this guide will help you build a solid understanding of sensor interfacing software.

What You’ll Learn and Article Scope

In this article, you’ll learn how to connect sensors to microcontrollers (MCUs) and design sensor software pipelines that turn raw data into meaningful, usable information. You’ll also explore practical techniques for processing sensor data accurately and efficiently in embedded systems.

Here’s a breakdown of what we’ll cover:

• What sensors are and how they work – An introduction to sensors, common types, and how sensor pipelines help process sensor data.

• Key sensor characteristics – Important parameters like sensitivity, accuracy, precision, range, drift, and response time to help you choose the right sensor for your project.

• How to interface sensors with microcontrollers – Hardware connections and communication protocols like SPI, I²C, and GPIO that allow microcontrollers to read sensor data.

• Software architecture for sensor data – A high-level overview of the software pipeline that processes sensor data, including drivers, ADC support, scaling, calibration, and post-processing.

• Detailed design of pipeline components – A closer look at each step in the pipeline, focusing on scaling raw data, calibrating sensors, and applying filters to clean up noisy signals.

• Practical tips for power management – Best practices for handling power efficiently using low-power modes, FIFO buffers, and DMA when working with sensor data in embedded systems.

By the end of this article, you’ll know how to design and implement a complete sensor data pipeline for an embedded system, from reading raw sensor data to preparing it for real-world use in intelligent, connected devices.

Note: Advanced data processing, high-resolution ADCs, and hardware circuit design for sensors are outside the scope of this article.

Prerequisites

To get the most out of this article, you should have:

1. Basic knowledge of microcontrollers: Understanding of common peripherals like ADCs (Analog-to-Digital Converters), SPI (Serial Peripheral Interface), I2C (Inter-Integrated Circuit) and GPIO (General Purpose Input/Output). If you’re new to these protocols, this article provides a great overview.

2. Basic knowledge of electronics: Familiarity with circuits and signals, including analog and digital interfaces.

3. Programming in C: Familiarity in embedded software development, including driver development.

4. (Optional) Basic knowledge of sensors: Understanding different types of sensors (like temperature, pressure, motion) is helpful but not required.

Also, this article assumes the following:

• You are working with a microcontroller equipped with the peripherals needed for sensor integration. The details of microcontroller peripherals can be found in a reference manual for example for an STM32F4 series microcontroller will have all the details :

• You are familiar with compilers, debuggers, and IDEs used in embedded systems. Some common tools include:

  • Compilers: GCC, Clang,

  • Debuggers: GDB, LLDB

  • IDEs: Visual Studio Code (VSCode) is a popular choice, especially with extensions for embedded development and debugging.

• You aim to build reliable, sensor-driven embedded systems, capable of collecting and processing real-world data efficiently.

Table of Contents

• What is a Sensor and Sensor Pipeline?

• Sensor Characteristics

• How to Interface with a Microcontroller

• Software Architecture

  • High-Level Overview of Components

  • Accessing Data from the Sensor

  • Sensor Power Management

• Detailed Design of Components

  • 1. Sensor Driver

  • 2. ADC Support

  • 3. Scaling

  • 4. Calibration

  • 5. Data Post-Processing

• Conclusion

What is a Sensor and Sensor Pipeline?

A sensor detects changes in physical properties such as temperature, pressure, or light and converts them into electrical signals that can be measured or interpreted. For example, a thermistor is a type of resistor whose resistance changes with temperature. As the temperature varies, the resistance of the thermistor changes, altering the voltage across it. The system then interprets this voltage change to determine the temperature.

To better understand sensors, consider the natural sensors in the human body: the eyes, ears, skin, nose, and tongue. These natural sensors constantly send signals about the environment to the brain for processing. Different regions of the brain interpret these signals and use the information to drive actions and responses. Just like the brain processes signals from natural sensors, a microcontroller processes signals from electronic sensors using a sensor pipeline.

Sensors come in many types, each designed to detect specific physical properties. Some sensors have a sensing element that changes its properties in response to conditions like heat, light, or pressure. Examples include thermistors, infrared receivers, and photodiodes.

For detecting movement, such as acceleration and rotation, MEMS (Microelectromechanical Systems) sensors—like accelerometers and gyroscopes—are widely used.

To measure distance, sensors like sonars, ultrasonic sensors, and radars are common. These are just a few examples of the many types of sensors available.

Beyond the types of physical properties they detect, sensors also differ in their levels of integration. Some sensors are raw sensors, consisting only of a sensing element and a transducer with simple leads for direct connection to an external circuit.

Others, known as smart sensors, include additional components such as an ADC (analog-to-digital converter) and onboard processing capabilities, enabling them to handle more of the data processing independently.

The choice between a raw sensor and a smart sensor depends on your application requirements, including factors like cost, size, and the processing load on the interfacing microcontroller.

Returning to our human analogy, consider how vision works as a sensor pipeline. When light enters our eyes, photoreceptor cells (rods and cones) in the retina act as sensing elements, converting the light into electrical signals. These signals travel via the optic nerve to the brain’s visual cortex, where they undergo processing to form a recognizable image. The brain then interprets this information and initiates a response, like smiling when you see a beautiful scenery.

Similarly, a sensor pipeline for an embedded system can be defined as shown in the picture below:

Each of these steps may have different requirements based on the application. Creating a requirements document for the sensor is helpful when selecting the appropriate sensor and configuring the pipeline.

Sensor Characteristics

Before you dive into the blocks of the sensor pipeline, let’s review some important characteristics of a sensor.

Sensitivity

Sensitivity is the ability of a sensor to detect small changes in the physical property it’s designed to measure.

Sensitivity can vary based on factors like manufacturing processes, cost, and the design of the sensing element.

Sensors designed for a specific property often come in different sensitivity levels, allowing users to select an appropriate sensitivity based on the application requirements.

Accuracy

Accuracy is the degree to which a sensor’s measurement matches the true value of the physical property it’s measuring. Testing a sensor’s accuracy typically requires comparing its readings to those of a reference instrument.

A sensor may have gain and offset errors—issues that calibration can help correct. Calibration adjusts for these systematic errors, which are often due to manufacturing tolerances or design factors.

Once calibrated, the sensor’s output can be verified against a reference to confirm its accuracy. The required level of accuracy should be determined based on the application’s needs.

Precision

Precision refers to the consistency or repeatability of a sensor's measurements, regardless of how close those measurements are to the true value. It indicates the sensor's ability to produce the same output under identical conditions and how finely it can resolve and report values.

For example, if the true temperature of an object is 12.53°C:

• A precise sensor will consistently measure values like 12.52°C, 12.53°C, or 12.54°C, even if those values are slightly offset from the true temperature.

• A highly accurate sensor, on the other hand, will measure values close to 12.53°C but may lack precision if those readings vary widely (e.g., 12.50°C, 12.53°C, and 12.56°C).

For applications requiring exact measurements, a sensor with both high accuracy (closeness to the true value) and high precision (low variability) is essential. This is especially important in distinguishing small differences, such as between 12.5°C and 12.53°C.

In contrast, applications with less stringent requirements might use sensors with broader tolerances, such as ±1°C, which are sufficient for general monitoring purposes.

Range

The range of a sensor refers to the span between the maximum and minimum values of the physical property it can measure while maintaining its specified precision and accuracy. A sensor's operating range may extend beyond its measurement range, but the measurement range defines the limits within which the sensor reliably adheres to its specified sensitivity, accuracy, and response time.

Drift

Drift is when a sensor's output changes over time due to conditions like temperature or humidity. Components within the sensor, including the sensing element, may be sensitive to these conditions, leading to gradual shifts in measurements.

For example, many components are affected by temperature and humidity changes, which can alter sensor readings. Also, sensors with internal oscillators may experience time-based drift, impacting accuracy.

Regular calibration with an accurate external reference (such as a precise clock) can help correct for drift and maintain reliable measurements. For certain applications, selecting a sensor with acceptable drift characteristics is crucial.

Response Time

Response time is the duration a sensor takes to detect and reflect a change in the measured physical property. For example, if the temperature rises by 5°C, the response time indicates how long the temperature sensor takes to reflect this change in its output.

Response time depends on the sensor’s design, manufacturing quality, and internal components, such as the ADC (Analog-to-Digital Converter), averaging circuits, and filters within the sensor pipeline.

All the parameters mentioned above are thoroughly documented in the sensor’s data-sheet. In practice, it’s a good idea to create a sensor requirements document for each specific application, detailing these key parameters as a baseline for sensor selection.

Now that you’ve examined the key characteristics of sensors, let’s explore how you can connect them to a microcontroller for real-world applications.

How to Interface with a Microcontroller

Choosing a Communication Protocol

Another essential aspect of sensor requirements is specifying the communication interface between the sensor and the MCU or processor in the system. It’s important to understand how the sensor will be interfaced based on its output signal type and the available pins on the microcontroller.

For instance, certain sensors may connect directly to an analog or digital input pin on a microcontroller. A raw sensor, such as a temperature sensor, typically connects to an analog input pin, which is then read by the microcontroller’s internal ADC (Analog-to-Digital Converter).

In contrast, a digital-output sensor connects to a digital GPIO (General Purpose Input/Output) pin. For instance, speed sensors generate square waves with variable pulse widths to indicate speed. These signals are usually connected to a GPIO pin configured as an external interrupt or timer capture input, allowing the microcontroller to measure pulse width accurately.

A smart sensor, on the other hand, often supports communication protocols like SPI (Serial Peripheral Interface) or I2C (Inter-Integrated Circuit). These interfaces enable the microcontroller to configure the sensor, check its status, and retrieve data through register reads and writes.

Choosing the appropriate communication protocol for interfacing a sensor depends on the available pins in the system and the specific requirements of the application.

Tip: When working with protocols like I²C or SPI, using tools such as Saleae logic analyzers can greatly simplify debugging and validation. Logic analyzers capture and visualize communication signals, and tools like Saleae offer built-in protocol interpreters to help you decode sensor communication in real time. This can be especially helpful when troubleshooting configuration issues, timing problems, or communication errors during sensor interfacing.

Figure 2 below shows an example of a microcontroller connected to 4 sensors having different interfaces.

Determining Power Requirements

Power requirements are another key consideration when interfacing a sensor. Sensors may operate at different voltages (for example, 3.3V or 5V), so ensuring the microcontroller can accommodate these levels is essential. Level converters can bridge voltage mismatches, ensuring compatibility between the sensor and microcontroller voltage levels.

Timing and sampling requirements must also be evaluated, especially for sensors generating high-frequency data. Configuring external interrupts on GPIO pins can ensure timely data capture, while techniques like using DMA can streamline data transfer for sensors sampling at high frequencies without CPU involvement.

Now that you’ve learned about communication protocols and hardware connections, let’s focus on designing the software architecture that acquires, processes, and prepares sensor data for use. Designing effective software is crucial for obtaining clean, reliable data from the sensor.

Software Architecture

Now that we’ve chosen the sensor and communication protocol, let’s design the software architecture for the sensor pipeline. This software runs on the microcontroller connected to the sensor and processes raw data to make it clean and usable.

While application-level data processing is beyond the scope of this article, let’s focus on interfacing with the sensor and preparing the data for application use.

The sensor processing pipeline can be broken into the following components:

1. Sensor Driver

2. Analog-to-Digital Conversion (ADC) Support

3. Scaling

4. Calibration

5. Data Post-Processing

Let’s examine a high-level overview of these components for both smart and raw sensors.

High-Level Overview of Components

1. Sensor Driver

   1. Smart sensors: The driver configures the sensor, manages power, and handles read and write operations to the sensor registers over a communication protocol like SPI, I2C.

   2. Raw sensors: The driver may only control GPIOs for power management, as raw sensors typically lack registers.

2. Analog-to-Digital Conversion (ADC) Support

   1. Smart sensors: Include an onboard ADC, which is configured through the sensor driver.

   2. Raw sensors: Requires an external ADC, an ADC driver implemented in software to configure the ADC, initiate conversions, and retrieve data.

3. Scaling: Scaling is necessary for both smart and raw sensors. It converts digital counts after the analog to digital conversion into meaningful physical quantities using formulas provided in the sensor data sheet. For example, a temperature sensor will use a formula to convert digital counts to degree Celsius.

4. Calibration: Once the measured physical quantity is obtained, calibration adjusts the value by applying offsets, gains, or both to correct errors. This process ensures the sensor output aligns with reference values across its entire measurement range. A detailed discussion of the calibration process will follow in the next section.

5. Data Post-Processing: Post-processing techniques, such as filtering are applied to improve data quality and reduce noise. Common filters such as low-pass or high-pass filters can remove unwanted frequency components.

Accessing Data from the Sensor

The method of accessing data depends on the whether it’s a raw sensor or a smart sensor. Smart sensors will have onboard ADCs and FIFOs. Before delving into how data is accessed, it’s important to first understand sampling frequency.

Sampling Frequency:

The frequency of taking a measurement from the sensor must follow the Nyquist-Shannon sampling theorem. It states that the sampling rate must be twice the highest frequency component of the signal to be measured to accurately reconstruct the measured data.

The sampling frequency defines how often the sensor captures data, which affects how the data is accessed. Depending on whether the sensor is a raw sensor or a smart sensor, the approach to handling this sampled data varies.

Smart Sensors:

1. Data register: The sensor writes sampled data directly into a register based on the set sample frequency updated during setup. The microcontroller reads this data register based on a data conversion completion interrupt.

2. FIFObBuffer: Some sensors include FIFO (First-In, First-Out) buffers to store multiple data points. When enabled, the FIFO updates at the configured sampling frequency and trigger interrupts when it becomes full or reaches a predefined level.
   The benefits of FIFO include:

   1. Power efficiency: The MCU can process data in batches, reducing CPU overhead and allowing it to enter low-power mode during data collection.

   2. Sampling and processing rate matching: FIFO buffers help reconcile differences between the sensor’s sampling rate and the MCU’s data processing rate.

   3. For MCUs with Direct Memory Access (DMA), data transfer from the sensor to MCU memory can occur without CPU intervention, further reducing power consumption.

Raw Sensors:

For raw sensors, the MCU triggers ADC conversions at the sampling frequency, often using a timer interrupt. Data is read upon the ADC conversion complete interrupt, allowing the MCU to sleep during conversions and between samples to save power.

Sensor Power Management

Power management is critical for energy-sensitive applications. Strategies include:

1. Low-power modes: Many sensors support low-power modes configurable through sensor registers.

2. GPIO-controlled power cycling (Duty-Cycling): For sensors without built-in low-power modes, the microcontroller can toggle the sensor’s power line using a GPIO pin, reducing power consumption further. Figure 3 below shows the diagram of a raw temperature sensor whose power is controlled using a GPIO from the MCU. For example, a temperature sensor in sleep mode can be activated only when temperature readings are required.

The above techniques ensure efficient use of power while maintaining the required data sampling rate and sensor responsiveness.

With the high-level architecture in mind, we’ll now dive into the detailed design of each pipeline component.

Detailed Design of Components

In this section, you’ll delve into the key components of the sensor pipeline outlined in the Software Architecture section.

1. Sensor Driver

The sensor driver is responsible for managing communication, configuration, power, and data acquisition for both smart and raw sensors.

Smart Sensor Driver:

1. Communication driver: Generic I2C or SPI drivers on the MCU can be adapted using wrapper functions to handle sensor-specific requirements, such as 1-byte, 2-byte, or 4-byte transfers.

2. Configuration: Typical tasks include setting the sampling rate, configuring interrupts, managing FIFO buffers, and, if needed, clock settings.

3. Power management: APIs should allow higher software layers to transition sensors between power modes by writing to specific registers or controlling GPIO lines for sensors without built-in power modes.

Raw Sensor Driver:

For raw sensors, the driver primarily manages power, often through GPIO-controlled toggling.

2. ADC Support

ADC support is required only for raw sensors. In this article, we’re focusing on SAR ADCs, which are commonly embedded in microcontrollers.

How SAR ADCs Work?

A SAR ADC converts an analog signal to a digital value over multiple clock cycles, with the number of cycles equal to its bit resolution (for example, 10 cycles for a 10-bit ADC).

Key terms related to ADCs:

1. Reference Voltage (VRef): Represents the maximum voltage the ADC can measure. Analog signals exceeding this limit must be scaled down.

2. Resolution: Determines the smallest detectable voltage change. For example, a 10-bit ADC with a 3.3V VRef has a resolution of 3.22 mV

$$V_{\text{Res}} = V_{\text{Ref}} /2^{10}$$

The ADC result is stored in a data register, which can then be scaled to meaningful physical units.

3. Scaling

Scaling converts ADC counts into meaningful physical values, such as temperature (°C) or acceleration (g) depending on the sensor type. Sensor datasheets typically provide the necessary formulas or lookup tables.

For example, the method to convert a voltage measured by a raw temperature sensor to temperature value is shown below:

$$V_{\text{Measured}} = Counts_{\text{ADC}} / 2^{10} * V_{\text{Ref}} \quad \text{(Get V_Measured from ADC Counts)}$$

$$Temperature_{\text{Measured}} = V_{\text{Measured}} * T_{\text{C/mV}} \quad \text{(Get Temperature physical value)}$$

Similarly, a 3-axis accelerometer maps counts on the X, Y, and Z axes to acceleration values in g or milli-g.

4. Calibration

The figure above on the left (4a) is showing Calibration with gain and offset, while the figure above on the right (4b) is showing calibration with fixed offset.

$$x_{\text{calibrated}} = Gain * x_{\text{raw}} + Offset \quad \text{(Figure 4a - Linear Calibration)}$$

$$x_{\text{calibrated}} = x_{\text{raw}} + Offset \quad \text{(Figure 4b - Fixed offset Calibration)}$$

Calibration ensures the sensor’s output aligns with reference measurements, correcting for errors introduced by design, materials, or manufacturing.

Types of Errors:

1. Offset error: A constant deviation of the sensor’s output from the true reference value, regardless of input magnitude.

2. Gain error: A proportional error where the sensor’s output scale deviates from the expected value, causing the output to increase or decrease incorrectly relative to the input.

Calibration Methods:

1. 2/3-Point calibration: This type of calibration may involve either applying a fixed offset to the raw value or applying both gain and offset. Figure 4a illustrates an example of a gain/offset calibration, while Figure 4b depicts offset calibration. In both figures, the y-axis represents the reference value measured by an accurate instrument, while the x-axis represents the raw value measured by the sensor after ADC.

2. N-Point calibration: Involves multiple points for more complex, non-linear error correction.

Implementation:

1. Calibration points shall cover the sensor’s entire measurement range for accuracy.

2. Parameters like gain and offset once estimated shall be stored in a non-volatile memory in the system for persistence to be used across power cycles.

5. Data Post-Processing

Post-processing covered in this section talks about removing noise and unwanted signal components, which improves data reliability.

Filtering

Filtering is the process of removing unwanted frequency components from a signal to improve data quality. There are several different types of filters:

• Low-Pass Filters: Allows low-frequency signals to pass while attenuating high-frequency noise.

• High-Pass Filters: Allows high-frequency signals to pass while attenuating low-frequency noise. (for example, gravitational acceleration in accelerometer data).

• Band-Pass Filters: Retains only signals within a specific frequency range, removing both lower and higher frequencies outside the desired band.

These filters are often implemented as FIR (Finite Impulse Response) or IIR (Infinite Impulse Response) filters. IIR filters are easy to implement and computationally efficient while FIR filters are computationally intensive but have better control over the frequency response.

Here, we will explore a simple low-pass filter known as the Exponential Moving Average (EMA), a type of IIR filter. A moving average filter is a mathematical technique that smooths short-term fluctuations while highlighting longer-term trends.

Unlike other moving average filters, EMA does not require maintaining a buffer, making it more memory-efficient. It is also more responsive to data changes while still providing smoothing, making it well-suited for real-time filtering. EMA assigns greater weight to recent data samples than older ones, allowing it to adapt quickly to changes in sensor readings.

EMA can be calculated like this:

$$EMA_{\text{t}} = \alpha * x_{\text{t}} + (1 - \alpha) * EMA_{\text{t - 1}}$$

$$\alpha = 2 / (N + 1) \quad \text{(Smoothening Factor, N - filter window size)}$$

$$EMA_{\text{t}} \quad \text{(Exponential Moving Average in current iteration)}$$

$$x_{\text{t}} \quad \text{(New Data Sample in Current Iteration)}$$

$$EMA_{\text{t - 1}} \quad \text{(Exponential Moving Average in the last iteration)}$$

Now that we understand the Exponential Moving Average (EMA) filter, here are two key factors to consider when tuning it for an application:

• Smoothing vs. Responsiveness: A higher smoothing factor (closer to 1, smaller filter window size) gives more weight to recent data, making the filter more responsive to changes but less effective at noise reduction. A lower smoothing factor (closer to 0, larger filter window size) provides better noise reduction but reacts more slowly to data changes.

• Application-Specific Tuning: The smoothing factor should be chosen based on the sampling rate, sensor sensitivity, and application requirements. Real-time systems often require a balance between quick responsiveness and stable output.

Here’s a code sample for EMA:

#include <stdio.h>
#include <stdint.h>

// Exponential Moving Average (EMA) filter implementation
#define FILTER_WINDOW 5

// Function to calculate EMA
float calculateEMA(float ema, float new_value, float alpha) {
    return (alpha * new_value) + (1 - alpha) * ema;
}

int main() {
    float sensorReadings[] = {26.0, 27.5, 28.2, 27.0, 26.8, 26.5, 27.2};
    int numReadings = sizeof(sensorReadings) / sizeof(sensorReadings[0]);

    float alpha = 2.0f / (FILTER_WINDOW + 1); // Standard EMA formula
    float ema = sensorReadings[0];  // Initialize EMA with the first reading

    printf("EMA Filtered Sensor Data:\n");

    for (int i = 0; i < numReadings; i++) {
        ema = calculateEMA(ema, sensorReadings[i], alpha);
        printf("Reading %d: Raw = %.2f, EMA = %.2f\n", i + 1, sensorReadings[i], ema);
    }

    return 0;
}

Conclusion

In summary, sensors are the backbone of modern smart devices, bridging the gap between the physical world and digital systems. From consumer electronics to industrial automation and medical devices, they enable devices to perceive and interact with their environments.

Understanding how sensors work, the components of their data pipeline, and their integration with microcontrollers is essential for engineers and hobbyists alike. By designing effective pipelines, developers can ensure accurate, clean, and reliable data, enabling systems to meet performance and power efficiency goals.

If you have questions or want to talk more about this topic, feel free to reach out on Twitter or LinkedIn. Always happy to connect.

From healthcare to finance, robust software systems power our daily operations, making good software design essential to avoid inefficiencies and bottlenecks. This involves not just writing code but also designing systems that are easy to scale, maintain, and debug, while allowing others to contribute effectively.

Inefficient or ineffective software design can lead to significant issues, like scope creep, miscommunication within teams, project delays, resource misallocation, and complex systems that are difficult to maintain or understand. Without a strong design, teams often accumulate technical debt, which hinders long-term progress and increases maintenance costs.

This article will introduce you to key software design elements that will help you and your team address these challenges and guide you in building efficient, scalable systems. By understanding and applying these elements correctly, you can set up a project for both short-term and long-term success.

Prerequisites

I’ll explain these concepts through examples, but a basic understanding of programming in any language is required for this article (knowledge of Python will be especially beneficial).

Scope

The article will introduce key software design elements and explain them using an example. While I won’t provide a full software design for the example problem, I will include enough details to effectively illustrate each design element.

Table of Contents

• Overview of Key Software Design Elements

• A Walkthrough of the Software Design Process

  • Problem Statement

  • Use Cases

  • Requirements

  • High Level System Architecture

  • Detailed Software Design and Component Breakdown

• Conclusion: The Value of Thoughtful Software Design

Overview of Key Software Design Elements

To fully understand the benefits of the software design process, you’ll need to understand some key elements and their scope.

Once you have a good grasp of these, the next step is to define them for the specific problem at hand. Accurately defining these elements reduces risks and simplifies the implementation phase.

Doing this groundwork before implementation helps prevent late discoveries, minimizes the need for rewriting, and makes sure that the design can handle constraints and corner cases.

Now let’s briefly go over the key elements of the software design process:

1. Creating a problem statement: This step involves creating a clear and concise description of the problem that needs to be solved, along with its scope. The scope is essential because it focuses on the exact problem to be addressed and includes assumptions that must be considered during design.

2. Identifying use cases: This step outlines all possible user interactions with the software to achieve the desired outcome. It is a critical input to the architecture, as it helps create a design that addresses both general and edge-case use cases.

3. Stating requirements: This step defines the expectations of the software, such as its limitations, behaviors, and capabilities for different use cases.

4. Designing the architecture: This step provides a high-level structure of the software design, focusing on how to meet the requirements. The architecture typically includes components, how they interact, and how data flows through the system.

5. Drafting a detailed design: This step refines the high-level architecture into detailed, component-specific designs, ready for implementation.

In addition to these core elements, there are two important factors you need to consider throughout the design phase.

First, you’ll need to identify and state any assumptions you have. Assumptions can be present at any stage in the design process. Making correct assumptions increases the likelihood of success, improves focus, and reduces complexity in the design.

Second, you’ll need to create good documentation. Documentation is one of the most important elements in the software design process. It’s essential to document each stage as you go along. Documentation serves as the only formal record of the software design and is invaluable for presentations to management, for onboarding new team members, and for anyone returning to the project after a break. It saves valuable time and ensures continuity, as we often overestimate our own memory.

The figure below provides a visual summary of the key software design elements discussed in this section.

Next, we’ll apply these key software design elements to a practical example, demonstrating how each element contributes to building a robust and scalable system.

A Walkthrough of the Software Design Process

In any well-structured software project, clearly defining the problem is the first crucial step before diving into design and implementation. A well-defined problem ensures that the software meets user needs, remains maintainable, and scales effectively over time.

For this walkthrough, we will focus on designing a financial expense categorization system that processes and analyzes transaction data. This system is a part of a larger financial management solution and needs to be easy to debug, maintain, and scale.

Problem Statement

The problem statement provides a high-level goal for the software that we’ll design.

For this example, here’s our statement: Design a software solution that categorizes monthly expenses and generates a report from a list of transactions.

Define the scope

Defining the scope clarifies the smaller tasks that must be accomplished to meet the high-level goal. It outlines the focus of the software design and includes some assumptions.

Includes:

1. Implementing a parser to process a list of transactions provided as input.

2. Filtering transactions for a given month.

3. Analyzing, categorizing, and generating a report for each expense category.

Excludes:

Performance and memory optimization (excluded due to the limited scope of this article). While performance and memory optimizations are not the primary focus here, it’s important to keep future scalability in mind. Small design choices made now, such as selecting data structures, can help avoid significant refactoring later when the system grows.

Assumptions:

1. The list of transactions will be provided as a CSV file in the following format:
   Columns: "Date, Description, Amount, Type, Category Label".

2. Expense categories will be provided as input through a JSON file.

3. The software will run in a shell environment, and inputs will be taken as command-line arguments.

Now that the scope is clear, let’s examine how users will interact with the system through various use cases.

Use Cases

Use cases define how users will interact with the system to accomplish specific goals. Identifying accurate and valid use cases is critical to creating comprehensive requirements. Failing to capture enough use cases can lead to a design that is incomplete and lacks robustness. This may result in the need for redesigns, which increases time and resource consumption.

On the other hand, identifying too many use cases without considering their feasibility can lead to overly complex designs that are difficult to maintain and implement in the short term.

For our specific problem, the user will need to provide the following inputs while running the software in a shell:

1. A CSV file containing a list of transactions.

2. A month number.

3. A JSON file containing expense categories.

We need to consider all possible ways the user can interact with the script to achieve the desired outcome. For each of the three inputs, there are two possibilities: valid input or invalid input. This gives us 8 potential use cases (2 possibilities per input: valid and invalid). It's important to define what constitutes valid and invalid inputs for this problem:

• CSV File: Valid if it is in the format described in Assumption 1 (columns: "Date, Description, Amount, Type, Category Label").

• Month Number: Valid if the value is between 1 and 12.

• JSON File: Valid if it contains expense categories in the correct JSON format.

An input is invalid if it doesn't meet these definitions or if the input is absent.

It’s also crucial to consider the correlation between inputs when evaluating the feasibility of certain use cases, as they may interact with each other in unforeseen ways. Based on these use cases, we can now define the specific requirements that the system must meet.

Requirements

Now, let’s define the expected behaviors, limitations, and capabilities for each use case. Requirements serve as the foundation for architecture, specifications, and implementation. Based on our problem statement, the software will need to accomplish the following tasks:

1. The script shall take three inputs: a CSV file of transactions, a month number, and a JSON file of expense categories.

2. The script shall verify all inputs.

3. The script shall throw an error and exit if the CSV file cannot be opened or if it does not match the format in Assumption 1.

4. The script shall throw an error and exit if the JSON file cannot be opened.

5. The script shall throw an error if the month number is not between 1 and 12.

6. The script shall parse each transaction and load it into a data structure.

7. The script shall filter transactions by the specified month.

8. The script shall load the expense categories from the JSON file into a data structure.

9. The script shall categorize transactions based on the category label provided in the CSV file.

10. The script shall throw an exception if a category label in the CSV file is not present in the expense categories.

11. The script shall use a categorizing function to assign transactions to categories from the JSON file.

12. A class shall encapsulate categorized transactions, providing APIs to modify or access them.

13. The script shall support statistics calculation and report generation for categorized transactions.

With the requirements in place, we can now design a high-level architecture to meet those needs.

High Level System Architecture

In this stage, we will design the system at a high level, much like creating a master plan. Architecture involves organizing the software's functions into distinct components, illustrating how they interact, and mapping the flow of control and data through the system. While designing the architecture in this tutorial, we’ll incorporate good design principles.

For this example, the high-level requirements include:

1. Loading inputs and verifying them.

2. Applying time-based filtering.

3. Categorizing transactions based on category labels and descriptions.

4. Managing categorized transactions in a finance registry.

5. Generating reports from the categorized data.

One important component of software architecture is telemetry. Telemetry gathers data on the software's behavior, which is invaluable for debugging and performance assessment in real-world environments.

For smaller systems, simpler logging mechanisms may be sufficient to track basic errors and monitor performance. The decision to implement telemetry should depend on the complexity of the system and operational requirements.

Since telemetry provides such a helpful feedback loop for improving the design in future iterations, we’ll add it to the list of components here.

We’ll build our system architecture around a Test-Driven Development (TDD) approach. We’ll design each component with testing in mind to ensure it meets our requirements.

Just keep in mind that while TDD is a strong practice for ensuring code quality, it may not be the best fit for all projects. In scenarios where you need rapid prototyping or exploratory development, testing might be prioritized after initial iterations. Balancing between TDD and other methodologies depends on the project context and team preferences.

Our architecture will follow a modular structure, meaning the system will be divided into self-contained components. Each component will be responsible for specific functionality, making the system easier to test, maintain, and scale.

To achieve this, the architecture will emphasize loose coupling between components. Each component will interact with others through well-defined interfaces or APIs, ensuring minimal dependencies. We’ll abstract and encapsulate internal implementation details, exposing only the necessary information for interaction. Also, each component will handle its own errors and exceptions to ensure robustness and fault isolation.

But it is also important to consider a centralized error-handling strategy in some cases. Centralizing error handling can reduce redundancy, improve consistency, and make maintenance easier. The choice between local and centralized error handling should depend on the system's complexity and how components interact. This will contribute to the overall scalability and maintainability of the system.

Below is a summary of each component's functionality in this architecture:

• Load and verify input: This component will take the CSV file, JSON file, and month number as input, verify their validity, and load the data into structures.

• Time-based filter: This component will filter transactions based on the input month and store the filtered transactions in a data structure.

• Label-based categorization: This component will categorize transactions based on the category label in the CSV file.

• Description-based categorization: This component will categorize transactions using an algorithm based on the transaction description.

• Finance registry: This component will store all categorized transactions for further processing. It isolates the post-processing of categorized transactions from the categorization process and provides methods for updating or retrieving datasets.

• Report generation: This component will generate expense reports from the categorized transaction data.

• Telemetry: This component will monitor the performance of other components. It will track the flow of transactions, ensuring that all transactions are categorized either by label or description. Additional parameters can be added as needed to monitor specific functionalities.

The diagram below demonstrates the flow of data through these components:

Detailed Software Design and Component Breakdown

While we won't cover the full system design, this section will highlight key components and their specifications. For this example, I will assume the role of both the designer and implementer of the software.

Software design and specifications depend on several factors, including the designer's knowledge, skill set, available time, and resources. We’ll define some of the design details for the system, starting with the choice of the implementation language.

Choosing the right language is based on several important factors:

1. The language must meet the software requirements.

2. It should be stable, and have strong support from an active developer community.

3. Additional considerations include performance (speed and memory), scalability (ability to grow with future requirements), and platform support (ability to run on all major operating systems).

If you’re the one implementing this design, you’ll need to be familiar with and confident using that programming language. For this project, I chose Python because it meets all the project requirements, has a robust developer community for support, it’s stable, and I’m confident in using it to complete the implementation successfully.

Data Structures

Now, let’s look at the fundamental data structures that we’ll use in the design. We need to load the contents of the CSV file into a data structure for further analysis and processing. In Python, the Pandas DataFrame from the Pandas library is ideal for analyzing and processing tables, so we will use it to store the transactions.

For generating report, we will encapsulate categorized transactions along with relevant statistics, such as the total number of transactions, mean amount, and maximum amount, within a dedicated dataset class. This approach ensures a clear separation of concerns, where the dataset class manages data processing, while the reporting component focuses on presentation.

By structuring the system this way, we enhance reusability, maintainability, and scalability, making it easier to extend and modify in the future.

This dataset class will include:

• Member variables: category name, category description, a Pandas DataFrame for transactions, total number of transactions, mean amount, and max amount of transactions.

• Member functions: set/get DataFrame, save dataset to CSV (useful for debugging).

Here’s an example of a Dataset class in Python for structured data management and processing:

import pandas as pd  # Import Pandas for data handling

class Dataset:
    """
    A class representing a structured dataset with a name, predefined keys, 
    and a Pandas DataFrame.
    """

    def __init__(self, name, keys):
        """
        Initializes the Dataset object.

        Parameters:
        name (str): The name of the dataset.
        keys (list): A list of expected column names for the dataset.

        Attributes:
        self.name (str): Stores the dataset name as a string.
        self.keys (list): Stores the expected column names for data organization.
        self.mean_amt (float): Tracks the mean (average) transaction amount.
        self.max_amt (float): Tracks the maximum transaction amount.
        self.count (int): Stores the total number of transactions in the dataset.
        self.dataframe (pd.DataFrame): A Pandas DataFrame initialized with the specified column names.
        """
        self.name = str(name)  # Convert and store dataset name as a string
        self.keys = keys  # Store expected column names for consistency
        self.mean_amt = 0  # Initialize mean transaction amount to zero
        self.max_amt = 0  # Initialize max transaction amount to zero
        self.count = 0  # Initialize transaction count to zero
        self.dataframe = pd.DataFrame(columns=keys)  # Initialize empty DataFrame with predefined columns

    def getName(self):
        """
        Returns the name of the dataset.

        Returns:
        str: The name of the dataset.
        """
        return self.name  # Fixed: Removed incorrect parentheses

    def getValue(self, key):
        """
        Retrieves a specific column from the DataFrame.

        Parameters:
        key (str): The column name to retrieve.

        Returns:
        pandas.Series or None: The column data if the key exists, otherwise None.
        """
        if key in self.dataframe.columns:
            return self.dataframe[key]
        else:
            print(f"Warning: Key '{key}' not found in DataFrame.")
            return None  # Prevents KeyError

    def getKeys(self):
        """
        Returns the list of expected keys (column names) of the dataset.

        Returns:
        list: The keys defining the dataset.
        """
        return self.keys

    def setDataFrame(self, dataframe):
        """
        Sets the dataset's DataFrame while ensuring it contains only expected keys.

        Parameters:
        dataframe (pandas.DataFrame): The DataFrame to assign to the dataset.
        """
        if not isinstance(dataframe, pd.DataFrame):
            raise TypeError("Provided data is not a valid pandas DataFrame.")

        # Ensure only the expected columns are included
        self.dataframe = dataframe[self.keys].copy() if set(self.keys).issubset(dataframe.columns) else dataframe.copy()

    def getDataFrame(self):
        """
        Returns the DataFrame associated with the dataset.

        Returns:
        pandas.DataFrame: The dataset's DataFrame.
        """
        return self.dataframe

    def save_to_csv(self, file_name):
        """
        Saves the dataset's DataFrame to a CSV file.

        Parameters:
        file_name (str): The name of the CSV file to save.
        """
        self.dataframe.to_csv(file_name, mode='w', index=False)  # Save the DataFrame to CSV

In the previous section, we outlined the high-level system architecture, detailing the core components and their interactions. Now, let’s dive into the detailed design of some of the individual components, specifying how we’ll implement each one and how it’ll function within the system. We’ll also break down the components to explain how they work together to process the input and generate the report.

Below, you can see the flow diagram for the software, illustrating the interaction between the core components and the flow of data through the system.

Category Label-Based Filtering Component

The Category Label-Based Filtering Component classifies transactions by matching their "Category Label" with predefined expense categories from a JSON file. Transactions with valid category labels are stored in the finance registry, while unmatched ones remain for further processing.

• Input: DataFrame of time-filtered transactions, expense categories from JSON.

• Libraries used: Pandas DataFrame.

• Software design: Filters transactions based on the "Category Label" column and assigns them to corresponding categories. Transactions that cannot be categorized remain for further processing.

• Output: DataFrame of remaining transactions with empty values in the "Category Label" field.

• Component tests: Validate handling of valid, invalid, and missing category labels.

Finance Registry Component

The Finance Registry Component manages categorized transactions by storing them as datasets for each expense category. It maintains a structured collection of DataFrames, each containing transactions and summary statistics such as total count, max amount, and mean amount.

• Input: Expense categories from JSON.

• Libraries used: Pandas DataFrame.

• Software design: Implements a class that organizes datasets for all expense categories, providing methods to set and retrieve DataFrames.

• Component tests: Validate dataset creation, ensuring correct storage and retrieval of categorized transactions.

Here’s a simple and efficient Finance Registry implementation in Python for managing categorized financial datasets:

from Dataset import Dataset
import pandas as pd  # Ensure Pandas is imported if used elsewhere

# Define column structure for datasets
KEYS = ("Date", "Description", "Amount", "Transaction Type", "Category", "Account Name", "Labels", "Notes")

# Define dataset names for different financial categories
EXAMPLE_DATASET_NAMES = ("Investment", "Expense", "Savings")

class FinanceRegistry:
    """
    A class to manage categorized financial datasets, including investment, expense, and savings datasets.
    This registry allows structured access to transaction data and maintains aggregated financial metrics.
    """

    def __init__(self):
        """
        Initializes the FinanceRegistry object.

        Attributes:
        self.example_dataset (dict): A dictionary storing Dataset objects for financial datasets.
        """
        self.example_dataset = {name: Dataset(name, KEYS) for name in EXAMPLE_DATASET_NAMES}  # Create datasets for categories

    def setExampleDatasetToRegistry(self, name, dataframe):
        """
        Merges a new dataframe into the existing dataset for a given financial category.

        Parameters:
        name (str): The category name (e.g., "Investment", "Expense", or "Savings").
        dataframe (pd.DataFrame): The new data to be added.

        If the dataset already contains data, it concatenates the new dataframe to the existing one.

        Raises:
        ValueError: If the provided name is not a valid dataset category.
        """
        if name not in self.example_dataset:
            raise ValueError(f"Invalid dataset name: '{name}'. Expected one of {EXAMPLE_DATASET_NAMES}")

        df = self.example_dataset[name].getDataFrame()  # Get existing dataset

        if not dataframe.empty:  # Ensure the new dataframe is not empty
            dataframe = pd.concat([df, dataframe], axis=0, ignore_index=True)  # Append new data

        self.example_dataset[name].setDataFrame(dataframe)  # Update dataset in registry

    def getExampleDatasetFromRegistry(self, name):
        """
        Retrieves the dataset for a given financial category.

        Parameters:
        name (str): The category name (e.g., "Investment", "Expense", or "Savings").

        Returns:
        Dataset: The dataset corresponding to the given name.

        Raises:
        ValueError: If the provided name is not a valid dataset category.
        """
        if name not in self.example_dataset:
            raise ValueError(f"Invalid dataset name: '{name}'. Expected one of {EXAMPLE_DATASET_NAMES}")

        return self.example_dataset[name]

The diagram below illustrates how the Finance Registry organizes these datasets for further processing in the Report Generation component.

Report Generation Component

The Report Generation Component processes categorized transaction datasets from the finance registry and generates summary statistics. It calculates key financial metrics such as maximum amount, mean amount, and total transaction count. It also provides functionality to display categorized transactions in a structured format within the shell.

• Input: Datasets of categorized transactions from the finance registry.

• Libraries used: Numpy for calculations, Tabulate for formatted shell output (if needed).

• Software design: Implements a class with methods to compute financial statistics and display transaction summaries per expense category.

• Component tests: Validate correct calculation of mean, max, and total transactions, and ensure accurate display of categorized datasets in the shell.

Here’s a function to compute transaction statistics, including mean, max, and count, from a dataset in the report generation component:

from Dataset import Dataset
import numpy as np

def calculateStats(dataset):
    """
    Computes statistical metrics for a given dataset.

    Parameters:
    dataset: The dataset containing transaction data.

    Updates:
    - dataset.mean: Mean transaction amount.
    - dataset.max: Maximum transaction amount.
    - dataset.count: Number of transactions.
    """

    # Return early if the dataset has no transactions
    if dataset.dataframe.empty:
        return

    # Extract transaction amounts as a list
    tx_amount_list = dataset.dataframe['Amount'].astype(float).round(2).tolist()

    # Adjust transaction amounts based on "Transaction Type"
    for i, tx_type in enumerate(dataset.dataframe['Transaction Type']):
        if tx_type == 'debit':
            tx_amount_list[i] *= -1  # Convert debit transactions to negative values

    # Compute statistical metrics
    dataset.mean = round(np.mean(tx_amount_list), 2)
    dataset.max = max(tx_amount_list)
    dataset.count = len(tx_amount_list)

This concludes the design section, where we explored key software design elements with a practical example. The next step, implementation, is beyond the scope of this article. But it's crucial to recognize that new challenges often emerge during development, requiring updates to requirements, architecture, and specifications.

The purpose of this article is not to provide a full implementation, but to teach you some basic software design principles through an example. The focus is on understanding how to structure software, define clear requirements, and create scalable architectures, all before writing code.

By following a structured design process, you can shift complex problem-solving from implementation to the architecture phase, where you can explore solutions more effectively using flowcharts, block diagrams, and documentation. This makes the development process more organized, efficient, and maintainable, a crucial skill for real-world software engineering.

If you're learning to code, remember that good design is just as important as writing code itself!

Conclusion: The Value of Thoughtful Software Design

With well-defined problem statements, scope, requirements, specifications, and design, even complex problems can be solved and maintained in a sustainable way.

The steps we went through in this article can help you break down any problem, regardless of its complexity, into smaller, actionable tasks that you and your team can efficiently tackle.

Without proper planning, projects are often plagued by scope creep, wasted time and resources, miscommunication between teams, overly complicated designs, technical debt, and frequent redesigns.
Good design is often simple design, but achieving simplicity is difficult without thorough planning.

Approaching each problem with the mindset of defining a Problem Statement, Scope, Use Cases, Requirements, Architecture, and Specifications helps cultivate a strong software design mindset. This mindset is crucial for developing software that is scalable, maintainable, and high quality.

Spring Boot’s multi-module structure allows you to manage different parts of the application independently, which lets your team develop, test, and deploy components separately. This structure keeps code organized and modular, making it useful for both microservices and large monolithic systems.

In this tutorial, you’ll build a multi-module Spring Boot project, with each module dedicated to a specific responsibility. You’ll learn how to set up modules, configure inter-module communication, handle errors, implement JWT-based security, and deploy using Docker.

Prerequisites:

• Basic knowledge of Spring Boot and Maven.

• Familiarity with Docker and CI/CD concepts (optional but helpful).

Table of Contents

1. Why Multi-Module Projects?

2. Project Structure and Architecture

3. How to Set Up the Parent Project

4. How to Create the Modules

5. Inter-Module Communication

6. Common Pitfalls and Solutions

7. Testing Strategy

8. Error Handling and Logging

9. Security and JWT Integration

10. Deployment with Docker and CI/CD

11. Best Practices and Advanced Use Cases

12. Conclusion and Key Takeaways

1. Why Multi-Module Projects?

In single-module projects, components are often tightly coupled, making it difficult to scale and manage complex codebases. A multi-module structure offers several advantages:

• Modularity: Each module is dedicated to a specific task, such as User Management or Inventory, simplifying management and troubleshooting.

• Team Scalability: Teams can work independently on different modules, minimizing conflicts and enhancing productivity.

• Flexible Deployment: Modules can be deployed or updated independently, which is particularly beneficial for microservices or large applications with numerous features.

Real-World Example

Consider a large e-commerce application. Its architecture can be divided into distinct modules:

• Customer Management: Responsible for handling customer profiles, preferences, and authentication.

• Product Management: Focuses on managing product details, stock, and pricing.

• Order Processing: Manages orders, payments, and order tracking.

• Inventory Management: Oversees stock levels and supplier orders.

Case Study: Netflix

To illustrate these benefits, let's examine how Netflix employs a multi-module architecture.

Netflix is a leading example of a company that effectively uses this approach through its microservices architecture. Each microservice at Netflix is dedicated to a specific function, such as user authentication, content recommendations, or streaming services.

This modular structure enables Netflix to scale its operations efficiently, deploy updates independently, and maintain high availability and performance. By decoupling services, Netflix can manage millions of users and deliver content seamlessly worldwide, ensuring a robust and flexible system that supports its vast and dynamic platform.

This architecture not only enhances scalability but also improves fault isolation, allowing Netflix to innovate rapidly and respond effectively to user demands.

2. Project Structure and Architecture

Now let’s get back to our example project. Your multi-module Spring Boot project will use five key modules. Here’s the layout:

codespring-boot-multi-module/
 ├── common/               # Shared utilities and constants
 ├── domain/               # Domain entities
 ├── repository/           # Data access layer (DAL)
 ├── service/              # Business logic
 └── web/                  # Main Spring Boot application and controllers

Each module has a specific role:

• common: Stores shared utilities, constants, and configuration files used across other modules.

• domain: Contains data models for your application.

• repository: Manages database operations.

• service: Encapsulates business logic.

• web: Defines REST API endpoints and serves as the application’s entry point.

This structure aligns with separation of concerns principles, where each layer is independent and handles its own logic.

The diagram below illustrates the various modules:

3. How to Set Up the Parent Project

Step 1: Create the Root Project

Let’s run these commands to create the Maven parent project:

mvn archetype:generate -DgroupId=com.example -DartifactId=spring-boot-multi-module -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
cd spring-boot-multi-module

Step 2: Configure the Parent pom.xml

In the pom.xml, let’s define our dependencies and modules:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://www.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-multi-module</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <modules>
        <module>common</module>
        <module>domain</module>
        <module>repository</module>
        <module>service</module>
        <module>web</module>
    </modules>
    <properties>
        <java.version>11</java.version>
        <spring.boot.version>2.5.4</spring.boot.version>
    </properties>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring.boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

This pom.xml file centralizes dependencies and configurations, making it easier to manage shared settings across modules.

4. How to Create the Modules

Common Module

Let’s create a common module to define shared utilities like date formatters. Create this module and add a sample utility class:

mvn archetype:generate -DgroupId=com.example.common -DartifactId=common -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Date Formatter Utility:

package com.example.common;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class DateUtils {
    public static String formatDate(LocalDate date) {
        return date.format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
    }
}

Domain Module

In the domain module, you will define your data models.

package com.example.domain;

import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class User {
    @Id
    private Long id;
    private String name;

    // Getters and Setters
}

Repository Module

Let’s create the repository module to manage data access. Here’s a basic repository interface:

package com.example.repository;

import com.example.domain.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {}

Service Module

Let’s create the service module to hold your business logic. Here’s an example service class:

package com.example.service;

import com.example.domain.User;
import com.example.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public User getUserById(Long id) {
        return userRepository.findById(id).orElse(null);
    }
}

Web Module

The web module serves as the REST API layer.

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

5. Inter-Module Communication

To avoid direct dependencies, you can use REST APIs or message brokers (like Kafka) for inter-module communication. This ensures loose coupling and allows each module to communicate independently.

The diagram below demonstrates how modules communicate with each other:

The diagram illustrates how different system components communicate to handle requests efficiently.

The Web Module processes incoming API requests and forwards them to the Service Module, which contains the business logic. The Service Module then interacts with the Repository Module to fetch or update data in the Database. This layered approach ensures that each module operates independently, promoting flexibility and easier maintenance.

Example Using Feign Client:

In the context of inter-module communication, using tools like Feign Clients is a powerful way to achieve loose coupling between services.

The Feign client allows one module to seamlessly communicate with another through REST API calls, without requiring direct dependencies. This approach fits perfectly within the layered architecture described earlier, where the Service Module can fetch data from other services or microservices using Feign clients, rather than directly accessing databases or hard-coding HTTP requests.

This not only simplifies the code but also improves scalability and maintainability by isolating service dependencies.

@FeignClient(name = "userServiceClient", url = "http://localhost:8081")
public interface UserServiceClient {
    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);
}

6. Common Pitfalls and Solutions

When implementing a multi-module architecture, you may encounter several challenges. Here are some common pitfalls and their solutions:

• Circular Dependencies: Modules may inadvertently depend on each other, creating a circular dependency that complicates builds and deployments.

  • Solution: Carefully design module interfaces and use dependency management tools to detect and resolve circular dependencies early in the development process.

• Over-Engineering: There's a risk of creating too many modules, leading to unnecessary complexity.

  • Solution: Start with a minimal set of modules and only split further when there's a clear need, ensuring each module has a distinct responsibility.

• Inconsistent Configurations: Managing configurations across multiple modules can lead to inconsistencies.

  • Solution: Use centralized configuration management tools, such as Spring Cloud Config, to maintain consistency across modules.

• Communication Overhead: Inter-module communication can introduce latency and complexity.

  • Solution: Optimize communication by using efficient protocols and consider asynchronous messaging where appropriate to reduce latency.

• Testing Complexity: Testing a multi-module project can be more complex due to the interactions between modules.

  • Solution: Implement a robust testing strategy that includes unit tests for individual modules and integration tests for inter-module interactions.

By being aware of these pitfalls and applying these solutions, you can effectively manage the complexities of a multi-module architecture and ensure a smooth development process.

7. Testing Strategy and Configuration

Testing each module independently and as a unit is critical in multi-module setups.

Unit Tests

Here, we’ll use JUnit and Mockito for performing unit tests:

@RunWith(MockitoJUnitRunner.class)
public class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    public void testGetUserById() {
        User user = new User();
        user.setId(1L);
        user.setName("John");

        Mockito.when(userRepository.findById(1L)).thenReturn(Optional.of(user));

        User result = userService.getUserById(1L);
        assertEquals("John", result.getName());
    }
}

Integration Tests

And we’ll use Testcontainers with an in-memory database for integration tests:

@Testcontainers
@ExtendWith(SpringExtension.class)
@SpringBootTest
public class UserServiceIntegrationTest {

    @Container
    private static PostgreSQLContainer<?> postgresqlContainer = new PostgreSQLContainer<>("postgres:latest");

    @Autowired
    private UserService userService;

    @Test
    public void testFindById() {
        User user = userService.getUserById(1L);
        assertNotNull(user);
    }
}

8. Error Handling and Logging

Error handling and logging ensure a robust and debuggable application.

Error Handling

In this section, we'll explore how to handle errors gracefully in your Spring Boot application using a global exception handler. By using @ControllerAdvice, we'll set up a centralized way to catch and respond to errors, keeping our code clean and our responses consistent.

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException ex) {
        return new ResponseEntity<>("User not found", HttpStatus.NOT_FOUND);
    }
}

In the code example above, we define a GlobalExceptionHandler that catches any UserNotFoundException and returns a friendly message like "User not found" with a status of 404. This way, you don’t have to handle this exception in every controller—you’ve got it covered in one place!

Now, let’s take a look at the diagram. Here’s how it all flows: when a client sends a request to our Web Module, if everything goes smoothly, you'll get a successful response. But if something goes wrong, like a user not being found, the error will be caught by our Global Error Handler. This handler logs the issue and returns a clean, structured response to the client.

This approach ensures that users get clear error messages while keeping your app’s internals hidden and secure.

Logging

Structured logging in each module improves traceability and debugging. You can use a centralized logging system like Logback and include correlation IDs to trace requests.

9. Security and JWT Integration

In this section, we’re going to set up JSON Web Tokens (JWT) to secure our endpoints and control access based on user roles. We'll configure this in the SecurityConfig class, which will help us enforce who can access what parts of our application.

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/admin/**").hasRole("ADMIN")
            .antMatchers("/user/**").hasAnyRole("USER", "ADMIN")
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}

In the code example above, you can see how we’ve defined access rules:

• The /admin/** endpoints are restricted to users with the ADMIN role.

• The /user/** endpoints can be accessed by users with either the USER or ADMIN roles.

• Any other requests will require the user to be authenticated.

Next, we set up our application to validate incoming tokens using .oauth2ResourceServer().jwt();. This ensures that only requests with a valid token can access our secured endpoints.

Now, let’s walk through the diagram. When a client sends a request to access a resource, the Security Filter first checks if the provided JWT token is valid. If the token is valid, the request proceeds to the Service Module to fetch or process the data. If not, access is denied right away, and the client receives an error response.

This flow ensures that only authenticated users can access sensitive resources, keeping our application secure.

10. Deployment with Docker and CI/CD

In this section, we'll containerize each module using Docker to make our application easier to deploy and run consistently across different environments. We’ll also set up a CI/CD pipeline using GitHub Actions (but you can use Jenkins too if you prefer). Automating this process ensures that any changes you push are automatically built, tested, and deployed.

Step 1: Containerizing with Docker

We start by creating a Dockerfile for the Web Module:

FROM openjdk:11-jre-slim
COPY target/web-1.0-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

Here, we’re using a lightweight version of Java 11 to keep our image size small. We copy the compiled .jar file into the container and set it up to run when the container starts.

Step 2: Using Docker Compose for Multi-Module Deployment

Now, we'll use a Docker Compose file to orchestrate multiple modules together:

version: '3'
services:
  web:
    build: ./web
    ports:
      - "8080:8080"
  service:
    build: ./service
    ports:
      - "8081:8081"

With this setup, we can run both the Web Module and the Service Module at the same time, making it easy to spin up the entire application with a single command. Each service is built separately from its own directory, and we expose the necessary ports to access them.

CI/CD Example with GitHub Actions

name: CI Pipeline

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up JDK 11
      uses: actions/setup-java@v2
      with:
        java-version: '11'
    - name: Build with Maven
      run: mvn clean install

This pipeline automatically kicks in whenever you push new code or create a pull request. It checks out your code, sets up Java, and runs a Maven build to ensure everything is working correctly.

11. Best Practices and Advanced Use Cases

The following best practices ensure maintainability and scalability.

Best Practices

• Avoid Circular Dependencies: Ensure modules don’t have circular references to avoid build issues.

• Separate Concerns Clearly: Each module should focus on one responsibility.

• Centralized Configurations: Manage configurations centrally for consistent setups.

Advanced Use Cases

1. Asynchronous Messaging with Kafka: Use Kafka for decoupled communication between services. Modules can publish and subscribe to events asynchronously.

2. REST Client with Feign: Use Feign to call services within modules. Define a Feign client interface for communication.

3. Caching for Performance: Use Spring Cache in the service module for optimizing data retrieval.

Conclusion and Key Takeaways

A multi-module Spring Boot project provides modularity, scalability, and ease of maintenance.

In this tutorial, you learned to set up modules, manage inter-module communication, handle errors, add security, and deploy with Docker.

Following best practices and using advanced techniques like messaging and caching will further optimize your multi-module architecture for production use.

The SOLID Principles were introduced by a software engineer named Robert C. Martin (also known as "Uncle Bob") in the early 2000s. Uncle Bob’s goal was to promote good software design practices, particularly in object-oriented programming (OOP), by addressing common problems developers face as software systems grow in size and complexity.

Here are the five SOLID principles:

• S: Single Responsibility Principle (SRP)

• O: Open-closed Principle (OCP)

• L: Liskov Substitution Principle (LSP)

• I: Interface Segregation Principle (ISP)

• D: Dependency Inversion Principle (DIP)

By following these principles, you can create software designs that are easier to understand, maintain, and extend, leading to higher-quality software that is more robust and adaptable to change.

In this article, to demonstrate each principle, I’ll first show you a bad code example in C# that violates the principle. We will then discuss the issues this bad code causes, and then solve those issues by refactoring the code to satisfy the principle.

First up we have the…

Single Responsibility Principle (SRP) in C

A class should have only one reason to change, meaning that it should have only one responsibility or purpose.

This principle encourages you to create classes that are more focussed and perform one single well-defined task, rather than multiple tasks. Breaking up classes into smaller, more focused units makes code easier to understand, maintain, and test.

An example that violates the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }

 public void Register()
 {
   // Register user logic, e.g. save to database...

   // Send email notification
   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", Email);
 }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

In this example, the User class manages user data (username and email), and contains logic for registering a user. This violates the SRP because the class has more than one reason to change. It could change due to:

• Modifications in user data management – for example adding more fields, such as firstName, gender, hobbies.

• Modifications to the logic of registering a user, for example we may choose to fetch a user from the database by their username rather than their email.

To adhere to the Single Responsibility Principle, we should separate these responsibilities into separate classes.

Refactoring the code to satisfy the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

public class UserService
{
 public void RegisterUser(User user)
 {
   // Register user logic...

   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", user.Email);
 }
}

In the refactored code, the User class is responsible solely for representing user data. The UserService class now handles user registration, separating concerns related to user data management from user registration logic. The UserService class is responsible only for the business logic of registering a user.

This separation of responsibilities adheres to the Single Responsibility Principle, making the code easier to understand, maintain, and extend.

Open/Closed Principle (OCP) in C

Software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.

This principle promotes the idea that existing code should be able to be extended with new functionality without modifying its source code. It encourages the use of abstraction and polymorphism to achieve this goal, allowing for code to be easily extended through inheritance or composition.

(By the way, if you don’t understand these fundamental OOP concepts, such as abstraction, polymorphism, inheritance and composition — then check out my book, Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon or Gumroad.)

Let's consider an example of a Shape class hierarchy that calculates the area of different geometric shapes. Initially, this violates the Open/Closed Principle because adding a new shape requires modifying the existing code:

public enum ShapeType
{
 Circle,
 Rectangle
}

public class Shape
{
 public ShapeType Type { get; set; }
 public double Radius { get; set; }
 public double Length { get; set; }
 public double Width { get; set; }

 public double CalculateArea()
 {
   switch (Type)
   {
     case ShapeType.Circle:
       return Math.PI * Math.Pow(Radius, 2);
     case ShapeType.Rectangle:
       return Length * Width;
     default:
       throw new InvalidOperationException("Unsupported shape type.");
   }
 }
}

In this example, the Shape class has a method, CalculateArea(), that calculates the area based on the type of shape. Adding a new shape, such as a triangle, would require modifying the existing Shape class, violating the OCP.

To adhere to the Open/Closed Principle, we should design the system in a way that allows for extension without modification. Let's refactor the code using inheritance and polymorphism:

public abstract class Shape
{
 public abstract double CalculateArea();
}

public class Circle : Shape
{
 public double Radius { get; set; }

 public override double CalculateArea()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Rectangle : Shape
{
 public double Length { get; set; }
 public double Width { get; set; }

 public override double CalculateArea()
 {
   return Length * Width;
 }
}

In this refactored code, we define an abstract Shape class with an abstract CalculateArea() method. Concrete shape classes (Circle and Rectangle) inherit from the Shape class and provide their own implementations of CalculateArea().

Adding a new shape, such as a triangle, would involve creating a new class – extending the codebase – that inherits from Shape and implements CalculateArea(), without modifying existing code. This adheres to the OCP by allowing for extension without modification.

Being able to add functionality without modifying existing code means that we don’t have to worry as much about breaking existing working code and introducing bugs.

Following the OCP encourages us to design our software so that we add new features only by adding new code. This helps us to build loosely-coupled, maintainable software.

Liskov Substitution Principle (LSP) in C

Objects of a superclass should be replaceable with objects of its subclass without affecting the correctness of the program.

This principle ensures that inheritance hierarchies are well-designed and that subclasses adhere to the contracts defined by their superclasses.

Violations of the LSP can lead to unexpected behavior or errors when substituting objects, making code harder to reason about and maintain.

Let's consider an example involving a Rectangle class and a Square class, which inherit from a common Shape class. Initially, we'll violate the LSP by not adhering to the behavior expected from these classes. Then, we'll fix it to ensure that the principle is respected.

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public virtual double Width { get; set; }

 public virtual double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Rectangle
{
 public override double Width
 {
   get => base.Width;
   set => base.Width = base.Height = value;
 }

 public override double Height
 {
   get => base.Height;
   set => base.Height = base.Width = value;
 }
}

Now, let’s test out if Rectangle calculates its area correctly:

// Program.cs

var rect = new Rectangle();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Running the program:

Expected area = 10 * 5 = 50.

Calculated area = 50

Perfect!

Now, in our program, the Square class inherits from, or extends, the Rectangle class, because, mathematically, a square is just a special type of rectangle, where its height equals its width. Because of this, we decided that Square should extend Rectangle – it’s like saying “a square is a (special type of) rectangle”.

But look what happens if we substitute the Rectangle class for the Square class:

var rect = new Square();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Expected area = 10 * 5 = 50.

Calculated area = 25

Oh dear, LSP has been violated: we replaced the object of a superclass (Rectangle) with an object of its subclass (Square), and it affected the correctness of our program. By modeling Square as a subclass of Rectangle, and allowing width and height to be independently set, we violate the LSP. When setting the width and height of a Square, it should retain its squareness, but our implementation allows for inconsistency.

Let’s fix this to satisfy LSP:

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public double Width { get; set; }

 public double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Shape
{
 private double sideLength;

 public double SideLength
 {
   get => sideLength;
   set
   {
     sideLength = value;
   }
 }

 public override double Area => sideLength * sideLength;
}

// Program.cs

Shape rectangle = new Rectangle { Width = 5, Height = 4 };

Console.WriteLine($"Area of the rectangle: {rectangle.Area}");

Shape square = new Square { SideLength = 5 };

Console.WriteLine($"Area of the square: {square.Area}");

In this corrected example, we redesign the Square class to directly set the side length. Now, a Square is correctly modeled as a subclass of Shape, and it adheres to the Liskov Substitution Principle.

How does this satisfy LSP? Well, we have a superclass, Shape, and subclasses Rectangle and Square. Both Rectangle and Square maintain the correct expected behavior of a Shape — we can substitute a square for a rectangle and the area will still be calculated correctly.

Interface Segregation Principle (ISP) in C

Clients should not be forced to depend on interfaces they do not use.

This principle encourages the creation of fine-grained interfaces that contain only the methods required by the clients that use them. It helps to prevent the creation of "fat" interfaces that force clients to implement unnecessary methods, leading to cleaner and more maintainable code.

Let's consider an example involving 2D and 3D shapes, initially violating the ISP.

Violating ISP:

public interface IShape
{
 double Area();
 double Volume(); // problem: 2D shapes don't have volume!
}

public class Circle : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   throw new InvalidOperationException("Volume not applicable for 2D shapes.");
 }
}

public class Sphere : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In this example, we have an IShape interface representing both 2D and 3D shapes. However, the Volume() method is problematic for 2D shapes, like Circle and Rectangle, because they don't have volume. This violates the ISP because clients (classes using the IShape interface) may be forced to depend on methods they do not need.

var circle = new Circle();
circle.Radius = 10;

System.Console.WriteLine(circle.Area());
System.Console.WriteLine(circle.Volume()); // My text editor doesn't flag a problem...

var sphere = new Sphere();
sphere.Radius = 10;

System.Console.WriteLine(sphere.Area());
System.Console.WriteLine(sphere.Volume());

Usually, if I try to call a method on an object that doesn’t exist, VS Code will tell me that I’m making a mistake. But above, when I call circle.Volume(), VS code is like “no problem”. And VS code is correct, because the IShape interface forces Circle to implement a Volume() method, even though circles don’t have volume.

It’s easy to see how violating ISP can introduce bugs into a program – above, everything looks fine, until we run the program and an exception gets thrown.

Fixing ISP

public interface IShape2D
{
 double Area();
}

public interface IShape3D
{
 double Area();
 double Volume();
}

public class Circle : IShape2D
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Sphere : IShape3D
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In the fixed example, we've segregated the IShape interface into two smaller, more focused interfaces: IShape2D and IShape3D. Each shape class now implements only the interface that is relevant to its functionality.

This adheres to the Interface Segregation Principle by ensuring that clients are not forced to depend on methods that they do not use. Clients can now depend only on the interfaces that they need, promoting better code reuse and flexibility.

Next up, the fifth and final SOLID principle…

Dependency Inversion Principle (DIP) in C

High-level modules should not depend on low-level modules. Both should depend on abstractions.

Dependency Inversion is the strategy of depending upon interfaces or abstract classes rather than upon concrete classes. This principle promotes decoupling between modules and promotes the use of interfaces or abstract classes to define dependencies, allowing for more flexible and testable code.

Let's start with an example violating the DIP and then we’ll correct it.

public class Engine // Engine is our "low-level" module
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car // Car is our "high-level" module
{
 private Engine engine;

 public Car()
 {
   this.engine = new Engine(); // Direct dependency on concrete Engine class
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

In this example:

• The Car class directly creates an instance of the Engine class, leading to a tight coupling between Car and Engine.

• If the Engine class changes, it may affect the Car class, violating the Dependency Inversion Principle.

The UML diagram below shows that Car depends on Engine:

But what do we mean by “high level” and “low level” classes?

High-Level Class: The high-level class is typically the one that represents the main functionality or business logic of the application. It orchestrates the interaction between various components and is often more abstract in nature.

In this example, the Car class can be considered the high-level class. It represents the main functionality related to starting the car and driving it. The Car class is concerned with the overall behavior of the car, such as controlling its movement.

Low-Level Class: The low-level class is usually one that provides specific functionality or services that are used by the high-level class. It typically deals with implementation details and is more concrete in nature.

In this example, the Engine class can be considered the low-level class. It provides the specific functionality related to starting the engine. The Engine class encapsulates the details of how the engine operates, such as ignition and combustion.

So in summary, the Car class is the high-level class, representing the main functionality of the application related to the car's behavior.

The Engine class is the low-level class, providing specific functionality related to the operation of the engine, which is used by the Car class.

Fixing DIP:

To adhere to the Dependency Inversion Principle, we introduce an abstraction (interface) between Car and Engine, allowing Car to depend on an abstraction instead of a concrete implementation.

public interface IEngine
{
 void Start();
}

public class Engine : IEngine
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car
{
 private IEngine engine;

 public Car(IEngine engine)
 {
   this.engine = engine;
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

We can now inject any type of engine into Car implementations:

var engine = new Engine(); // concrete implementation to be "injected" into the car

var car = new Car(engine);

car.StartCar();

From the UML diagram below, we can see that both objects now depend on the abstraction level of the interface. Engine has inverted its dependency on Car.

In this corrected example:

1. We define an interface IEngine representing the behavior of an engine.

2. The Engine class implements the IEngine interface.

3. The Car class now depends on the IEngine interface instead of the concrete Engine class.

4. Dependency injection is used to inject the IEngine implementation into the Car class, promoting loose coupling. Now, if we want to give a car a different type of engine, for example a FastEngine, we can inject that in instead.

5. Now, if the implementation of the engine changes, it won't affect the Car class as long as it adheres to the IEngine interface.

Dependency Injection (DI) offers several advantages in software development:

• Decoupling: DI promotes loose coupling between components by removing direct dependencies. Components rely on abstractions rather than concrete implementations, making them more independent and easier to maintain.

• Testability: Dependency injection simplifies unit testing by allowing components to be easily replaced with mock or stub implementations during testing. This enables isolated testing of individual components without relying on their dependencies.

• Flexibility: DI provides flexibility in configuring and swapping dependencies at runtime. It allows different implementations of dependencies to be used interchangeably without modifying the client code, facilitating runtime customization and extensibility.

• Readability and Maintainability: By explicitly specifying dependencies in the constructor or method parameters, DI improves code readability and makes the codebase easier to understand. It also reduces the risk of hidden dependencies, leading to more maintainable and understandable code.

• Reusability: DI promotes component reusability by decoupling them from their specific contexts or environments. Components can be designed to be independent of the application framework or platform, making them more portable and reusable in different projects or scenarios.

• Scalability: DI simplifies the management of dependencies in large-scale applications by providing a standardised approach for dependency resolution. It helps prevent dependency hell and makes it easier to manage and scale complex systems.

Overall, dependency injection enhances modularity, testability, and maintainability of software systems, contributing to improved software quality and developer productivity.

Conclusion

Congratulations – you now understand the extremely important SOLID principles. These principles are going to save you a lot of headaches during your software development career, and guide you towards creating beautiful, maintainable, flexible, testable software.

If you’d like to take your software development skills to the next level and learn:

• OOP principles: encapsulation, abstraction, inheritance, polymorphism, coupling, composition, composition vs inheritance, fragile base class problem.

• All 23 design patterns (“The Gang of Four Design Patterns”) with real world examples.

• Unified Modeling Language (UML): the standard way to model classes and the relationships between them.

Then check out my book:

Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon (also available on Gumroad).

Hopefully this article helps you to become a better OOP software developer!

Thanks for reading,

Danny 😎

The challenge is that architecture diagrams – if they even exist – are often outdated relics from a bygone era.

This is why creating and maintaining effective and clear diagrams should be effortless. Up-to-date visuals ensure everyone stays on the same page, eliminating confusion and wasted time.

Table of Contents

• What is the C4 Model?

• Level 1: Context

• Level 2: Containers

• Level 3: Components

• Level 4: Code

• Supplementary Diagrams

• Diagrams as Code

• Automate Rendering in Your CI

• Resources

What is the C4 Model?

The C4 model was created as a way to help software development teams describe and communicate software architecture.

C4 stands for “Context, Containers, Components, and Code”. Those are the four levels that should be enough to describe a complex system.

The best way to explain the concept is to think about how we use Google Maps. When we are exploring an area in Google Maps, we will often start zoomed out to help us get context. Once we find the rough area we are interested in we can zoom in to get a little more detail.

Level 1: Context

This level is the most zoomed out. It's a bird’s eye view of the system in the greater context of the world. The diagram concentrates on actors and systems.

For the examples below, we will use a simple Task Management Software System to demonstrate all these 4 levels.

This diagram portrays the Task Management Software System's interactions with external systems and the different user groups that utilize it. We can see that the Task Management software relies on two external systems: Email and Calendar, and two types of actors (users) use it: Customer and Admin User.

Level 2: Containers

The containers level is a more detailed view of your system (don’t confuse C4 containers with Docker containers).

It reveals how various functional units like applications and databases work together and distribute responsibilities.

This diagram also highlights the key technologies employed and showcases the communication flow between these containers. It presents a simplified, technology-centric view of the system's core components and their interactions.

If you have Microservice architecture, then each Microservice would be a container.

Examples of containers are:

• Single page application

• Web server

• Serverless function

• Database

• API

• Message buses

And so on.

This level delves into the internal composition of the Task Management Software System. It showcases that our Task Management software system consists of containers such as User Web UI, Admin Web UI, API and a Database. API is also the container that is connected to external systems, for example to send emails or create events in calendar.

Level 3: Components

The next level of zoom is components. This shows the major structural building blocks of your application, and is often a conceptual view of the application. The term component is loose here. It could represent a controller or a service containing business logic.

This diagram focuses on the internal structure of the API container within the Task Management Software System. It reveals that the API container houses crucial functionalities like CRUD operations (Create, Read, Update, Delete) for data manipulation and user authentication mechanisms. The CRUD components is the one that talks to the database.

Level 4: Code

The deepest level of zoom is the code diagram. Although this diagram exists, it is often not used as the code paints a very similar picture. However, in highly regulated environments and complex legacy projects this level can help to paint a better picture of inner intricacies of the software.

Supplementary Diagrams

Besides the 4 diagrams above, there are a couple more worth mentioning:

• Deployment diagram

• Dynamic diagram: to describe the process or a flow

On this diagram we show a Login Flow, which is not a container or component, but rather a software process that happens in our software system. It shows that Web/Admin UIs use JWT-based authentication for communication with the API and the JWT token is stored in local storage on a client side.

Diagrams as Code

The power of C4 comes with a diagram-as-code approach. This means treating your diagrams just like your codebase:

• Version control: Store them in a source control system (like Git) for easy tracking and collaboration.

• Collaboration: Work together on diagrams using pull requests, similar to code reviews.

• Automation: Integrate them into your build pipelines for automatic rendering with your preferred tools.

Helpful Tool: Structurizr

There are few tools to help with modeling and diagramming, but the most popular nowadays is Structurizr with their custom DSL (Domain Specific Language).

All you need is to get familiar with the DSL syntax, which is pretty simple. As long as you get used to it you will be able to create or update diagrams in no time.

Below you can see the DSL for our Task Management Software System.

workspace {
    model {
        # Actors
        customer = person "Customer" "" "person"
        admin = person "Admin User" "" "person"

        # External systems
        emailSystem = softwareSystem "Email System" "Mailgun" "external"
        calendarSystem = softwareSystem "Calendar System" "Calendly" "external"

        # Task Management System
        taskManagementSystem  = softwareSystem "Task Management System"{
            webContainer = container "User Web UI" "" "" "frontend"
            adminContainer = container "Admin Web UI" "" "" "frontend"
            dbContainer = container "Database" "PostgreSQL" "" "database"
            apiContainer = container "API" "Go" {
                authComp = component "Authentication"
                crudComp = component "CRUD"
            }
        }

        # Relationships (Actors & Systems)
        customer -> webContainer "Manages tasks"
        admin -> adminContainer "Manages users"
        apiContainer -> emailSystem "Sends emails"
        apiContainer -> calendarSystem "Creates tasks in Calendar"

        # Relationships (Containers)
        webContainer -> apiContainer "Uses"
        adminContainer -> apiContainer "Uses"
        apiContainer -> dbContainer "Persists data"

        # Relationships (Components & Containers)
        crudComp -> dbContainer "Reads from and writes to"
        webContainer -> authComp "Authenticates using"
        adminContainer -> authComp "Authenticates using"
    }
}

Let's dive into the most important parts:

workspace [name] [description] {
    model {
    }
}

Here we define our workspace which should have at least one model. A workspace can optionally be given a name and description.

customer = person "Customer" "" "person"
admin = person "Admin User" "" "person"

In this section we define our persons (for example, a user, actor, role, or persona) in the following format: person <name> [description] [tags].

You can use a similar format (name, description, tags) to identify the external systems:

        emailSystem = softwareSystem "Email System" "Mailgun" "external"
        calendarSystem = softwareSystem "Calendar System" "Calendly" "external"

To describe the internal software system we need to write a block that also shows its containers and components:

taskManagementSystem  = softwareSystem "Task Management System"{
    webContainer = container "User Web UI" "" "" "frontend"
    adminContainer = container "Admin Web UI" "" "" "frontend"
    dbContainer = container "Database" "PostgreSQL" "" "database"
    apiContainer = container "API" "Go" {
        authComp = component "Authentication"
        crudComp = component "CRUD"
    }
}

• Container format: container <name> [description] [technology] [tags]

• Component format: component <name> [description] [technology] [tags]

The rest of the model is the most interesting part where we define the relationships between all parts (systems, containers, components):

apiContainer -> emailSystem "Sends emails"

The following format is used: <identifier> -> <identifier> [description] [technology] [tags].

There are other features available in Structurizr DSL, such as styling, themes, visibility, etc. You can find find them here.

Automate Rendering in Your CI

Since you can host your models on GitHub, it is very easy to automate the pipeline for rendering the diagrams in the tools of your choice.

In our case, Structurizr has a GitHub Action that allows you to run structurizr-cli, a command line utility for Structurizr that lets you create software architecture models based upon the C4 model using a textual domain specific language (DSL).

This sample repository contains a workflow that simply generates a static page and publishes it to GitHub Pages.

name: Deploy static content to Github Pages

on:
  push:
    branches: ["main"]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/avisi-cloud/structurizr-site-generatr
      options: --user root
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Create site
        run: |
          /opt/structurizr-site-generatr/bin/structurizr-site-generatr generate-site -w diagram.dsl
      - uses: actions/upload-artifact@v3
        with:
          name: website
          path: build/site
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: website
          path: build/site
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: "build/site"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

This Github Action uses Structurizr CLI action to compile our DSL file as HTML and publish it to Github Pages.

Conclusion

I believe that creating and maintaining effective and clear diagrams should be effortless. Up-to-date visuals ensure everyone stays on the same page, eliminating confusion and wasted time.

The C4 model and a bit of automation with Structurizr DSL can help make this process faster and keep diagrams close to the codebase. The whole process can now be automated as well into your SDLC.

Resources

• Github Repository

• C4 Model

• DSL Language Reference

• C4 DSL Visual Studio Code Extension

• structurizr-cli-action

• Discover more articles from packagemain.tech

As the Buddha said, "All conditioned things are impermanent."

In this article, we'll look at how the concept of time to live can help us with this type of data and when it makes sense to use it.

Table of Contents

1. What is Time to Live (TTL) in Distributed Systems?
2. How to use TTL in Message Queues (AWS SQS)
3. How to use TTL in Object Storage Systems (AWS S3)
4. How to use TTL in Databases (AWS DynamoDB)
5. How to use TTL in Event Based Architecture
6. Summary

What is Time to Live (TTL) in Distributed Systems?

TTL, as the name suggests, is the amount of time a piece of data stays relevant or stays stored in a distributed system or a component of a distributed system. A TTL may be set on any piece of data that isn't needed indefinitely.

Knowing when and when not to use a TTL can sometimes be tricky. It can also affect the way a system is designed, cost and scaling considerations. In the following sections, we learn about when and when not to use TTL.

Where does TTL make sense?

As mentioned above, it makes sense to use TTL for any piece of data that is ephemeral. Some common examples of use cases where you can set a TTL on data are:

1. Cached data: Cached data is pretty much omnipresent in distributed systems. For instance, a very popular social media post's resources (image, video, audio) may be cached on a CDN (Content Delivery Network)'s servers. You don't want this data to live forever on the server, so in some cases it may make sense to add a TTL to this data, so that it is automatically removed after a certain period of time.
2. Analytics Data: Most if not all large scale systems store some form of metrics that help analyze things like latency, system health, and product metrics amongst others. In a large number of cases, you wouldn't want these metrics to be stored in systems forever. Only recent data (say 60 days or 180 days) may be useful in most cases. A TTL on data in this case makes sense, especially if you have constraints on memory.
3. Indexed data: Search is a feature that's ubiquitous across products. Be it social media apps, e-mail or search engines – indexed data is vital to blazing fast searches. Indexed data, however, can become stale after a while, so it makes sense for the index to expire after some time. Hence, a TTL here can be useful.
4. Social media apps with short lived content: Social media apps with short lived content are extremely popular and images/videos posted are often short lived. In case these images do not need to be stored for posterity, they can benefit from a TTL being set on them. In addition to being memory efficient, it also aids privacy.

Where does TTL not make sense?

In the above section we looked at a few cases where TTL makes sense. What about cases where TTL isn't common and isn't useful? Let's look at some examples:

1. Media stored for streaming platforms: Streaming platforms often use cloud storage solutions such as Amazon AWS S3 to store objects that correspond to the media they stream to customers. These forms of media are generally not ephemeral and are expected to stay on platforms for years if not decades. Since such data isn't expected to expire anytime, TTL does not make sense here.
2. Bank transactions: Bank transactions produce some of the most sensitive data that are stored in cloud-based and distributed systems. For audit and book-keeping purposes, these pieces of data are generally stored for decades. So, since this data seemingly never expires, there's generally no use for a TTL here. This isn't to say that this form of data can't be moved from fast access databases/caches to slower and cheaper forms of data storage, though.

How to Use TTL in Message Queues (AWS SQS)

AWS SQS is a distributed message queuing solution that is the backbone of many versatile distributed systems across the world. Message queues can process billions of messages and are used almost universally across distributed systems around the world.

In this section, we'll look at how TTLs can be useful while we consider design options with respect to message queues.

What happens if a message queue's consumers have been backed up for several days, or messages simply haven't been consumed for a while? We have the option of setting a custom Time To Live on SQS messages.

By default, the retention period is 4 days. The maximum TTL at the time of writing is 14 days. So it's important to be aware of constraints such as these while using AWS SQS to design systems.

Note that with AWS SQS, a retention period is a set on the queue itself, and not individually for each message.

Boto is an AWS SDK for Python that enables developers to create, configure, and manage AWS services and resources programmatically. Boto is widely used for prototyping, production systems, and in general offers a user-friendly interface for accessing services like S3, EC2, and DynamoDB.

Here's a code snippet using Boto that will help you set the MessageRetentionPeriod attribute which is the formal name for TTL in this context.

sqs = boto3.client('sqs', 
aws_access_key_id=your_aws_access_key_id, 
aws_secret_access_key=aws_secret_access_key, 
region_name='your_region')

# Set the desired retention period in seconds
retention_period_seconds = 86400  # Example: 1 day

# Set the queue attributes
response = sqs.set_queue_attributes(
    QueueUrl=your_queue_url,
    Attributes={
        'MessageRetentionPeriod': str(retention_period_seconds)
    }
)

Visibility Timeout in Message Queues (AWS SQS)

Note that while it's tempting to think of Visibility Timeout in SQS as Time To Live, these aren't the same. Time To Live or Retention Period is different from Visibility Timeout.

Visibility timeout instead refers to a generally shorter period of time by which a message should be processed (once picked up by a consumer). If not, it is back in the SQS queue and visible to consumers again, with its receive count having been increased by one.

How to Use TTL in Object Storage Systems (AWS S3)

The all-versatile AWS S3, which is an object storage solution, gives users the ability to set a Time To Live on objects stored in S3 buckets.

S3 is extremely flexible with the way TTLs are set on objects / buckets. You can set Lifecycle rules to specify what objects or what versions of an object you'd like to remove.

Managing your storage lifecycle is a great read on the AWS Documentation website.

How to Use TTL in Databases (AWS DynamoDB)

Some types of data in databases are prime candidates to have a TTL set on them. Pieces of data such as logs and analytics data may become stale very fast, and/or they may lose utility with time.

TTL in DynamoDB provides a cost-effective approach that lets you automatically remove items that are no longer relevant. It is supported natively and can be set on the whole DynamoDB table.

Here's a code snippet that lets you set the TTL on a DynamoDB table (again, using Boto):

ddb_client = boto3.client('dynamodb')

# Enable Time To Live (TTL) on an existing DynamoDB table
ttl_response = ddb_client.update_time_to_live(
    TableName=your_table_name,
    TimeToLiveSpecification={
        'Enabled': True,
        'AttributeName': your_ttl_attribute_name
    }
)

# Check for a successful status code in the response
if ttl_response['ResponseMetadata']['HTTPStatusCode'] == 200:
    print("Time To Live (TTL) has been successfully enabled.")
else:
    print(f"Failed to enable Time To Live (TTL)")

Here, the your_ttl_attribute_name attribute is the attribute that DynamoDB looks at to determine whether or not the item is to be deleted. The attribute is generally set to some timestamp in the future. When that timestamp is reached, DynamoDB removes the item from the table.

How to Use TTL in Event-Based Architecture

So far we've discussed Time To Live and where it can be useful. What about its implications? Lots of cloud based solutions provide notifications that can indicate that a piece of data has indeed reached it's expiration, and allow you to take actions based on the expiration of that data.

Let's look at a common use case. Suppose you have a social media app that you're building that lets users send each other ephemeral messages. Now while the contents of these messages themselves are ephemeral, you may still want to retain a log of what users a particular user exchanged messages with, even though the contents of the message (audio/video/image) may have expired.

The diagram below explains a possible architecture in a little more detail:

Social Media App Architecture Example

Suppose a user exchanges messages with another user. An entry corresponding to a message is stored in ActiveMessageDB which, for the purpose of simplicity, we'll suppose is a NoSQL database that stores messages.

If the app here allows for expiring messages, you could set a TTL on the entry. While the message entry itself is deleted after the TTL is reached, an event can be fired off to let a system know that the message is being deleted.

In the above diagram, the event is picked up by an AWS Lambda instance and a much smaller amount of data is written to another database MessageLogDB which isn't as frequently accessed as ActiveMessageDB. What we just saw is an instance of event-based architecture being coupled with TTL.

Summary

1. TTL is the amount of time a piece of data stays relevant or stays stored in a distributed system or a component of a distributed system.
2. TTL makes sense in use cases where data can be deleted, can expire, or its form can change after a certain period of time.
3. TTL is popular and generally easy to set on many distributed systems offerings.
4. TTL can be paired with event driven architecture to transform data.

This article will explain how auto scaling and load balancing work and why they're important to consider in your designs. It will also go through example architectures showing auto scaling and load balancing in action.

Table of Contents

1. Auto Scaling Explained

2. Dynamic Scaling

3. Scheduled Scaling

4. Why use Auto Scaling

5. Load Balancing Explained

6. Why use Load Balancing

7. Bringing it Together – Load Balancing and Auto Scaling in Action

Auto Scaling Explained

Auto scaling, as its name implies, is simply a way to automatically scale your compute instances. With most cloud providers like AWS, GCP and Azure, you select scaling policies that define how it will add or remove instances.

Scaling policies are simply rules that say how much you should increase or decrease the number of instances based on some predefined metric.

Scaling policies can be dynamic, for example, by adding new instances based on CPU utilisation of the existing instances. Scaling policies can also be based on a schedule, that is based on specific times of the day or the week when you anticipate higher or lower demand.

Dynamic Scaling

Dynamic scaling is ideal for when there is a large fluctuation of demand at unknown and unpredictable times. You know there may be a sudden surge or drop in demand on your instances, you just don’t know when.

Using a restaurant analogy, think of an instance as a chef doing the work of converting orders into meals. If you only have three chefs and don’t have large fluctuations in demand throughout the day or week, you have nothing to worry about.

But if your restaurant had a sale that was more popular than anticipated, or a large party of tourists were to suddenly descend upon the restaurant, how would you cope? What if you could add more chefs on the fly immediately when needed?

This is how dynamic auto scaling works. Dynamic scaling will cause chefs to spontaneously appear in the kitchen, ready to transform orders into delicious meals, based on a predefined metric that you can choose to measure how overworked the chefs are – that is, how much they are struggling to fulfill current orders.

Remember that these scaling policies are simply rules. These rules can be very simple, like:

if CPU utilisation is > 50%, add one more instance. If CPU utilisation is <50%, remove an instance.

These rules can also be more complex.

With AWS and GCP, for example, you can set a target tracking metric that will monitor the CPU performance of your scaling group and add or remove instances so that that the average CPU utilisation approximately matches your desired setting.

For example, if you specify that you want the average CPU utilisation of your scaling group to be at 60%, instances will be added or removed as required to approximately meet that target.

Using CPU utilisation to trigger a scaling action is one of the most popular patterns. But CPU utilisation is not the only metric you can use to scale. In some ways, it can actually be suboptimal to use CPU utilisation, especially if you want even more responsive scaling.

What if you could track another metric that anticipates the increase in CPU utilisation so you don’t have to wait for the inevitable increase in the CPU utilisation of your instances before a scaling action is triggered?

With GCP, for example, if you have an HTTP load balancer in front of your instances, you can configure your scaling to be triggered based on the number of requests hitting your load balancer. Similarly with AWS, if you have an SQS queue in front of your instances, you can scale based on the number of messages in the queue.

In both of these examples, something else anticipates a likely increase in future CPU utilisation, so setting a scaling action to be triggered based on this is a way of creating more responsive scaling.

Bringing back our restaurant analogy, this would be like calling in more chefs to the kitchen once you see a large queue outside the restaurant. This is a more responsive way of dealing with a sudden surge in demand compared to waiting until your chefs are overwhelmed with orders.

Scheduled Scaling

Scheduled scaling is ideal for when there is a large fluctuation in demand at known times.

Using the restaurant analogy again, your scaling policy can be based on a schedule. So for example, if you know evenings and weekends are busier than mornings and weekdays, your scaling policy will ensure that there are more chefs during periods of higher expected demand.

With AWS and GCP, you can set a scheduled scaling policy to add or remove instances at specific times.

Why Use Auto Scaling?

Auto scaling solves the age old problem of capacity planning. Trying to accurately forecast how much compute will be required in the future is fraught with errors. Too little capacity, and your website is down during periods of high demand, costing you money and reputation. Too much capacity, and you are paying for unused instances.

Capacity planning is fundamentally a forecasting problem. And humans are not great at accurately forecasting the future. Before cloud providers like AWS, GCP, and Azure existed, companies needed to plan capacity based on expected future demand. This planning process was often just disguised guesswork. You had to pay upfront for servers and hope you didn’t significantly under or overestimate how many servers you needed.

The problem with forecasting arises because we have a misguided faith in the precise measurement of the unknowable future. Humans have been making inaccurate forecasts for a long time. As far back as 600 BC, the Greek philosopher Thales was so intent on counting the stars that he kept falling into potholes on the road.

Some things are fundamentally unknowable, and that is ok. Auto scaling removes the need to accurately forecast future demand since you can automatically increase or decrease the number of instances you have based on your scaling policy.

By using auto scaling, you get to improve the resilience of your architecture and reduce costs. These are the two main reasons to use auto scaling in your designs.

Improve Resilience

Being able to automatically and immediately increase the number of instances in response to growing demand reduces the chances that your instances are under excessive load and at risk of poor performance. This improves the resilience of your architecture.

Auto scaling is, however, not only about scaling. It can also be used to maintain a set number of instances. This is a great way of creating self healing architectures.

With AWS, you can set your minimum, maximum, and desired number of compute instances, without any scaling policy. AWS will simply attempt to maintain the desired number of instances specified by you. So if you set the min, max, and desired all equal to one, AWS will maintain one instance for you. If this instance fails, another will be automatically created to replace the failed instance to restore your desired capacity.

This is a cheap and easy way of ensuring high availability without having multiple instances in different availability zones.

Self healing in action, figuratively

The ability to create self healing architectures is a really strong argument to almost always place your instances in an auto scaling group. AWS and GCP do not, as of this writing, charge you for the privilege of using auto scaling. You only pay for the underlying infrastructure that is created to support your instances.

So, even if there is no requirement to be able to scale instances based on the demand thrown at them, having instances in an auto scaling group is a cheap and easy way of creating a self healing architecture.

Reduce Cost

Previous examples have been about scaling up the number of instances to meet higher demand. But equally as important is the ability to scale down during periods of lower demand.

Auto scaling allows you to do this using scheduled or dynamic scaling policies. This is a great way of ensuring that you are not paying for more than you need to.

Load Balancing Explained

Load balancers accept connections from clients and distribute the requests across target instances. The distribution of requests is usually done on layer 7 (application layer) or layer 4 (transport layer). These layers are a theoretical model that organises computer networking into 7 layers and is know as the OSI model.

I won't go into too much detail on the OSI model here, but for now, what is important to know is that most load balancers can work on the application layer or transport layer. This means that they work with layer 7 protocols like HTTP(S) or layer 4 protocols like TCP, UDP, SMTP, SSH.

The example in this section will only cover the more popular layer 7 application load balancers that work with HTTP/HTTPS.

While the low level implementation details and use cases between layer 7 and layer 4 load balancers are different, the principles remain the same. Load balancers are used to distribute incoming traffic across a number of target instances

The distribution of the requests among the target instances typically uses a round robin algorithm where requests are sent to each instance sequentially. So, request #1 goes to instance #1, request #2 to instance #2, request #3 to instance #3, request #4 again comes to instance #1, and so on.

While other balancing algorithms exist, the round robin algorithm is the most popular one used by most cloud providers for load balancing.

A simple view of how load balancers distribute requests

The diagram above is a logical depiction of how load balancers work. It only shows one load balancer, which is not a very resilient design. This logical abstraction is easy to illustrate, but is not accurate.

Behind the scenes, multiple load balancer nodes are deployed into each subnet within an availability zone. The load balancer is created with a single DNS record that points at all the elastic load balancer nodes created – that is, this single DNS record points at all of the IP addresses of the actual nodes deployed. All incoming requests are distributed equally across all the load balancer nodes and the load balancer nodes in turn equally distribute requests to target instances. In this way, you don’t have a single point of failure.

A more realistic, albeit more complex, representation of how load balancers work is shown below. In this example, requests will come to any of the load balancer nodes deployed across the three subnets and then they are equally distributed across the target instances.

A more accurate view of how load balancers distribute requests

Why Use Load Balancing?

Load balancers ensure that traffic is distributed among the target instances. This spreads out the load and prevents a single instance from being overloaded with an excessive number of requests.

Load balancers also create a loosely coupled architecture. Loose coupling is generally sought because it mans that users don't have to be aware of the instances, or instances don't need to be aware of other instances.

What exactly does being “aware” mean? Since user requests are first sent to the load balancer, users are not aware of the instances actually responding to their request. All communication is done via the load balancer, so it becomes easy to change the type and number of instances without the user being aware of it. The load balancer is aware of the instances in its target so it can send the request to all relevant instances.

Bringing it Together – Load Balancing and Auto Scaling in Action

The diagram below shows load balancing and auto scaling used for a three tiered web application consisting of web, application, and database tiers. Each of these tiers have separate instances/infrastructure.

Load balancing and auto scaling used for a three tiered web application consisting of web, application, and database tiers.

The instances in the web and application tiers are in separate auto scaling groups. There is also a load balancer between the user and the web tier, and between the web tier and the application tier.

By having a load balancer between the user and the web tier, the web tier can scale independently, using the auto scaling feature to add or remove instances as needed.

The user does not need to know which instance to connect to as the connection is through a load balancer. This is loose coupling in action. The same logic applies between the web tier and application tier. Without the load balancer, the instances in the two tiers would be tightly coupled, making scaling difficult.

The database tier in this case is an RDS database with one master and two standby nodes. All reads and writes go to the master node and if this node fails, there is an automatic failover to one of the standby instances.

Auto scaling ensures:

1. Resilience, as it can automatically and immediately increase the number of instances in response to growing demand. It can also self heal, so even if you don’t anticipate the need for immediate and automatic scaling based on changes to demand, self healing is almost always desired as it increases the availability of your architecture

2. Cost control, as it has the ability to scale in and reduce the number of instances used during periods of lower demand can save you money

Load balancing ensures:

1. Distribution of load, as it prevents a single node being overloaded with requests

2. Loose coupling, as it removes the need for awareness between users and instances, and between instances themselves. This allows for instances to scale independently

Thank you for reading!

The consequences of this seemingly simple and innocuous decision are potentially significant, and they're often not fully thought through. A wrong decision can be very expensive, not just financially, but also expensive with regard to the time required to develop the application and the time required to deploy any future changes.

There is no objectively correct approach, though. It all depends on what problem you are trying to solve and what trade-offs you are able to live with.

This article will explain the differences between monoliths and microservices as well as some heuristics to help you decide how to choose between the two architectures.

Table of Contents

1. Monoliths vs Microservices: An Analogy

2. What is a Monolith?

3. What are Microservices?

4. Data Management in Microservices

5. Database Isolation in Microservices

6. How to Choose Between Monoliths and Microservices

7. Why you should start with a Monolith

8. Why you should start with a Microservice

9. Hybrid Architecture – A Middle Ground

10. Bringing it Together

Monoliths vs Microservices: An Analogy

Before we go into the technical details of monoliths and microservices, let’s quickly explain the difference between the two architectures using an analogy.

A monolithic architecture is like a typical restaurant, where all kinds of dishes are prepared in one large kitchen and a single menu is presented to guests to choose from.

Just as the restaurant offers everything from starters to desserts in one place, a monolith includes all functionalities in one codebase.

A typical restaurant is like a monolithic application

A microservice architecture is like a food court composed of several small, specialised stalls, each serving a different type of cuisine. Here, you can pick and choose dishes from various stalls, each expertly preparing its own menu.

A food court is like a microservice application

In a microservice architecture, the application is divided into smaller, independent services. Just as each stall in the food court manages its own menu, staff, and kitchen, in a microservice architecture, different services run separately and are responsible for handling their specific functionalities.

Customers can pick and choose dishes from any stall, mixing and matching as they like, just as different microservices can be used in combination to create a comprehensive application. Each service is self-contained and communicates with other services through simple, well-defined interfaces.

What is a Monolith?

In a monolith, all the code needed for the all the features of the application is in a single codebase and gets deployed as a single unit.

Let's look at an e-commerce application, for example. Some of the important features of an e-commerce application are:

1. Product search service: Manages product listings, descriptions, inventory, prices, and categories. It's responsible for providing up-to-date information about products to other services and users.

2. Payment service: Handles processing of payments and transactions. It interacts with external payment gateways and provides secure payment options to customers.

3. Order management service: Manages the lifecycle of customer orders from creation to completion. This includes handling order processing, status updates and order cancellation.

4. Recommendation service: Provides personalised product recommendations to users based on their search history and past purchases.

In a monolithic application, the code for these features will be in a single codebase and deployed as a single unit. This is illustrated in the image below where the application is deployed to a single server with a separate database.

Monolithic e-commerce application deployed on a single server

The database is hosted on a separate server to improve performance and security, while the application servers handle the business logic.

Even in a monolithic architecture, the application can be duplicated and deployed across multiple servers, with a load balancer distributing traffic between the servers. This is illustrated below:

Monolithic e-commerce application deployed on two separate servers

What are Microservices?

Microservices are independently deployable services modeled around a business domain.

In contrast to a monolithic architecture, where all the application components are tightly integrated and deployed as a single unit, a microservices architecture breaks down the application into smaller, independently deployable services. Each service runs its own process and communicates with other services over a network, typically using HTTP/REST, RPC, or message queues.

We can brea the monolithic e-commerce application we talked about above down into a microservice architecture, as shown below:

Microservice e-commerce application

The following are some key differences between the monolithic and microservices e-commerce application:

In the microservice architecture, every feature of the application is in a separate codebase. This separation ensures we have independently deployable services modeled around business domains (Product Search Service, Payment Service, Order Management Service and Recommendation Service).

Having a separate codebase for every service ensures:

1. Simplified deployment: With each service in its own codebase, it can be updated, tested, and deployed independently of others.

2. Fault Tolerance: Separate codebases contribute to fault tolerance. If one service experiences a failure, it does not necessarily compromise the operation of others. This is crucial for maintaining the overall system's availability and reliability. For example, if the payment service fails, only customers that want to purchase an item will be affected. Other customers can still search through the application for things to buy, track existing orders, and get recommendations for things they might want to buy.

3. Technology Flexibility: Separate codebases allow each service to be developed using the technology stack best suited to its needs. Different teams can choose different programming languages, frameworks, or databases depending on what works best for the specific functionality of that service.

4. Each service is deployed on its own servers. The servers hosting each service can be scaled independently based on its specific demand and resource requirements. This is much more efficient than scaling a monolithic application where scaling up often means scaling the entire application, even if only one part of it is under heavy load. For example, the payment service might be really busy during a promotion/sale. This can be independently scaled instead of scaling the entire application, which can be a waste of money.

Each service has its own database (if it needs a database). This ensures:

1. Every microservice can run independently of other services. If every service used the same database (as is the case in a monolithic application), a database failure will bring down the entire application.

2. The databases can be scaled independently as needed. Some databases will be busier than others, so having the flexibility to scale them independently is useful.

3. Every microservice uses the right type of database. Some microservices might function better with different types of databases. For example, Elasticsearch would be ideal for the product search database of the e-commerce application due to its powerful full-text search capabilities, while a relational SQL database will be better suited for the order and payment databases.

4. An API Gateway sits in front of the services. This acts as the middle-man between users and the many services they may need to access. The API Gateway handles authorisation and authentication, request routing and rate limiting.

Data Management in Microservices

Managing data between services is the most complex part of a microservice architecture. Communication between services is either synchronous or asynchronous.

Synchronous Communication: Services communicate directly with each other. This is a straightforward approach, easy to understand and implement.

For example, in an e-commerce application, when a customer places an order, the Order Management Service might directly call the Product Search Service to check if the item is in stock before proceeding.

Asynchronous Communication: Services do not wait for a direct response from another service. Instead, they communicate through events or messages using a message broker.

In the e-commerce example, when a new order is placed, the Order Management Service will publish an "Order Created" event to a message queue. The Product Search Service, subscribing to this queue, reacts to the event at its own pace and updates the inventory accordingly. This decouples the services, allowing them to operate and scale independently.

Synchronous communication is simpler to understand and implement but lacks fault tolerance.

Database Isolation in Microservices

In a microservice architecture, it is a standard practice to prevent services from directly accessing the databases of other services. You'd typically do this to ensure that each service can manage its data schema independently, without affecting other services.

Looking back at our e-commerce example, suppose the Payment Service decides to change its data schema and rename a column called “amount” to “order_value”, as “amount” can be quite an ambiguous term. If the Order Management Service were directly querying the Payment Service’s database, any direct SQL queries from the Order Management Service to the Payment Service’s database on this column would fail because of this schema change.

To handle these dependencies and changes securely and efficiently, the services should interact via APIs rather than via direct database access. By providing an API as an interface, the Payment Service can abstract the complexities of its underlying data model.

For instance, regardless of whether the database field is named “amount” or “order_value”, the API can expose a parameter called “payment_amount”. This allows the Payment Service to internally map “payment_amount” to whatever the current database schema is using.

How to Choose Between Monoliths and Microservices

Choosing between a monolith and a microservice architecture depends on what problem you are trying to solve and what trade-offs you are able to live with.

Microservices are newer and more popular with the large technology companies. Most technical books and blogs cover the architectures of these large companies.

But the engineering problems of large companies operating at scale are not necessarily the same engineering problems faced by smaller companies.

Copying what the large technology companies do is reasoning by analogy. This is not necessarily wrong, but it can introduce unnecessary complexities for a smaller company/startup. Better to reason by first principles, or better yet, choose better analogues.

You can look at what other startups are doing, or what the technology giants of today did when they were much smaller. For example, Etsy, Netflix and Uber all started as monoliths before migrating to a microservice architecture.

Why you should start with a Monolith

Creating an application should be done for one reason and one reason alone: to build something that people want to use. Users of your application do not care if you use a microservice or monolith. They care that you are solving a problem for them.

To quote Paul Graham:

“Almost everyone’s initial plan is broken. If companies stuck to their initial plans, Microsoft would be selling programming languages and Apple would be selling printed circuit boards. In both cases, their customers told them what their business should be and they were smart enough to listen”.

There is arguably no need to spend so much time designing and implementing a highly complex microservice architecture when you are not even sure that you are building something that people want to use.

So, why should you start with a monolith when building an application?

1. Simplicity: A monolith does not require dealing with the complexities of a distributed system, such as network latency, data consistency, or inter-service communication. This lack of complexity not only makes the initial development phase smoother but also reduces the overhead for new developers, who can contribute more quickly without having to understand the intricacies of a distributed system

2. Ease of Iteration: In the early stages of a product, rapid iteration based on user feedback is critical. The product direction is still evolving, and quick pivots or adjustments are necessary based on user input. This is usually easier to achieve with a simple monolithic architecture.

3. Low Cost: Running a monolithic application can be less expensive in the early stages, as it typically requires less infrastructure and fewer resources than a distributed microservices architecture. This is crucial for startups and small businesses where money can be in short supply.

Beginning with a monolith often aligns better with the practical realities of launching and iterating on a new application.

Why you should start with a Microservice

1. Scalability from the Start: One of the strongest arguments for microservices is their innate ability to scale. If you anticipate rapid growth in usage or data volume, microservices allow you to scale specific components of the application that require more resources without scaling the entire application. This can be particularly valuable for applications expected to handle varying loads or for services that might grow unpredictably.

2. Resilience: Microservices enhance the overall resilience of the application. Because each service is independent, failures in one area are less likely to bring down the whole system. This isolation helps in maintaining resilience by ensuring that parts of your application can still function even if others fail.

3. Flexible Tech Stacks: Microservices allow different teams to use the technology stacks that are best suited for their specific needs. Going back to our e-commerce example, the other services may be written in Java, but the recommendation service can be written in Python if the team responsible for building that has more expertise in Python. This is a very crude example, but the principle holds. A microservice architecture gives teams flexibility on which technology they can use. Taken to its logical extreme, this can also be a flaw since it can add additional complexity to the overall architecture. Introducing a different language for a service might require different build tools and deployment processes.

Hybrid Architecture – A Middle Ground

The formal, academic definition of a microservice is that it is an independently deployable service modeled around a business domain. Under the thumb of this definition, each business domain should be a separate service.

But you're not confined to this strict definition when it comes to implementing a design. Let’s look at our e-commerce microservice application again.

Microservice e-commerce application

We can choose to keep the product search service as a microservice. Since more people search for products than buy them, we may want the ability to scale this service independently of the others.

Also, this service will need its own dedicated full text search database like Elasticsearch or Solr. SQL databases are not well-suited for full text search and product filtering.

We can also choose to keep the recommendation service as a microservice since this will be written in a different language from the other services. This service will also need its own separate graph database like Neo4j to help make recommendations to users about what to buy based on their past searches and purchases.

We are left with the payment service and the order management service which can be combined into a monolith. This is illustrated below.

Hybrid monolithic/microservice architecture

In this example, we haven’t followed the academic definition of a microservice architecture, where every service is modeled around a business domain. Instead, we have chosen to be pragmatic and create microservices because we want to use a specific technology and because we want to be able to scale some services independently.

Bringing it Together

In a monolith, all the code needed for the all the features of an application is in a single codebase and is deployed as a single unit. In a microservices architecture, the application is divided into smaller, independent components, each responsible for specific features or functionalities. Each microservice has its own codebase and can be deployed independently of others.

Choosing between a monolith and a microservice depends on the problem you are trying to solve and what trade-offs you are able to live with.

Monoliths provide simplicity, ease of iteration and low cost. Microservices provide scalability, resilience and a more flexible tech stack.

For startups, the simplicity, ease of iteration, and cost-efficiency of a monolithic architecture make it an ideal initial choice, allowing them to focus on developing core features and finding product-market fit without the overhead of managing a distributed system.

For a more established company with growing needs for scalability, resilience, and technological flexibility, a microservice architecture can be a better choice.

These devices inevitably use power and have batteries and circuits, which degrade over time. As time passes, these devices get replaced by newer upgraded ones. But this also means that more and more electronic waste builds up on our planet.

Also, since we have more electronic devices entering our ecosystem every day, we’re also using more power, leading to more carbon emissions.

This means we need to design both hardware and software in a way which acknowledges that the earth’s resources are limited. This article will give you an introduction on how you can architect your software for sustainability.

Here is what we'll cover:

• Prerequisites
• Why are we thinking about this now?
• What's involved in architecting and programming for sustainability?
• Profile your software for power and energy consumption
  • Energy Delay Product
  • Greenup, Powerup and Speedup
  • Tools for Profiling
• Software Techniques and Design Patterns for Sustainability
  • Consider which programming language to use
  • Make software Power aware: React to Thermal events
  • When appropriate use low power states on hardware
  • Investigate the tradeoffs between Interrupt driven I/O and Polling
  • Look into Caching
  • Design software with lifetime and updatability in mind
• Conclusion

##Prerequisites

I wrote this article with a focus on general ideas in computer science. This lecture will help with some background on Power and Energy in electrical circuits.

Other parts of this article provide references wherever you might need some background.

Why Are We Thinking About this Now?

Human made climate change has been steadily accelerating for decades. Carbon emissions have been rising. As a part of the technology community, we can help reduce some factors which have been contributing towards the degradation of the earth’s environment.

In this article I will present a few ideas and techniques on how you as a programmer and a software architect can make choices which will lead to more sustainable technology.

What's Involved in Architecting and Programming for Sustainability?

In the context of this article, when I describe architecting software and programming for sustainability, I’m referring to the following aims:

Designing software so that it:

1. Consumes the smallest amount of energy possible, to get the task at hand done.
2. Results in the least amount of battery degradation possible, while maintaining the minimum amount of performance needed for the task.
3. Needs a minimum amount of cooling for the hardware that it is running on.
4. Results in devices lasting longer.

You’ll see that the techniques we'll discuss here all have the same theme behind them: make electronic hardware do the minimum amount of work possible to complete the task at hand.

Let's start with some techniques that you can use to accomplish this while architecting and writing software.

##Profile Your Software for Power and Energy Consumption

A problem which cannot be measured, cannot be solved. As a result, measuring the energy and power consumption of software is one of the most important tasks we need to do when designing with sustainability in mind.

Let’s take a step back and cover some of the basics of power and energy.

As you may know, power is the rate at which energy is consumed. That is:

$$P = dE/dt$$

In continuous time domain, we could also say that:

$$Energy = \int_{0}^{t} P \,dt$$

Practically, we never really get power measurements in the continous time domain. We usually have discrete power measurements over an interval of time. So our Power vs time graph might look something like this:

Figure 1: Power vs time and computing energy consumption

Since we have n discrete Power measurements over time, the energy consumption can be estimated as the area under the curve. This can be modeled as the sum of n-1 trapezoids.

(Energy = \sum_{i=1}^{n-1} A^{i}) where (A^{i}) is the area of the ith trapezoid.

Profiling software for energy consumption refers to the process of measuring the energy consumed by the software being run.

So should you be profiling power or energy ? The answer is – it depends. In some scenarios which involve heavy user interaction (where the user controls the amount of time spent), it makes more sense to measure power.

For example: When a user is watching a video on a laptop or a mobile phone, they control many things such as the duration of the video watched, the screen’s brigthness, speaker volume, and so on.

In other scenarios where the user doesn’t have as much control over the work being performed by the electronic device, it makes sense for energy to be profiled. An example of such a case might be the energy needed to send a message via SMS / IP messaging service (not counting the energy needed to type out the message).

Let's look at some common metrics for profiling energy consumption next.

###Energy Delay Product (EDT)

Used in the research paper What are your programming language's Energy delay implications?, the energy delay product is a weighted metric which is defined as follows:

$$EDT = E * T^{w}$$

where E is the Energy consumption for the task and T is the time taken for the task to be completed.

This metric aims to give us a measure of how much energy an operation takes, while at the same time penalizing the metric for the amount of time taken. That is, an operation consuming the same amount of energy but taking longer to perform by a system, has a higher EDT and is therefore considered less energy efficient.

The weight w can be chosen to be:

• 1: When energy efficiency is of major concern
• 2: When both energy and performance are important
• 3: When performance is more important than energy efficiency

So, you can tailor w to give you an idea of your software system’s energy and performance, based on indicators fit for your use case – whether energy is more important or performance.

Greenup, Powerup, and SpeedUp

In the thesis Using the Greenup, Powerup And Speedup Metrics To Evaluate Software Energy Efficiency, AbdulSalam et al introduced new metrics to measure energy efficiency.

They saw that EDT had one shortcoming: since it was a product of two quantities (Energy and weighted time taken to complete the task at hand), it was possible that two systems which had the same EDT for a task, actually differed when it came to energy efficiency and performance - but their EDT was still the same.

As a result, it was hard to conclude which system was better from an energy + performance point of view, where energy and performance had equal importance.

They introduced 3 metrics to address this issue.

1. Speedup, which is defined as:

$$Speedup = T_{base} / T_{opt}$$

where (T{base}) = Time taken to complete the task for the unoptimized case, (T{opt}) = Time to complete the task for the optimized case.

If the optimized case is more performant than the unoptimized case (since remember, we could be optimizing for only energy, only performance, or both) then Speedup > 1.

2. Greenup, which is defined as:

   $$Greenup = Energy_{base} / Energy_{opt} = P_{base} * T_{base} / P_{opt} * T_{opt}$$

   .

Here (P{base}) is the average power consumed by the task in the unoptimized case and similarly, (P{opt}) is the average power consumed by the task in the unoptimized case.

If we look at different values of Speedup and Powerup, they can fall into the following categories:

1. Zone 1: Powerup < 1 and Speedup < 1 and Speedup > Powerup – in this scenario, the optimized solution sacrificed some performance, but there was a greater power reduction. As a result Greenup > 1, so there are energy savings.
2. Zone 2: Powerup < 1, Speedup > 1 – in this scenario, the optimized solution improved in performance and at the same time, reduced power consumption. As a result, energy consumption decreased and performance improved. This is the best case scenario for any optimization.
3. Zone 3: Powerup > 1, Speedup > 1 and Speedup > Powerup – in this case, average power consumption improved, but the speedup more than made up for the increase in power consumption. As a result, energy consumed still reduced between the optimized and unoptimized solutions.
4. Zone 4: Powerup > 1, Speedup > 1 and Powerup > Speedup – in this case, power consumption decreased, but so did performance. Still, the energy consumption as a whole increased since the loss of performance was greater than the power savings.
5. Zone 5: Powerup > 1, Speedup < 1 – in this case, the energy consumption increased since there was a performance degradation and also there was an increase in power consumption.
6. Zone 6: Powerup < 1, Speedup < 1, Powerup > Speedup – in this case, performance improved, but power increased more than the amount that performance improved. As a result, the energy consumption increased as a whole.

The figure below (inspired by this thesis) shows the zones where energy consumption increases and where it decreases. The red (4, 5 and 6) and the green areas (1, 2 and 3) depict these zones.

Figure 2 : The different zones for Speedup and Powerup

We went over a couple of metrics which both have their strengths and weaknesses. EDT’s strength is that you can give more weightage to performance. But its weakness is that many a time, it may not tell you whether one solution is really better than the other.

While knowing about energy consumption is very important, you should not ignore power consumption. High power consumption, amongst other effects, can have adverse thermal impacts on electronic devices. That is, your device’s skin and component temperature can increase. This may lead to:

1. Component damage: Electronic components such as memory, wires, and capacitors on your device can get damaged as temperature increases.
2. Battery damage: Batteries can get damaged at higher temperatures. Their life may decrease and in some extreme cases they may also explode.

Commercial electronics are usually built to operate within a 0 - 70 degrees Celsius temperature range. But for mobile phones it is usually recommended that the operating temperature not exceed 35 degrees celsius.

Before you profile the energy and power being consumed by a specific task on your devices, it's important to isolate the task as much as possible.

By this, I mean that its important that we take out as many other power consuming tasks or variables. These may be other services / daemons or settings on the device which may affect the power consumed in unreliable ways.

For example, if the device uses the internet, background processes may be doing some activities which may vary between multiple profile runs, so in general it is a good idea to switch off the internet (unless the task being measured uses the internet). We want to do this since we want reproducible power profiling numbers from run to run.

So in general, it is a good idea to make a checklist of the conditions which need to be constant for power profiling to be reliable and reproducible. This could vary from system to system.

##Tools for Profiling

Now, let's talk about how power can be profiled. Different systems may offer different ways of profiling energy consumed.

Depending on the operating system and the underlying hardware, there are a few options. I won’t go into details of these tools since there are many options and there is also good documentation available on their official websites.

###Linux

1. PowerStat is a tool that can measure power consumption on Intel hardware that supports the RAPL (Running average power limit) interface.
2. Cpu-energy-meter is a tool that measures the energy consumed by CPUs in a given time period.
3. Powertop is a tool authored by Intel which gives you information about many things of interest such as power consumption, CPU C / P States, CPU usage, and file system operations per second (and so on).

###macOS

1. Intel power gadget is a tool authored by Intel which gives users the ability to monitor power consumption, CPU frequency, CPU utilization, and even temperature on Intel based Mac machines. Note: According to Intel’s website, Power gadget will not get updates anymore and it recommends using Intel Performance Counter instead.
2. MxPower Gadget is a tool similar to the Intel power gadget, but for Apple silicon-based Macs.
3. Powermetrics is a command line tool that is pre-installed on Apple Silicon and Intel-based machines. It helps you obtain power measurements for CPU and GPU operation.
4. The Activity Monitor App is pre-installed on Macs, and gives you an overview of how your app is performing. It also gives you an overview of various metrics about your Mac. While it doesn’t give you power numbers, it is still a useful tool.

###Android

The AOSP (Android Open Source Project) official documentation provides some guidelines on how to measure system component power here. This process may vary depending on the manufacturer of the device.

Android Studio, Android’s official development IDE also offers a Power Profiler to measure power. The On-Device Power Monitor (ODPM) reports power consumed by all profilable sub-systems through their power rails. Note: These measurements are not specific to any app, as they measure device power on the whole.

###iOS

During iOS app development, developers can measure the energy impact of their app using XCode’s inbuilt Instruments profiler.

We talked about various ways to profile power and energy in this section. In the coming sections, I'll discuss some techniques and considerations to keep in mind to make your software more sustainable.

##Software Techniques and Design Patterns for Sustainability

###Consider which programming language to use

Programming languages have multiple levels of abstraction over the hardware that they are running on. Some have a model of the machine presented to the programmer which is really close to the actual hardware they are running on.

Languages which are directly compiled to machine code are generally more power efficient. They also are generally more performant, since there is less overhead compared to languages which are interpreted or run on a virtual machine, such as Java.

The research paper I mentioned earlier (What are your programming language's Energy delay implications) discusses this in detail and is a great read.

While many popular operating systems have the majority of their APIs in languages like Java, Kotlin, and Swift (which are not native), they usually have performance critical APIs available in native code as well – for example, Android’s C interface-based NDK library. These can interface with their virtual machine-run counterparts and in combination be used to write efficient applications.

###Make software power aware: React to thermal events

In the previous section, I talked about the importance of keeping power consumption low on the devices which run your software. This is not only important to reduce energy consumption, it's also important so that your device’s operating temperature doesn’t go into territory which can damage your device.

The operating temperature of your device doesn’t only depend on the software running on it (which includes your software). It also depends on the ambient temperature.

For example: if a smartphone is used in a car on a hot day, there’s a good chance that when a demanding application is run on it, it’ll thermally stress out the device. So what can you as a software architect do about this?

You cannot control ambient temperature, but you can control how your software responds to thermal events. Many popular operating systems offer APIs to ‘listen’ for thermal events. When apps get notifications that the device’s thermal load has crossed a certain limit, they should take appropriate actions.

For example, if a device is streaming video and it gets a notification about thermally heating up, it may lower the resolution at which it is streaming video in order to reduce power consumption.

If a video conferencing app gets a worrisome thermal event notification, it may want to reduce the frame rate at which it is capturing video / reduce the resolution.

The following are thermal event APIs on popular operating systems

MacOS and iOS: the NSNotificationCenter offers a thermal event listener which userspace applications can register for.

Android: PowerManager offers an onThermalStatusChangedListener which apps can register for, to receive thermal event notification.

###When appropriate, use low power states on hardware

Most modern processors have provisions for reducing power consumption. In these modes, the processor consumes less power by changing the CPU clock speed, putting the CPU into various idle states among various methods. Operating systems give the user the ability to leverage these low power states.

For example, Linux has the cpupower-frequency-set tool which allows users to modify CPU frequency settings.

As another example, Arduino microcontrollers give programmers the ability to put them in various sleep modes when there are no active tasks to be run. These microcontrollers are typically woken up by an interrupt when a task to be processed is ready.

###Investigate the tradeoffs between Interrupt driven-I/O and Polling

Often, software needs to wait on another component of hardware or software for data to process. There are usually two parties involved: the producer of the data and the consumer of the data

For example, a mobile application may be waiting on a touch event on the display. Here the consumer is the mobile application and the producer is the display hardware + software.

Another example could be a native embedded program that is waiting on the status of a CPU register to change in order to perform some task. Here the consumer is the native embedded program and the producer is the CPU register (well, the producer may actually be producing some other data, but for simplicity we’re only considering a CPU register here).

There are broadly 2 ways of doing this:

Polling: The process of checking the status of a data-readiness at regular predetermined intervals of time is referred to as polling. Typically it looks something like this in code:

// psuedo-code
while(poll) {
    bool data_available =  check_data();
    if (data_available) {
        process_data();
    }
    sleep(SLEEP_TIME); // to avoid wasting cpu cycles
}

Polling seems pretty simple to implement. But unless you’re absolutely sure that the data or condition you’re waiting on is going to be available at a regular frequency, it has some disadvantages:

1. Polling doesn’t respond to the data being available as soon as it is available, since it checks for availability after every SLEEP_TIME ms.
2. By constantly checking every time the polling thread wakes up, it still wastes cpu cycles and as a result some power.

Interrupt-driven I/O: in this strategy, there are no explicit checks for the data that is being waited on to be ready. Instead, it is the responsibility of the producer to inform the consumer whenever the data is ready. The consumer does not explicitly check in with the producer, even periodically. As a result, this saves CPU cycles and also power!

There are multiple ways of implementing interrupt-driven I/O. There can be hardware interrupts as well as software interrupts.

For example, when a user touches a mobile phone screen at a particular location, the operating system could send a callback to one of the application’s thread’s notifying it that a touch input event is ready to process. Until the thread gets the notification, it can either do something else, or just stay asleep!

So in short, interrupt-driven I/O is generally more power efficient than polling, and you should prefer it, unless there’s a very good reason to use polling.

Look into Caching

Caching in computer science refers to the process of saving data in a storage location that is typically faster to access than high latency storage (which are generally larger in capacity).

Caching is useful when the same set of data needs to be read or modified repeatedly by software. It allows efficient retrieval and re-use of data.

You can see caching in action in many forms such as:

1. Random Access Memory (RAM) is a cache for underlying disk
2. CPU cache – L(n) – where n is the level of the cache. As n decreases, the cache size usually gets smaller and the latency of data retrieval gets smaller as well.
3. Applications can cache data retrieved from the internet into their on device memory for quick access.
4. Local servers can cache data from remote servers for quicker access as well.

And many more.

Figure 3: Flow of data from disk to CPU via cache hierarchy

As a result of being more efficient with data access, caching usually reduces power consumption and saves energy as well.

Before software can take advantage of caching, it needs to be architected so that that's possible. In general, the following steps can help you:

1. The very first thing is to make sure you're on the lookout for opportunities to cache data.
2. Then, implement caching. How you implement it will depend on the type of software you’re building. It might range from tiling data matrix operations to caching data retrieved from the internet for re-use later on.
3. Monitor profile performance, energy and power usage – and make sure that these metrics are actually improving. It is possible with sub-optimal implementations to cause thrashing of the cache – which may increase power consumption and reduce performance.

###Design software with lifetime and updatability in mind

This article has talked a lot about your software’s energy and power consumption. Finally, there’s something else that is very important as well: the ability for your software to last a long time and be updatable.

It's very beneficial for software to last a long time, since that in turn means that devices will work well for longer. Software being updatable means that older devices get important feature and security updates, which leads to users not necessarily needing to buy newer devices just to get better software. This leads to a reduction in electronic waste and energy being spent on recycling electronic components.

Software updatability is a large topic which I will not cover in detail here. But there are some principles that you shoulder consider which will serve you well while designing for updatability:

Design your software in modules which are updatable by themselves: This may involve having strict interfaces between different modules so that on updating one module the software package as a whole still functions correctly.

Focus on using memory as efficiently as possible: If all software was designed keeping in mind memory efficiency, electronic devices would last longer, since the amount of memory they had would be sufficient for longer.

As an example, consider the iPhone: the first generation in 2007 had 128MB of RAM and 16GB of flash storage (maximum). Today, the iPhone 15 has 6GB of RAM and has a maximum storage option of 1 TB (1024GB). That is a nearly 16x increase in RAM and 64x increase in flash memory. This was needed since the amount of memory needed by applications and the operating system itself grew in size by a huge amount.

As time passes, if memory is used judiciously, we can think of a future where electronic devices last for multiple decades instead of being phased out every 5-6 years.

Testing needs to be bulletproof: When software is going to be updated frequently, there’ll be multiple version of software running on devices which interact with other pieces of software which might be older. These pieces of software must still function correctly.

For this to happen, before deploying updates, software must be tested thoroughly. As an example: when an app developer releases an app, they must test with multiple versions of operating systems to make sure that their app behaves well on all of them.

##Conclusion

This article introduced the concept of engineering software for sustainability and discussed why this is necessary.

You also learned about various metrics as well as some techniques to make your software sustainable and more efficient.

Finally, I hope it inspired you to think about a very serious problem we're facing right now and how we in the tech community can do our part.

I hope you enjoyed the article!

There's always a new frontend framework to learn, or a new database or language that's a variation of another language. It's never ending and feels like you always have to keep up.

But it doesn't have to be this way.

Everything is Built From the Fundamentals

If you learn the fundamentals, then everything else will become easier.

For example, if you learn how the TCP/IP protocol works, then from that you can easily learn all the other protocols that are built on top of it.

You're essentially having to cover less ground. The more fundamentals you know, the less you will struggle learning new things.

I believe there are 10 core subjects which, if you learn them, will give you a solid foundation.

Why Should You Learn These Key Concepts?

Learning the fundamentals will really put you in the top 5% of all programmers.

If we look at it from a different perspective, here's a great quote from Ras Bodik.

Don’t be a boilerplate programmer. Instead, build tools for users and other programmers. Take historical note of textile and steel industries: do you want to build machines and tools, or do you want to operate those machines?

But There are a Million Different Courses to Choose From

Well, look no further.

Below, I've compiled a bunch of helpful resources on each subject – with some alternatives, of course. So you can focus on learning and not on mindlessly researching which books/videos/courses are the best.

A few notes

This article is well-suited for self-taught developers or developers who don't feel quite comfortable with certain computer science concepts.

If you are learning to program for the first time, I would recommend r/learnprogramming community on Reddit.

This article was heavily inspired by Oz Nova and Myles Byrne who authored the site teachyourselfcs.com. If you enjoy this article, feel free to check out and share their site.

Table of Contents

• Programming
• Computer Architecture
• Algorithms and Data Structures
• Math for Computer Science
• Operating Systems
• Computer Networking
• Databases
• Languages and Compilers
• Distributed Systems
• Web Security
• Conclusion

Programming

Source

I'm not talking about syntax here. But actually programming or problem solving. Things such as abstraction, functions as data, recursion, and the different kinds of programming paradigms (object-oriented, functional, and declarative).

The book I recommend to learn programming is Structures and Interpretations of Computer Programs (SICP) (It's also known as the wizard book).

The book is free and has a set of MIT lectures. But the MIT lectures are a bit hard to watch due to the poor quality of that time (2005). So I recommend Brian Harvey’s SICP lectures (for the 61A course at Berkeley) instead.

Why this book?

Because this book focuses on the big picture.

It doesn't care about the programming language. It uses a variation of Lisp called Scheme. Scheme is very easy to learn (you can probably learn it in less than an hour), so it let's you focus on ideas not syntax.

Because of its simplicity, it makes it possible to examine different programming paradigms. It's a functional first approach, but you can implement your own OOP.

Scheme is a great language for teaching because it takes the focus away from the language and puts it on the big ideas.

If you're worried about it not being used in the industry, it's ok – you can always learn a more commonly-used programming languages after you grasp these high-level concepts.

But what if I REALLY don't want to learn Scheme?

Okay, you can follow the new version of the book which uses Python. The book is called Composing Programs. It also has its own set of lectures.

But, I highly recommend at least trying to do the Scheme version. It's just magical once you get it.

Okay, I've tried it but it's really hard

Yes, I understand.

Some of you will find SICP a bit too hard. It's not meant for purely beginner programmers.

If that's the case, then I would recommend How to Design Programs (HTDP). It uses a language very similar to Scheme and is generally more slower paced. You can use this book and its course on edX.

Tips on Studying

Don't read these books like a story.

It's not meant to be read cover to cover. Instead, focus on the exercises. You don't have to do them all, but just make sure you know how to solve most of them.

The lectures are optional and only needed if they help. It's really up to you.

Additional Resources

• Virtual meetups that talk about SICP
• Racket (IDE for Scheme) (Checkout this StackOverFlow answer for Scheme setup)

Computer Architecture

Source

You wrote some code and it magically runs.

How does that work? Well, this is what you will learn with computer architecture. This is by far the most neglected subject by most self taught engineers.

As engineers, we don't believe in magic. We have to unravel the magic behind computers. You will also learn some useful stuff such as:

• What is the L1, L2 cache?
• Why does cyberpunk lag?

The book I recommend here is Computer Systems: A Programmer's Perspective. I would also recommend an introductory course that will cover chapters 1-6 of the book (That was made by the authors of the book).

But there's a catch

This book is not meant to be read cover to cover. It has a lot of content, that may not well be presented in the optimal order.

So I recommend that you follow the course and do the labs.

What if I find it too hard?

A lot of people will find the content a bit heavy, so to ease into it, I would recommend doing the following:

• Read Code: The Hidden Language of Computer Hardware and Software\
• Read this handbook on Software Architecture
• Watch all 4 videos of Exploring How Computers Work
• Watch all 41 videos of Crash Course: Computer Science
• Take the course NAnd2Tetris
• Learn a bit of C by reading the book: C Programming a Modern Approach

Once you finish that you can then come back to Computer Systems: A Programmers Perspective.

Data Structures and Algorithms

Source

Everyone wants to work at a FAANG company, but no one wants to learn Data Structures and Algorithms.

Nevertheless, I don't want you to learn these just because of technical interviews. Data structures and algorithms are important because they help build your problem solving skills.

There are many great books and courses on Data Structures and Algorithms but the one I would recommend is a book named The Algorithm Design Manual by Steven Skiena. You can also check out his course here.

Don't forget to practice

Same rules apply here. Don't just learn about data structures, but create them in whatever language you want. Don't just memorize algorithms but implement them and see where and how you can use them.

A good tip is solving some Leetcode problems while going through the book/course.

What if I find it too hard?

If you find the material a bit heavy, then I would recommend the following resources:

• Read the book: Grokking Algorithms
• Read the book: How to Solve It: A New Aspect of Mathematical Method

In general there are many different books/courses that teach Data Structures and Algorithms – Here are some other great resources:

• Data Structures and Algorithms course on freeCodeCamp
• Algorithms Illuminated
• Princeton Algorithms Course
• ThePrimegeans Data Structures and Algorithms Course
• MIT Introduction to Algorithms

Math for Computer Science

Don't worry, this is some random math photo found here

Many new developers skip this.

But, hear me out – computer science is essentially a branch of mathematics. Learning it will make you a better developer by honing your problem solving skills.

The most relevant area for CS is Discrete Mathematics

Discrete mathematics is the branch of mathematics that deals with countable or finite numbers.

The topics in discrete mathematics are many, but the ones which are relevant for CS are:

• Logic
• Combinatorics
• Discrete Probability
• Set Theory
• Graph Theory
• Number Theory

How to Study Discrete Mathematics

I would suggest starting with a set of lecture notes by László Lovász.

Professor Lovász notes are easier to digest than formal texts and are just generally fun. He starts of with a problem and solves it using discrete mathematics.

After that, you can take an MIT book called Mathematics for Computer Science. The book comes with video lectures that are freely available.

What if it's too hard?

Don't worry – sometimes you just have to accept that you won't always get it right away.

It's fine.

But if you feel like you're missing some fundamental knowledge, then it's a different story. The fundamental prerequisite subjects for discrete mathematics are:

• Algebra
• Geometry
• Calculas

There are many free resources, but the ones I would recommend are:

• Khan Academy
• College Algebra course
• Calculus 1 course
• Calculus 2 course

Operating Systems

Source

Remember when I told you that we as developers want to remove the magic in computing?

Same thing applies here – operating systems seem like some sort of magical black box. But they're not – it's just a lot of clever engineering.

If you know how these operating systems are built and work, then you will definitely be in a league of your own.

It's somewhat difficult to find good resources online for operating systems but the most recommend book is Operating Systems: Three Easy Pieces (OSTEP). There isn't any official video lecture online that fully covers the book but I found this playlist on YouTube.

Recommend Prerequisites

I would suggest learning computer architecture first and a little bit about C before embarking on the operating systems journey.

Optional Resources

Now, I recommend finishing OSTEP first and then checking out the other recommend resources. They are all optional.

• Want to build your own Linux system? Check out Linux from Scratch.
• Want an in-depth overview of Linux, MacOS, and Windows? Here's a handbook for you.
• Want to build your own OS? Check out OSDEV
• Want to build your own Sockets? Check out Beej's Guide to Network Programming

Computer Networking

Source

Since the dawn of the internet, computer networking has been one the most important subjects for software engineers.

If you don't know things like IP, TCP, UDP, HTTP, TLS, DNS, SMTP, and so on — then you should learn about computer networking (especially if you are a backend engineer).

The recommended book here is Computer Networking: A Top-Down Approach. You can also check out the video lectures from the author of the book himself.

But before beginning that I would recommend to check out this video crash course on computer networking from a bottom up approach. And here's a helpful tutorial that covers the basics well.

Databases

Source

Databases are somewhat new – they came around the 1970s and have since become integral parts of many applications.

I highly recommend the below courses from the CMU Database Group. They're all freely available on YouTube. I would recommend going through at least the first one.

1. Introduction To Databases
2. Database Seminars
3. Advanced Databases

Also, here's a great collection of resources to help you learn about SQL databases. And here's a free course on NoSQL databases.

Languages and Compilers

Source

You may know how to code in one or more programming languages.

But do you know how to create or design one? That's what you will learn by studying programming languages and compilers.

The recommended introductory book is called Crafting Interpreters.

After that you can move on to Compilers: Principles, Techniques & Tools, also called “the Dragon Book”. The book is covers a lot of topics so I highly recommend taking a course with it. The one I recommend is from Alex Aiken on edX.

And here's a helpful beginner-friendly tutorial on how the compiler works in C programming.

Distributed Systems

Source

If you choose to study only one subject from the list, make it distributed systems. It's the holy grail for tech companies, and if you want to get a developer job, you should be proficient about distributed systems.

My recommend path in learning the subject is:

1. Read the book: Understanding Distributed Systems
2. Read the book: Designing Data Intensive Applications also known as the "red book"
3. While reading the "red book", take its accompanying MIT course on YouTube.
4. Read the book: Software Architecture: The Hard Parts (Optional)
5. You can also check out my handbook about design patterns for distributed systems.

Web Security

Source

There have been a lot of security breaches in the last 2-3 years.

It's getting dangerous out there – and as a software engineer, knowing some fundamentals of web security will give you an edge.

The course I recommend first is CS253 Web Security by Stanford. It gives a comprehensive overview of web security. So expect topics like web app vulnerabilities, injection, denial-of-service, and many more.

You can also review these common vulnerabilities and learn how to prevent attacks that take advantage of them.

Later on, if you want, you could learn how to hack using pwn.college.

Conclusion

Learning all these subjects will take you a while, and will require consistent effort. But if you like what you do and are interested in the subject, then it should feel like play and not a chore.

Regardless of the subjects you choose to study. The most important tip I can give you is...

Don't be a passive learner

Don't just watch videos – do the exercises as well. Build the projects along with the tutorials.

Don't just read books but engage in the book by asking questions and doing your own research.

You want the information to stick, so you don't forget it. And to make it stick you have to actively engage in the subject.

I sincerely hope that I encouraged you to study some of these subjects. As always I want to end it of by thanking you for reading this article.

I wish you all the best.