How Passkeys Work at the Cryptographic Level

When you register a passkey with a service (the relying party), your device generates a key pair, a public key and a private key. The public key is shared with the server, while the private key is securely stored in your device’s enclave or secure element (for example, the Trusted Platform Module or Secure Enclave).

When you later authenticate, the server sends a challenge, a random piece of data, to your device. Your device signs this challenge using the private key, producing a digital signature. The server then uses the public key it stored earlier to verify the signature. If the verification passes, the server knows two things:

- The signature could only have been created by the matching private key.

- The challenge is fresh, meaning the authentication attempt is not a replay of a previous one.

This process provides proof of possession of the private key, without ever transmitting it over the network.

At a high level, the math works like this:

- The device generates a signature using the private key.

- The server verifies the signature with the public key.

- If verification passes, the server knows the user is authentic.

Subscribe now

The Math Behind the Verification

WebAuthn supports multiple cryptographic algorithms, with ECDSA (Elliptic Curve Digital Signature Algorithm) and EdDSA (Ed25519) being the most common. RSA-based algorithms like RSASSA-PKCS1-v1_5 and RSASSA-PSS are also supported for compatibility.

The principle behind all these algorithms is that the public key is mathematically linked to the private key, allowing verification without ever exposing the private key. The algorithms differ in curves, key sizes, and signing methods, but all implement challenge-response authentication.

ECDSA Example: A Step-by-Step Walkthrough

Let’s be honest: the math behind ECDSA is not easy to follow. Even with a clear explanation, keeping track of all the variables (d, k, r, s, Q, R, G, H...) and understanding how they relate to each other can feel overwhelming. You’re dealing with elliptic curve operations, modular arithmetic, and multiple interdependent steps, all happening simultaneously.

That’s why I’ve created an interactive visual guide that walks you through each step with animations and highlights. Instead of just reading about the process, you can see it unfold:

🎯 Launch Interactive Visual Guide

The guide breaks down the entire process into digestible steps, showing you exactly when each variable is created, how they combine, and where they end up. I highly recommend opening it in a new tab and following along as you read the explanation below.

Now, let’s walk through ECDSA from setup to verification.

Initial Setup: Creating the Key Pair

When you first register a passkey, your device creates a key pair on an elliptic curve. Think of an elliptic curve as a mathematical space where certain operations are easy in one direction but nearly impossible to reverse.

The setup starts with a fixed point called the generator `G`, which is a standard point that everyone using this curve agrees upon. Your device then:

1. Generates a private key `d`, which is simply a large random number. This is your secret, stored securely in your device’s enclave, and never shared with anyone.

2. Computes the public key `Q` using the formula `Q = d * G`. This operation means “multiply the generator point `G` by the scalar `d`” in elliptic curve arithmetic.

Here’s the crucial property: computing `Q` from `d` and `G` is easy, but computing `d` from `Q` and `G` is computationally infeasible. This one-way property is what makes the cryptography secure. Your device sends `Q` to the server during registration, but `d` stays locked away forever.

Authentication: Creating a Signature

Now, when you return to authenticate, the server sends you a challenge `H` (typically a hash of random data plus contextual information). Your device needs to prove it still possesses the private key `d` without revealing it. Here’s how the signature is created:

1. Generate a fresh nonce `k`: For each signature, your device creates a new random number called `k`. This nonce is temporary and unique to this specific authentication attempt. Using a new `k` every time ensures that even signing the same challenge twice produces different signatures, preventing replay attacks.

2. Create a curve point `R`: Using the same generator `G` from setup, compute `R = k * G`. This point `R` has two coordinates, an x-coordinate and a y-coordinate.

3. Extract `r`: Take the x-coordinate of point `R` and call it `r`. This becomes the first part of your signature.

4. Compute `s`: Now comes the part that actually involves your private key. Calculate `s = k^(-1) * (H + r*d) mod n`, where:

- `k^(-1)` is the modular inverse of your nonce `k`

- `H` is the hash of the challenge from the server

- `r` is the x-coordinate we just extracted

- `d` is your private key

- `n` is the order of the elliptic curve (a fixed parameter)

5. Send the signature: Your device sends the pair `(r, s)` back to the server. Notice that neither `d` (your private key) nor `k` (your temporary nonce) are included, only the values `r` and `s` derived from them.

Verification: The Server’s Role

The server now has:

- The challenge `H` it originally sent

- Your signature `(r, s)`

- Your public key `Q` from registration

Using elliptic curve mathematics, the server can verify that this signature could only have been created by someone who knows the private key `d` corresponding to public key `Q`. The verification algorithm checks the mathematical relationship between all these values. If the relationship holds, the server has proof that you possess the private key without you ever transmitting it.

The beauty of this system is in its asymmetry: creating the signature requires the private key `d`, but verifying it only requires the public key `Q`. The server can be confident of your identity without ever knowing your secret.

If you found this explanation dense (and honestly, who wouldn’t?), go back to the interactive visual guide. Click through each step and watch how the variables flow from one operation to the next. It makes the whole process much clearer than words alone can convey.

Other Algorithms

- EdDSA (Ed25519): A faster, modern elliptic curve algorithm with deterministic signatures (no random `k` needed, which eliminates certain implementation risks).

- RSASSA-PKCS1-v1_5 and RSASSA-PSS: RSA-based algorithms that use different mathematical operations (prime factorization instead of elliptic curves) but follow the same principle of public key verification.

All these algorithms implement the same core concept: only the private key holder can produce a signature that the public key can verify, ensuring authenticity without exposing secrets.

Why the Challenge Matters

The challenge prevents replay attacks. Each authentication request generates a new random challenge, so an old signature is useless. Including contextual data, like the domain name, prevents phishing or cross-origin attacks, ensuring the signature is valid only for the legitimate site.

Security Properties

The cryptographic mechanism provides three main guarantees:

- Authenticity – Only the legitimate private key holder can produce a valid signature.

- Integrity – Any modification to the challenge or signed data invalidates the signature.

- Non-repudiation – Once the challenge is signed, the signer cannot plausibly deny having authenticated (depending on implementation).

These properties make passkeys robust against phishing, credential stuffing, and password leaks. The private key never leaves your device, and even the server breach won’t compromise your credentials.

Subscribe now

If you enjoyed this deeper dive and want to keep exploring the technical side of authentication, subscribe to the newsletter or follow me on X for future updates.

If you find this content useful, feel free to support me with a coffee

More articles I enjoyed this week

• Linear Regression (New Free Series) by AI by Hand ✍️

• Chain Replication by The Polymathic Engineer

What Is a Passkey

A passkey is a cryptographic key pair that replaces a password. The private key stays securely on your device, while the public key is stored by the service you register with. When you log in, the service sends a random challenge that your device signs using the private key.

Subscribe now

The signature is verified using the public key, and access is granted only if the signature is valid. The private key never leaves your device and cannot be shared across sites. This removes the two classic risks of credential theft and phishing.

Passkeys are part of the FIDO2 and WebAuthn standards, and are supported across all major ecosystems including Apple, Google, and Microsoft.

The WebAuthn Foundation

At the core of passkeys is WebAuthn, the Web Authentication API. It defines how browsers, authenticators, and servers communicate to register and use credentials.

A WebAuthn flow consists of two main parts:

Registration

• The authenticator (your phone, laptop, or hardware key) generates a new key pair.

• The public key is returned to the service and stored.

• The private key remains secured on the authenticator.

Authentication

• The service sends a unique challenge to the client.

• The authenticator signs the challenge with the private key.

• The server verifies the signature using the stored public key.

Each credential is scoped to a specific origin, meaning that a key created for example.com cannot be used on fake-example.com. This property makes phishing nearly impossible.

WebAuthn supports two types of authenticators:

Platform authenticators, built into a device (like Touch ID or Windows Hello).

Roaming authenticators, external devices like YubiKeys that can be used across machines.

The browser acts as the interface between your application and these authenticators. In JavaScript, the process is straightforward:

// Registration
const credential = await navigator.credentials.create({
  publicKey: publicKeyCreationOptions
});


// Authentication
const assertion = await navigator.credentials.get({
  publicKey: publicKeyRequestOptions
});

The browser and operating system handle the cryptography and user verification. Your backend only needs to store public keys and verify signatures, which can be done through existing libraries for Java, Node.js, Go, and others.

Implementation in Practice

To integrate passkeys in your app:

• Use WebAuthn on the client side for registration and authentication.

• Generate and store challenges securely server-side.

• Validate signatures using a WebAuthn or FIDO2 library.

• Update your login flow to support both passwords and passkeys during the transition.

Mobile and desktop platforms provide equivalent APIs through AuthenticationServices (iOS) and Credential Manager (Android).

Why It Matters

• Phishing resistance: Credentials are domain-bound and cannot be replayed.

• No password reuse: Each service has its own key pair.

• Hardware-backed security: Private keys live inside secure enclaves or TPMs.

• Faster user experience: Logins are completed with biometrics or device unlock.

Integration with Password Managers

Modern password managers such as 1Password, Bitwarden, iCloud Keychain, and Google Password Manager now support passkeys. They act as roaming authenticators, synchronizing passkeys across devices while keeping private keys encrypted.

This approach combines strong cryptography with usability. Users can log in from new devices without manually exporting keys, while developers avoid dealing with device-specific storage concerns.

Subscribe now

Passkeys are not an experimental idea. They are live across browsers and platforms today. For developers, supporting them is mostly a matter of implementing WebAuthn and preparing authentication flows that work without passwords.

We have spent decades patching around passwords with multi-factor authentication, password complexity rules, and breach monitoring. Passkeys move the conversation forward by removing the weakest component altogether. They are not just a security upgrade — they are the logical endpoint of password evolution.

Articles I enjoyed this week

• Engineering Leader’s Guide: How to Become a Great Coach and Mentor by Engineering Leadership

• 4 Resources You Should Read to Get Better at Agentic Coding by The Growing Engineer

If you want to explore the underbelly of IT and follow the journey of a senior engineer and architect, subscribe to this newsletter and follow me on X.

If you find this content useful, feel free to support me with a coffee

MCP is the hottest thing this year in the AI sphere. I keep seeing badly written articles so I decided to try to put together some meaningful informations.

I did what every sensible person would at this point and I started asking question to Claude. From the questions I created this article to try bringing some clarity into the matter.

Model Context Protocol (MCP) is an open standard protocol introduced by Anthropic in November 2024 that standardizes how AI assistants communicate with external tools and data sources. Think of it as a universal adapter, like USB-C for hardware, that allows any AI application to connect with any tool or data source without custom integration code.

Before MCP, connecting an AI to 10 different tools (GitHub, Slack, databases, APIs) meant writing 10 different integrations. And if you wanted 5 different AI applications to use those same 10 tools, you’d need 50 separate integrations. MCP solves this N×M problem by providing one standardized way for AIs to talk to tools.

What Problem Does MCP Solve?

The AI integration landscape before MCP looked like this:

The Fragmentation Problem:

• Every AI application needed custom code to integrate with each tool

• Developers wrote the same integration logic repeatedly for different AI platforms

• Tools had to provide separate SDKs and APIs for each AI application

• No standard way to describe what a tool could do or how to use it

• Switching tools or AI providers meant rewriting everything

Real World Impact:

• A company using Claude, ChatGPT, and a custom AI agent would need three separate integrations for each tool (like GitHub, Slack, or their database)

• Adding a new data source required updating every AI application individually

• Tool developers couldn’t build once and support all AI platforms

• Security, permissions, and error handling were inconsistent across integrations

MCP eliminates this by creating a single protocol that both AI applications and tools can implement once and use everywhere.

How MCP Solves the Problem

Think of the system like a puppet master controlling multiple puppets. Here’s how the strings connect:

The Puppets (Third-Party Tools):

• Each puppet is a tool like GitHub, Slack, PostgreSQL, or Google Drive

• The puppet needs attachment points where strings can connect

• These attachment points are the MCP Server implementation

The Puppet Master (AI + MCP):

• The puppet master is the combination of the AI model and its MCP Client

• The strings are the JSON-RPC messages flowing over a transport layer

• The puppet master needs to know what strings connect to which parts of each puppet

The Strings (The Protocol): This is where we get into the HOW. The strings aren’t magical, they’re made of three distinct layers:

1. Transport Layer (The Physical String)

   • How the messages physically travel

   • Local puppets: STDIO (standard input/output streams)

   • Remote puppets: HTTP with Server-Sent Events (SSE)

2. Message Format Layer (What’s Written on the String)

   • All messages use JSON-RPC 2.0 format

   • Provides structure for requests, responses, and notifications

   • Ensures every message can be understood by both sides

3. Protocol Layer (The Commands on the String)

   • Defines specific MCP methods like tools/list, tools/call, resources/read

   • Describes capabilities, permissions, and data formats

   • Handles initialization, discovery, and execution

Subscribe now

The Technical Deep Dive: How the Strings Actually Work

Now let’s explain exactly how the puppet master pulls the strings.

Phase 1: Attaching the Strings (Initialization)

When you want to use an MCP server, the AI application (MCP Client) first needs to establish a connection. Here’s the exact sequence:

Step 1: Transport Connection

For a local tool using STDIO:

AI Application spawns the MCP server as a child process
Server process: node github_mcp_server.js
Communication channels: stdin/stdout pipes connect AI ↔ Server

For a remote tool using HTTP:

AI Application connects to: https://api.example.com/mcp
Opens persistent connection for Server-Sent Events
Communication channels: HTTP POST for requests, SSE stream for responses

Step 2: The Handshake (Initialize Request)

The AI sends the first message over the connected transport:

{
  “jsonrpc”: “2.0”,
  “id”: 1,
  “method”: “initialize”,
  “params”: {
    “protocolVersion”: “2024-11-05”,
    “capabilities”: {
      “roots”: { “listChanged”: true },
      “sampling”: {}
    },
    “clientInfo”: {
      “name”: “Claude Desktop”,
      “version”: “1.0.0”
    }
  }
}

This message says: “Hello, I’m Claude Desktop version 1.0.0, I speak MCP protocol version 2024-11-05, and here’s what I can do (my capabilities).”

Step 3: The Response (Initialize Response)

The MCP Server responds:

{
  “jsonrpc”: “2.0”,
  “id”: 1,
  “result”: {
    “protocolVersion”: “2024-11-05”,
    “capabilities”: {
      “tools”: {},
      “resources”: {},
      “prompts”: {}
    },
    “serverInfo”: {
      “name”: “GitHub MCP Server”,
      “version”: “1.2.0”
    }
  }
}

This says: “Hello, I’m the GitHub MCP Server version 1.2.0, I also speak protocol version 2024-11-05, and I can provide tools, resources, and prompts.”

Step 4: Initialization Complete

The AI sends a notification (no response needed):

{
  “jsonrpc”: “2.0”,
  “method”: “notifications/initialized”
}

The strings are now attached. The connection is live.

Phase 2: Discovering the Puppet’s Joints (Capability Discovery)

This is one of the most powerful aspects of MCP. Instead of hardcoding what each tool can do, the AI dynamically discovers capabilities at runtime. This means new tools can be added without changing the AI’s code, and tools can update their capabilities without breaking existing integrations.

Now the puppet master needs to learn what this puppet can do. This is where the magic starts to become clear.

Step 1: Asking “What Tools Do You Have?”

The AI sends:

{
  “jsonrpc”: “2.0”,
  “id”: 2,
  “method”: “tools/list”
}

Step 2: The Server Lists Its Tools

The GitHub MCP Server responds:

{
  “jsonrpc”: “2.0”,
  “id”: 2,
  “result”: {
    “tools”: [
      {
        “name”: “create_issue”,
        “description”: “Creates a new GitHub issue in a repository”,
        “inputSchema”: {
          “type”: “object”,
          “properties”: {
            “repository”: {
              “type”: “string”,
              “description”: “Repository name in format ‘owner/repo’”
            },
            “title”: {
              “type”: “string”,
              “description”: “Issue title”
            },
            “body”: {
              “type”: “string”,
              “description”: “Issue description”
            }
          },
          “required”: [”repository”, “title”]
        }
      },
      {
        “name”: “list_issues”,
        “description”: “Lists issues from a GitHub repository”,
        “inputSchema”: {
          “type”: “object”,
          “properties”: {
            “repository”: {”type”: “string”},
            “state”: {
              “type”: “string”,
              “enum”: [”open”, “closed”, “all”]
            }
          },
          “required”: [”repository”]
        }
      }
    ]
  }
}

This response tells the AI: “I have two tools. The first one is called create_issue and it needs a repository name and title (and optionally a body). The second one is list_issues and it needs a repository and optional state.”

The AI now knows exactly what strings it can pull and what information each string pull requires.

Step 3: Discovering Resources

Similarly, the AI can ask about available data:

{
  “jsonrpc”: “2.0”,
  “id”: 3,
  “method”: “resources/list”
}

Response:

{
  “jsonrpc”: “2.0”,
  “id”: 3,
  “result”: {
    “resources”: [
      {
        “uri”: “github://repo/user/myproject”,
        “name”: “My Project Repository”,
        “description”: “Main project repository information”,
        “mimeType”: “application/json”
      }
    ]
  }
}

Phase 3: Pulling the Strings (Executing Actions)

This is where the puppet master actually makes the puppet move. Let’s trace a complete action from user request to execution.

User Says: “Create a GitHub issue titled ‘Fix login bug’ in the auth-service repository”

Step 1: AI Decides to Use a Tool

The AI model (Claude) processes the request and determines it needs to use the create_issue tool. It constructs the appropriate parameters and sends:

{
  “jsonrpc”: “2.0”,
  “id”: 4,
  “method”: “tools/call”,
  “params”: {
    “name”: “create_issue”,
    “arguments”: {
      “repository”: “mycompany/auth-service”,
      “title”: “Fix login bug”,
      “body”: “Users are experiencing login failures. Need to investigate authentication flow.”
    }
  }
}

This message travels over the transport (STDIO or HTTP) as a JSON string.

Step 2: MCP Server Receives and Routes

The GitHub MCP Server:

1. Receives the JSON-RPC message on its transport layer

2. Parses the JSON and validates the structure

3. Checks that the requested tool (create_issue) exists

4. Validates the arguments against the tool’s input schema

5. Routes to the actual tool implementation code

Step 3: MCP Server Translates to Third-Party API

Here’s the crucial part that’s often glossed over. The MCP Server now translates this standardized MCP request into the specific API call the third-party service expects:

// Inside the GitHub MCP Server implementation
async function handleCreateIssue(args) {
  // Translate MCP request to GitHub API format
  const githubApiRequest = {
    title: args.title,
    body: args.body,
    labels: []
  };
  
  // Make actual HTTP call to GitHub’s REST API
  const response = await fetch(
    `https://api.github.com/repos/${args.repository}/issues`,
    {
      method: ‘POST’,
      headers: {
        ‘Authorization’: `Bearer ${process.env.GITHUB_TOKEN}`,
        ‘Content-Type’: ‘application/json’,
        ‘Accept’: ‘application/vnd.github.v3+json’
      },
      body: JSON.stringify(githubApiRequest)
    }
  );
  
  const issue = await response.json();
  
  // Translate GitHub response back to MCP format
  return {
    issueNumber: issue.number,
    url: issue.html_url,
    state: issue.state
  };
}

This is THE critical translation layer. The MCP Server is a wrapper that:

• Takes standardized MCP requests

• Translates them to service-specific API calls

• Handles authentication (using stored tokens/credentials)

• Makes the actual API call to GitHub

• Translates the response back to MCP format

Step 4: MCP Server Responds

After GitHub’s API returns success, the MCP Server sends back:

{
  “jsonrpc”: “2.0”,
  “id”: 4,
  “result”: {
    “content”: [
      {
        “type”: “text”,
        “text”: “Successfully created issue #127 in mycompany/auth-service”
      }
    ],
    “isError”: false
  }
}

Step 5: AI Incorporates Result

The AI receives this response and uses it to formulate the final answer to the user:

“I’ve created issue #127 in the auth-service repository with the title ‘Fix login bug’. You can view it at: https://github.com/mycompany/auth-service/issues/127”

The Complete Data Flow Diagram

User Request
    ↓
[AI Model - Claude]
    ↓ (decides which tool to call)
[MCP Client in Host App]
    ↓ (formats JSON-RPC message)
[Transport Layer - STDIO or HTTP]
    ↓ (sends JSON string)
[MCP Server - GitHub Wrapper]
    ↓ (receives & parses JSON-RPC)
    ↓ (validates request)
    ↓ (translates to GitHub API format)
[GitHub REST API]
    ↓ (processes request)
    ↓ (returns GitHub response)
[MCP Server]
    ↓ (translates response to MCP format)
    ↓ (formats JSON-RPC response)
[Transport Layer]
    ↓ (sends JSON string back)
[MCP Client]
    ↓ (parses response)
[AI Model]
    ↓ (incorporates result into context)
User Response

Subscribe now

A Complete Working Example: Weather Tool with Claude

Let’s build a simple but complete MCP server and show exactly how Claude interfaces with it.

Building the MCP Server

1. Server Implementation (weather_server.js)

import { Server } from “@modelcontextprotocol/sdk/server/index.js”;
import { StdioServerTransport } from “@modelcontextprotocol/sdk/server/stdio.js”;

// Create the MCP server instance
const server = new Server(
  {
    name: “weather-server”,
    version: “1.0.0”,
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Define the weather tool
server.setRequestHandler(”tools/list”, async () => {
  return {
    tools: [
      {
        name: “get_weather”,
        description: “Gets current weather for a city”,
        inputSchema: {
          type: “object”,
          properties: {
            city: {
              type: “string”,
              description: “City name”,
            },
            units: {
              type: “string”,
              enum: [”celsius”, “fahrenheit”],
              description: “Temperature units”,
            },
          },
          required: [”city”],
        },
      },
    ],
  };
});

// Handle tool execution
server.setRequestHandler(”tools/call”, async (request) => {
  if (request.params.name === “get_weather”) {
    const { city, units = “celsius” } = request.params.arguments;
    
    // Simulate weather API call
    // In real implementation, this would call OpenWeatherMap, etc.
    const weatherData = await fetchWeatherFromAPI(city);
    
    const temp = units === “celsius” 
      ? weatherData.temp_c 
      : weatherData.temp_f;
    
    return {
      content: [
        {
          type: “text”,
          text: `Weather in ${city}: ${temp}°${units === “celsius” ? “C” : “F”}, ${weatherData.condition}`,
        },
      ],
    };
  }
  
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// Simulated API call
async function fetchWeatherFromAPI(city) {
  // In real implementation, this makes HTTP request to weather service
  // For demo, we return mock data
  return {
    temp_c: 22,
    temp_f: 72,
    condition: “Partly cloudy”,
  };
}

// Start the server with STDIO transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error(”Weather MCP server running on stdio”);
}

main().catch(console.error);

2. Connecting to Claude Desktop

Edit Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  “mcpServers”: {
    “weather”: {
      “command”: “node”,
      “args”: [”/path/to/weather_server.js”]
    }
  }
}

How Claude Interfaces with the MCP Server

Step-by-Step Execution:

1. Claude Desktop Startup

When Claude Desktop launches:

// Inside Claude Desktop’s MCP Client code
const weatherClient = new MCPClient();
const transport = new StdioClientTransport({
  command: “node”,
  args: [”/path/to/weather_server.js”]
});

// Spawns: node /path/to/weather_server.js
// Creates stdin/stdout pipes for communication
await weatherClient.connect(transport);

2. Initialization Handshake

Claude sends over stdin:

{”jsonrpc”:”2.0”,”id”:1,”method”:”initialize”,”params”:{”protocolVersion”:”2024-11-05”,”capabilities”:{},”clientInfo”:{”name”:”Claude Desktop”,”version”:”1.0.0”}}}

Server responds over stdout:

{”jsonrpc”:”2.0”,”id”:1,”result”:{”protocolVersion”:”2024-11-05”,”capabilities”:{”tools”:{}},”serverInfo”:{”name”:”weather-server”,”version”:”1.0.0”}}}

3. Tool Discovery

Claude sends:

{”jsonrpc”:”2.0”,”id”:2,”method”:”tools/list”}

Server responds:

{”jsonrpc”:”2.0”,”id”:2,”result”:{”tools”:[{”name”:”get_weather”,”description”:”Gets current weather for a city”,”inputSchema”:{”type”:”object”,”properties”:{”city”:{”type”:”string”,”description”:”City name”},”units”:{”type”:”string”,”enum”:[”celsius”,”fahrenheit”],”description”:”Temperature units”}},”required”:[”city”]}}]}}

Claude now knows: “I have access to a tool called get_weather that needs a city and optional units.”

4. User Interaction

User types: “What’s the weather in Paris?”

Claude’s internal processing:

1. Analyzes the user query

2. Recognizes this requires weather information

3. Checks available tools

4. Finds get_weather tool matches the need

5. Extracts parameters: city = “Paris”

6. Decides to call the tool

5. Tool Execution

Claude sends over stdin:

{”jsonrpc”:”2.0”,”id”:3,”method”:”tools/call”,”params”:{”name”:”get_weather”,”arguments”:{”city”:”Paris”,”units”:”celsius”}}}

This JSON string travels through the stdin pipe to the server process.

6. Server Processing

The weather_server.js:

1. Receives the JSON string from stdin

2. Parses it: JSON.parse(message)

3. Recognizes method: “tools/call”

4. Routes to the tools/call handler

5. Extracts tool name: get_weather

6. Validates arguments against schema

7. Executes the tool function

8. Calls fetchWeatherFromAPI(”Paris”)

9. Formats the response

7. Server Response

Server sends over stdout:

{”jsonrpc”:”2.0”,”id”:3,”result”:{”content”:[{”type”:”text”,”text”:”Weather in Paris: 22°C, Partly cloudy”}]}}

8. Claude’s Final Response

Claude receives the response, incorporates it into its context, and responds to the user:

“The weather in Paris is currently 22°C and partly cloudy.”

How MCP Communicates with Third-Party Services

The critical piece that makes MCP work is that the MCP Server acts as a translation layer. Here’s the exact flow:

Claude (MCP Client)
    ↓
Sends standardized MCP request:
{method: “tools/call”, params: {name: “get_weather”, arguments: {city: “Paris”}}}
    ↓
MCP Server receives this
    ↓
MCP Server translates to third-party API format:
fetch(’https://api.openweathermap.org/data/2.5/weather?q=Paris&appid=KEY’)
    ↓
Third-party API (OpenWeatherMap) returns:
{temp: 295.15, weather: [{description: “partly cloudy”}]}
    ↓
MCP Server translates response back to MCP format:
{content: [{type: “text”, text: “Weather in Paris: 22°C, Partly cloudy”}]}
    ↓
Claude receives standardized MCP response

The Power of This Design:

1. Claude never needs to know about OpenWeatherMap’s API

   • Doesn’t need their API key format

   • Doesn’t need to know their endpoints

   • Doesn’t need to parse their response format

2. The MCP Server handles all service-specific details

   • Stores the API key securely

   • Knows the exact endpoint URLs

   • Handles authentication headers

   • Translates data formats both ways

   • Manages rate limiting

   • Handles errors gracefully

3. Switching weather providers is easy

   • Update only the MCP Server code

   • Claude’s interface stays identical

   • Change from OpenWeatherMap to WeatherAPI

   • Claude still calls get_weather the same way

The Transport Layer: How the Strings Actually Connect

STDIO (Local Integrations)

For tools running on the same machine as the AI:

How it works:

// Claude spawns a child process
const serverProcess = spawn(’node’, [’weather_server.js’]);

// Sets up communication pipes
serverProcess.stdin.write(jsonRpcRequest);  // Send request
serverProcess.stdout.on(’data’, (data) => {  // Receive response
  const response = JSON.parse(data);
  handleResponse(response);
});

Why STDIO?

• Simple: uses standard input/output streams

• Fast: no network overhead

• Secure: no network exposure

• Works perfectly for local tools

Data Flow:

[Claude Process]                [Weather Server Process]
     stdin ←→ stdout                  stdin ←→ stdout
        ↓                                  ↑
    Writes JSON to server’s stdin          |
        ↓                                  |
    Server reads from its stdin            |
        ↓                                  |
    Server processes request               |
        ↓                                  |
    Server writes JSON to its stdout -------
        ↓
    Claude reads from server’s stdout

HTTP with Server-Sent Events (Remote Integrations)

For tools running on remote servers:

How it works:

Request Phase (HTTP POST):

// Claude makes HTTP POST request
const response = await fetch(’https://api.example.com/mcp’, {
  method: ‘POST’,
  headers: {
    ‘Content-Type’: ‘application/json’,
    ‘Mcp-Session-Id’: sessionId
  },
  body: JSON.stringify({
    jsonrpc: “2.0”,
    id: 3,
    method: “tools/call”,
    params: {name: “get_weather”, arguments: {city: “Paris”}}
  })
});

Response Phase (Server-Sent Events):

// Server can stream responses back
res.setHeader(’Content-Type’, ‘text/event-stream’);
res.write(’data: {”jsonrpc”:”2.0”,”id”:3,”result”:{...}}\n\n’);

Why HTTP + SSE?

• Works across networks

• SSE allows server-initiated messages

• Handles long-running operations

• Supports progress updates

• Can maintain session state

Data Flow:

[Claude - Browser/Desktop]          [MCP Server - Cloud]
         ↓
    HTTP POST request to /mcp
    (contains JSON-RPC message)
         ↓
    [Server receives, processes]
         ↓
    HTTP Response or SSE stream
    (contains JSON-RPC response)
         ↓
    Claude processes response

Session Management

For stateful interactions:

First Request:
Claude → Server: {”jsonrpc”:”2.0”,”id”:1,”method”:”initialize”,...}
Server → Claude: HTTP 200, Header: “Mcp-Session-Id: abc123”

Subsequent Requests:
Claude → Server: Header: “Mcp-Session-Id: abc123”, {”jsonrpc”:”2.0”,...}
Server: Recognizes session, maintains context

Security and Authentication

An often overlooked aspect of “how the puppet master controls the puppet” is security. Here’s how it works:

Authentication Flow

For Remote Servers:

1. OAuth 2.1 Flow (most common):

User → Claude: “Connect to my Notion workspace”
    ↓
Claude → Notion MCP Server: Initiates OAuth
    ↓
Notion MCP Server → Notion: Redirects user to Notion login
    ↓
User authenticates with Notion directly
    ↓
Notion → MCP Server: Returns authorization code
    ↓
MCP Server → Notion: Exchanges code for access token
    ↓
MCP Server stores token securely
    ↓
Future tool calls include: Authorization: Bearer {access_token}

2. API Key Authentication:

// In MCP Server environment variables
process.env.GITHUB_TOKEN = “ghp_abc123xyz...”

// When making API calls
fetch(’https://api.github.com/repos/...’, {
  headers: {
    ‘Authorization’: `Bearer ${process.env.GITHUB_TOKEN}`
  }
});

Critical Security Point:

• Claude NEVER sees the API keys or access tokens

• MCP Server handles all authentication

• Claude sends standardized requests

• MCP Server adds authentication before calling third-party API

Permission and Approval System

MCP includes a built-in approval mechanism:

// Server marks tool as requiring approval
{
  name: “delete_repository”,
  description: “Permanently deletes a GitHub repository”,
  dangerous: true,
  requiresApproval: true
}

// When Claude tries to call this:
Claude → Server: {method: “tools/call”, params: {name: “delete_repository”}}
    ↓
Server → Claude: {requiresApproval: true, toolName: “delete_repository”}
    ↓
Claude → User: “The AI wants to delete a repository. Approve?”
    ↓
User clicks “Approve”
    ↓
Claude → Server: {method: “tools/call”, approved: true, ...}
    ↓
Server executes the action

Error Handling: When Strings Break

Here’s how MCP handles errors at each layer:

Transport Layer Errors

// Connection fails
Server process crashes
    ↓
Claude detects broken pipe on stdin/stdout
    ↓
Claude shows user: “Weather server disconnected”
    ↓
Attempts reconnection or marks tool unavailable

Protocol Layer Errors

// Invalid JSON-RPC message
Request: {”method”: “tools/call”}  // Missing required ‘id’
    ↓
Response: {
  “jsonrpc”: “2.0”,
  “id”: null,
  “error”: {
    “code”: -32600,
    “message”: “Invalid Request: missing id field”
  }
}

Tool Execution Errors

// Tool fails during execution
Request: {method: “tools/call”, params: {name: “get_weather”, arguments: {city: “InvalidCity”}}}
    ↓
Response: {
  “jsonrpc”: “2.0”,
  “id”: 5,
  “result”: {
    “content”: [{
      “type”: “text”,
      “text”: “Error: City ‘InvalidCity’ not found in weather database”
    }],
    “isError”: true
  }
}

Claude then tells the user: “I couldn’t find weather data for that city. Please check the spelling.”

Understanding the Connection

The “magic” of MCP isn’t magic at all. It’s a carefully designed protocol with three clear layers:

1. Transport Layer: The physical connection (STDIO pipes or HTTP) 2. Message Layer: JSON-RPC 2.0 format for structured communication
3. Protocol Layer: Standardized MCP methods and data formats

The MCP Server is the crucial translator that:

• Speaks standardized MCP to the AI

• Speaks service-specific APIs to the tool

• Handles authentication and security

• Translates data formats in both directions

This separation of concerns is why MCP succeeds where custom integrations failed. The AI doesn’t need to know about every tool’s quirks, and tools don’t need to understand AI-specific formats. The MCP Server bridges the gap with a standard protocol that both sides can implement once and reuse everywhere.

The puppet master (AI + MCP Client) pulls strings (sends JSON-RPC messages over transport), which connect to the puppet’s joints (MCP Server translates to tool APIs), making the puppet move (tool executes action and returns result). Each layer has a specific job, and together they create the seamless integration that makes AI agents powerful and practical.

Articles I enjoyed this week

• Concurrency and Parallelism - Franco Fernando

• How to Stay Relevant as an Engineering Leader While Empowering Others - Gregor Ojstersek, Djordje Mladenovic

This passion about understanding the HOW was a massive driver. In the audio field I wanted to know how amplifiers work and how I could obtain a certain sound. In IT, no matter the topic, I needed to go deeper. I need to understand algorithms. I need to fully understand how a web server works. Why a system needs a certain part.

As a first Linux distribution I installed Gentoo with a uni colleague of mine. He was more experienced and enthusiastic about Linux and I was fascinated by the fact that Gentoo compiles all the packages with the legendary emerge. That I need to compile the kernel and know my hardware pretty well. Considering that it was 2006 the community was already amazing. The Gentoo documentation was the best around and it was translated in several languages already (at the time having the doc in Italian for me was a big plus). I loved the experience of that installation. It took me 1 week probably to have a usable machine. That was only one example.

Those years saw also the birth of Rails. How does the configuration work? How is this magic put together? What is a Rack server and all the middleware? Years later I re-did the same deep dive with Spring. I understand now that this need of mine to understand kept me away from some more abstract and complex concepts and algorithms. I was never a fast or particularly talented "coder" because if I don't understand the why and how immediately my brain will start grinding gears. Complex algorithms, ML stuff, and so on have always been tough for me. I know the concepts but cannot implement them confidently.

The will of understanding is still there. And that's why I want to go through the process of writing my own JVM-compatible programming language. It came to me like a random thought and the more I was thinking about it the more I remembered I was always fascinated by the concept. Some years ago a friend advised me to read "Ruby Under the Hood" by Pat Shaughnessy an amazing book going through every language feature. That book is a great inspiration for this project and I hope that I can manage to have some results. Another big inspiration is the amazing JRuby project by the great and powerful Charles Oliver Nutter. I will use AI to help me with explanations of the concepts but I will try to code on my own.

Subscribe now

Finding My Language's Identity

So here I am, starting this journey with the same curiosity that made me compile kernels in 2006. What kind of language do I actually want to create? The JVM already hosts dozens of languages. Kotlin brought null safety and conciseness. Scala merged functional and object-oriented paradigms. Clojure brought Lisp to the JVM. So what gap am I trying to fill with my language let's call it “rix“?

I needed to examine what I personally find frustrating in existing languages. Java's verbosity? Python's performance characteristics? JavaScript's... well, JavaScript-ness? After some reflection, I realized I wanted something that felt approachable like Ruby but could leverage the JVM's mature ecosystem and performance characteristics. Not revolutionary evolutionary.

The core question became: Should rix lean functional, object-oriented, or try to be everything to everyone? I've seen languages try to do everything and end up with confusing mental models. But I've also seen overly opinionated languages that feel restrictive. My answer: start with a functional lean but don't lock myself into a corner. Hybrid by design, functional by default.

Syntax Philosophy: What Feels Right to My Brain?

Here's where my need to understand everything deeply kicked in. I could go full Lisp with parentheses everywhere, or create something entirely novel. But why make developers learn completely new patterns when there are already elegant solutions?

Looking at Ruby's method definition syntax:

def greet(name)
  "Hello, #{name}"
end

This feels right to me. No type annotations cluttering simple functions. No semicolons. The def/end blocks are clear without being verbose. It's what I reach for when sketching ideas on paper.

But wait does this work on the JVM? Ruby's dynamic nature seems at odds with Java's static typing. Here's where I had to dig deeper into how JRuby actually works, just like I did with Rails and Spring years ago. Turns out, you can absolutely start dynamic and add types later. The JVM's Object type can hold anything, and invokedynamic can handle method dispatch.

The Type System Dilemma

This led me to a crucial decision point that reminded me of my Gentoo days do I compile everything from source (static types from day one) or use a package manager approach (gradual typing)?

Option A: Static from the start

def add(x: Int, y: Int): Int
  x + y
end

Option B: Dynamic with optional types

def add(x, y)  # Start here
  x + y
end

# Later evolution:
def add(x: Int, y: Int): Int  # Add when needed
  x + y
end

I chose Option B. Why? Because I want to use this language while building it, just like I wanted a working desktop while learning Gentoo. Static typing is great, but it adds complexity to the compiler that I'm not ready to tackle in week one. Start simple, evolve incrementally. My brain needs to understand each layer before moving to the next.

The Mutability Question

Functional languages love immutability, but let's be honest about basic programming. My brain started grinding gears on this one:

counter = 0
# How do I increment this if everything's immutable?

I found myself wrestling with purity versus practicality. Purely functional approaches are elegant but can be cognitive overhead for straightforward algorithms. And if I don't understand something immediately, I get stuck.

My compromise: mutable variables, immutable data structures by default.

# Variables can be reassigned (practical)
counter = 0
counter = counter + 1

# But lists don't mutate in place (functional flavor)
numbers = [1, 2, 3]
more_numbers = numbers.append(4)  # numbers unchanged

This gives me the best of both worlds: familiar control flow with functional data handling. I can understand and implement this without my brain grinding gears.

Implementation Strategy: Learning by Building

Now for the meta-question: How do I actually build this thing? This is where my engineering background kicks in.

Parser Generation vs Hand-Written: I could write a recursive descent parser by hand for maximum control, but honestly? I want to iterate quickly on syntax, just like I needed that emerge command to quickly try different package configurations. ANTLR lets me modify grammar files and regenerate parsers instantly. Perfect for experimentation and learning.

Bytecode Generation: The ASM library gives me direct control over JVM bytecode without javac's overhead. More work upfront, but I'll understand exactly what my language generates. This is the equivalent of compiling my own kernel more effort, but total understanding.

Build System: Maven for now. Boring but reliable. Like choosing a stable Linux distribution after spending a week with Gentoo.

What “rix” Looks Like (v0.1)

After all this analysis, here's where I landed for the initial version:

# Simple function definition
def greet(name)
  "Hello, " + name
end

# Variables and basic types
age = 25
active = true
numbers = [1, 2, 3, 4]

# Control flow as expressions
status = if age >= 18
  "adult"
else  
  "minor"
end

# Function calls
message = greet("World")
puts(message)

Clean, readable, familiar. Nothing groundbreaking, but a solid foundation to build on. Every piece of this I can understand and implement without getting lost in complexity.

Next Steps

With the basic syntax decided, it's time to make this real. That means diving into ANTLR grammar files and getting "Hello, World" to actually compile and run on the JVM. The journey from idea to working interpreter starts now, driven by the same curiosity that made me want to understand how amplifiers work and why Rails was so magical.

Subscribe now

Articles I enjoyed this week

• Decoupling Your Monolithic Application: A Practical Guide for Software Engineers - Marcos F. Lobo 🗻🧭

• How 3 raw visuals teach you REST APIs, Linux Filesystems and SSO Instantly! - Sketech | Unfiltered Dev Notes

Why I Disappeared

Life got in the way, as it tends to do. I bought a house my first one and spent months renovating it from top to bottom. Between dealing with contractors, choosing tiles I'll probably regret in five years, and figuring out how rental agreements work when I decided to rent it out, my writing took a backseat.

Summer didn't help. For once, I decided to actually enjoy the nice weather with my partner instead of being glued to my laptop. You know, doing all those things people say you should do but rarely make time for.

Then there's my new obsession with running. I enrolled in a marathon and I'm running like a maniac, especially on weekends. Turns out training for 42 kilometers takes up a surprising amount of mental bandwidth who knew?

But the real reason I stopped writing runs deeper than busy schedules and summer distractions.

Subscribe now

The Content Problem

I realized I don't want to and frankly, I can't keep writing my take on obvious, well-known, and thoroughly documented topics. No matter how entertaining I try to make it, a Pub/Sub pattern is always the same, and it's already explained in a million reputable places. No matter how much I want to showcase my knowledge, there are simply better resources out there for learning common patterns.

I cannot stand that kind of content anymore, and I sure as hell can't create it.

Most of my didactical content bored me to death. Looking back at what I've written both here and on X where I was trying to post consistently only the career-related pieces or the ones with practical examples actually interested me. I don't want to talk about stuff that bores me. I'm already struggling with liking my job and my field; I don't need to fuel the sensation that everything I do has lost its spark.

A New Direction

I'm writing again, but it's going to be different. Way more practical, way more interesting at least for me, and hopefully for you too. And don’t worry there will still be place for my rant about the industry and my draconian advice on career.

Subscribe now

I'll focus on practical guides and real advice. If I talk about architecture, it'll only be through concrete examples and only if I consider the topic worthy of your time, but mostly my time. I love writing and I still love discovering new things I just can't force myself into content I don't want to create because "that's my role."

I want to write about my personal passions in IT. My love for Linux, learning programming languages I'll never use at work, frameworks that caught my eye, tools that make my life easier. The stuff that actually gets me excited about technology again.

I want to go back to writing because the process is fun, and the content should be fun too. Not everything needs to be a comprehensive guide or a definitive resource. Sometimes it's enough to share what you're curious about, what you're tinkering with, what made you think "huh, that's interesting" while scrolling through GitHub at 2 AM.

This is my newsletter, after all. Time to make it actually mine.

Articles I enjoyed this week

• Rails World 2025 Opening Keynote - David Heinemeier Hansson

• Linear Interpolation - Franco Fernando

• Model Context Protocol 101 - Saurabh Dashora

As I started scaffolding the architecture, I reached that familiar crossroad: choosing the tech stack.
It’s my idea, my project. I could use whatever technology I like, from the most mainstream framework to some quirky self-made library.

So what should I choose, and why?

Let’s go back to the premise:
I want to monetize it fast.

This scenario might sound familiar. Maybe it’s your own side project. Maybe it’s a custom solution for a client. Either way, if time is critical, there’s only one direction that makes real sense:

Go with what you know best.

If you need to deliver, maintain, and possibly expand fast, there’s no room for tech experiments.
Choosing a technology stack you're already familiar with lets you focus on what actually matters: building something that works and satisfies end users.

Subscribe now

But what if you want to experiment?

There’s no doubt: doing a real project with an unfamiliar technology is one of the best ways to learn.
But—there’s always a “but”—you’ll spend a lot of time learning without making tangible progress on your project. That time loss can be frustrating, especially when delivery speed is a goal. You'll hit bumps, burn hours, and get blocked by things that have nothing to do with your core idea.

That’s fine when time isn’t a factor. But when it is? That learning curve becomes a liability.

That’s why I also brought up the example of custom work for a client. There’s no client on Earth without time constraints. If you want to reduce stress and risk, using a familiar stack is the most reliable path.

Every project already has enough uncertainty. Adding more on the technical side can turn friction into failure.

Real-world vs. tutorials

Learning is great—but we all know real-world products have little in common with step-by-step tutorials. When you're on your own, you face a million edge cases and need to adapt well-known concepts to your specific use case. That takes time, even if you’re an experienced engineer.

A word on bleeding-edge tech

Most of us in tech love innovation. There’s always a new language, framework, or tool dropping every week.
So what happens if you pick something ultra-new for your project?

You’ll probably run into incomplete documentation and missing features.

Sure, lack of docs can sometimes be solved by diving into the source code. But missing features? That’s another story. You might need to build significant parts yourself—components that the framework should handle. And those components will need to be solid: engineered properly, tested thoroughly, and ready for production.

Remember, we want to go live fast—and that means a certain level of maturity and stability is non-negotiable.

Personal example

Contributing to new tech is exciting, no doubt. I remember back when I was deep into JavaScript, I contributed to a little-known framework called Vue.js. It was fun, I learned a lot, and I still remember what I did.

At the same time, at work, I was building production apps—and guess what I used there? Angular 2.
Well-established. Fairly complete. Backed by a large community.

Learning and making money rarely move at the same pace.

Flashy vs. reliable

If you’ve got the luxury of time and money to invest two or three times longer in your project, more power to you. But for me, the reliability of a production tool is way more important than the flashiness of the tech stack.

In over 15 years of career, I don’t recall a single end user asking me which technology stack I used.
Sure, there are always a few nerdy exceptions who care about this stuff—but let’s be honest, they’re not the ones paying the bills.

As a lead architect, I’ve had countless conversations with enthusiastic junior devs or tech gunslingers about why we aren’t using the “next big thing.” And often, the reason is simple: it’s too new.
Statistically, fewer people know it. The community support isn’t there yet. Documentation might be spotty. Libraries might not exist. And when you need help, you’ll be mostly on your own.

Will AI change this?

That said, I’m genuinely curious to see how this dynamic evolves with the rise of AI.

Right now, most AI models have a knowledge cutoff. Even when they can access the internet, their real strength still depends on the quality and volume of documentation available. The newer the tech, the less training data there is—so AI help is limited. I expect this will shift quickly, but today, it’s still a factor.

Subscribe now

Articles I enjoyed this week

• Key API Design Considerations by Saurabh Dashora

• Every Outbox Needs an Inbox by Raul Junco

This was my question back in October, when I created the IT Untold publication here on Substack.

My idea was to start fresh—writing about tech on a platform that encourages long-form content and slower-paced media consumption.

And to some extent, that’s what I found. I began writing deeper articles, taking the time to explore topics more thoroughly, and posting less frequently but with more substance. But on the reading side, I quickly ran into the same old problem.

Hype and buzzwords.

This platform, like almost every social media space filled with tech content, is polluted by the same recurring noise.

AI bros and people obsessed with numbers.

The AI bubble started as a revolution in 2023. Like many others, I was genuinely excited to try it, explore its potential, and understand its limitations. For a moment, it really felt like something new and promising.

But soon, on every platform with tech news or commentary, the miraculous benefits of AI became omnipresent.

That’s when the infamous “10x developer” meme resurfaced, accompanied by dramatic talk about the end of “old developers” and the urgent need to embrace AI tools to avoid falling behind.

I’m not pessimistic about this shift—I’m quite sure that, in one way or another, everyone will end up using AI. That’s just how technology adoption works.

The problem is the spam. It got worse and worse.

Building LLM wrappers became the thing to do for all of 2023 and a good chunk of 2024. Useless chat apps popped up everywhere, with self-proclaimed “prompt engineers” repackaging your input in a slightly different prompt and calling it innovation.

Anyone with a basic understanding of IT could see through the nonsense. LLMs became so advanced that the so-called "art" of prompt engineering became mostly irrelevant.

And so, the AI bros needed to find new ways to stay relevant.

That’s been the real problem since the beginning. The AI revolution made a lot of people with nothing interesting to say look relevant—just because they rode the massive hype wave. I’ve never seen so many posts and courses about “growing your audience” until people figured out they could just slap “AI” on top of it.

Suddenly, everyone and their mom was trying to convince me that I needed AI to write. That I could generate passive income using AI. That I could use it to create content for social media. That AI would grow my audience from zero to profit.

"Are you a mom who wants to make extra money? Use this method to learn how to leverage AI tools."

For a while, I was intrigued by those bold claims.

Was it true? Could anyone really build an audience this way? Could you just generate content and magically start selling a product or service?

So I started digging.

And I noticed something odd: many of the people selling these “methods” used social media only for that—selling methods.

What do I mean?

The accounts of these snake-oil sellers were filled exclusively with content about content creation. There was no actual product. No past experience. No real expertise.

In my research, I came across an insane number of stay-at-home moms selling courses on "making money with digital products." But if you look across their entire online presence, the only product they have is a course on how to make money selling digital products.

It’s a weird chicken-and-egg situation, and it applies to countless other niches too.

So—what does this have to do with AI? A lot.

AI made it easier for people to produce grammatically correct, visually polished material, padded with filler that makes it look professional. It gives the illusion that the so-called expert spent time crafting a valuable course.

AI gave people the impression that making money online is effortless.

And while there are still many genuine, high-quality creators who love sharing knowledge and maybe earning from it, they now coexist with a tidal wave of fluff.

I’m absolutely pro-AI when it comes to content creation—don’t get me wrong. It’s an incredible partner for revising, polishing, avoiding repetition, and catching strange mistakes. But it’s not a panacea. It’s not a silver bullet.

Most people consume content in their free time. It’s a way to stay up to date, learn something new, or simply escape from everyday life.

That’s why the absurd amount of pollution in the content creation world feels even more frustrating—especially here on Substack, where the newsletter format is designed for depth, not surface-level noise.

I want to read about interesting concepts, exciting technologies, and genuine experiences. Sure, use an LLM to help you put an article together—but please, don’t bury me under a mountain of meaningless AI-themed posts.

If I sound dramatic, just try scrolling through the Technology tab on your Substack homepage. It’s ridiculous.

But this isn’t just a rant aimed at the tech space on social media. It’s mostly an invitation—for those who do have something to say: say it. Keep publishing good content. Keep sharing your thoughts, experiences, and knowledge.

Your voice matters. And sooner or later, your content will stand out.

Subscribe now

Articles I enjoyed this week

• How Kubernetes Works Internally? by Saurabh Dashora

• Why Just Publishing Events Isn’t Enough by Raul Junco & Marcos F. Lobo

Despite being around for years, threat modeling has recently gained renewed attention, including a mention in the latest ThoughtWorks Technology Radar. The reason? Teams are starting to treat it less as a specialized security task and more as a regular design habit. And that’s a welcome shift.

Subscribe now

What Threat Modeling Actually Is

The premise of threat modeling is simple: every system has assets worth protecting, and every system makes assumptions about what can and cannot happen. Threat modeling is about identifying both, and then challenging those assumptions.

It often revolves around four recurring questions:

1. What are we building?

2. What could go wrong?

3. What are we going to do about it?

4. Did we do a good enough job?

It’s not a formal method or a framework. It’s a structured conversation, usually centered around architecture diagrams, that helps a team uncover risks and make design choices with intent, not just hope.

Why It Matters in Architecture

Security flaws aren’t always the result of coding mistakes. They’re often a symptom of misplaced trust, implicit assumptions, or blind spots in the architecture itself.

If a service assumes the caller is authenticated because it's “internal,” or if a frontend trusts data returned from an API without verifying it, those are architectural issues. They aren’t going to be caught by linters or firewalls.

Threat modeling shifts the conversation left, before production, before implementation, and puts it in the hands of those making design decisions. It allows teams to reduce the attack surface and build in defense where it’s most effective: at the edges of architectural trust boundaries.

Making It a Habit, Not an Event

One of the most effective things teams can do is lower the barrier to threat modeling. If it becomes a heavyweight activity with forms, templates, and formal reviews, it’ll get deferred until “later.” In most cases, later never comes.

Teams that do this well treat it as a recurring, informal discussion, often baked into sprint planning, story refinement, or design reviews. It doesn’t need to be exhaustive every time. A 30-minute conversation with a whiteboard sketch can go a long way, especially when focused on a single new feature or integration point.

The key is frequency, not completeness. Risks evolve as the system evolves. A “threat model” isn’t a static artifact, it’s a lens to regularly re-examine your system’s weak spots.

How to Run an Effective Threat Modeling Session

Here’s what works in practice, no buzzwords, no silver bullets:

1. Start with a Diagram

Draw how the system works, even if it’s rough. Show components, users, data flows, and especially trust boundaries (e.g., between the browser and backend, between services, between your system and third parties). If you can’t draw it, you probably don’t understand it.

2. Ask “What Could Go Wrong?”

This is the heart of it. Walk through each part of the system and ask:

• What if this component is compromised?

• What happens if this data is tampered with?

• What assumptions are we making about the network, the identity provider, the user?

3. Use Threat Categories If Needed

Many teams use the STRIDE model (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) as a checklist. It helps, but don’t follow it blindly. Think of it as training wheels — a way to spark questions, not to gatekeep answers.

4. Prioritize, Don’t Panic

Not every risk needs a mitigation. Some just need documentation. Some are so unlikely they’re not worth addressing now. But some will point to weak spots in the design that should be fixed early. The point is to surface them, discuss them, and make decisions deliberately.

5. Document the Assumptions

Even if you don’t write down a full report, log your assumptions. For example:

• “We assume service X cannot be accessed from the public internet.”

• “We trust the identity provider’s tokens are valid and time-bound.”

• “This system doesn't store PII, so data exposure is low-impact.”

These assumptions are often what come back to bite you six months later, especially during incident response.

Common Pitfalls to Avoid

Even with good intentions, threat modeling efforts can go off track. Here are the traps to watch for:

• Trying to cover everything at once – It’s better to model one feature well than the whole system badly. Keep it scoped and focused.

• Over-formalizing the process – Threat modeling isn’t compliance. It’s about clarity and critical thinking, not checkboxes.

• Doing it once, then forgetting about it – Systems change. So do risks. If you don’t revisit your assumptions, they’ll silently rot.

• Relying only on security experts – Engineers, architects, product owners — all of them see different angles. Don’t gatekeep the process.

Threat Modeling in Agile Teams

Traditional security reviews often happened late, if they happened at all. That doesn’t work in iterative environments. Teams need lightweight, repeatable practices that match the pace of delivery.

Some useful strategies:

• Incorporate threat modeling in backlog grooming for features that affect trust boundaries or data flow.

• Add “evil user stories” (e.g., “As an attacker, I want to bypass rate limits to scrape data”) to uncover threats from an adversary's point of view.

• Treat architectural spikes as opportunities to explore security implications, not just technical feasibility.

The point is not to slow down agility, it’s to build security thinking into the process without friction.

Good architecture isn’t just about performance, scalability, or modularity. It’s about trust, knowing where your system is vulnerable and putting the right controls in place.

Threat modeling gives teams the space to challenge their assumptions and clarify their thinking. It’s not just a security technique; it’s a design discipline. And like all good design habits, its power comes from repetition, not complexity.

You don’t need a dedicated security team to start. You just need to care enough to ask, “What could go wrong?” and take the time to answer it while it still matters.

Subscribe now

If you like my content enough to pay me a coffee…

Articles I enjoyed this week

• How (not to) fail a system design interview by Franco Fernando

• A Deep Dive into Apache Iceberg: A Journey Through the Future of Data Lakehouse Table Formats by Lorenzo Bradanini

• Load Balancer, Gateway, BFF & GraphQL: The Squad Handling API Calls by Saurabh Dashora

One aspect I consider key when talking about developing and deploying an application is Infrastructure as code (IaC).

I think it is crucial to touch this aspect before we move on to the deployment view.

Subscribe now

IaC is an essential practice in modern software development, especially when working in the cloud. It allows teams to define infrastructure through code rather than manual processes, making environments reproducible, scalable, and maintainable.

In this article, we'll explore what IaC is, the main technologies used to implement it, and why a build pipeline is crucial. We'll also look at key considerations when working with IaC in cloud environments—focusing on Microsoft Azure.

What Is Infrastructure as Code?

IaC is the practice of managing infrastructure (networks, virtual machines, storage, databases, etc.) using machine-readable definition files instead of manual configuration. This approach brings several advantages:

• Consistency – Environments can be recreated reliably.

• Version Control – Infrastructure changes are tracked like application code.

• Automation – Reduces human error and speeds up deployment.

• Scalability – Makes it easier to replicate environments across teams and regions.

Declarative vs. Imperative IaC

IaC tools fall into two main categories:

• Declarative (e.g., Terraform, Pulumi, Bicep): Define the desired state, and the tool figures out how to get there.

• Imperative (e.g., Ansible, PowerShell, Bash scripts): Define step-by-step instructions to configure infrastructure.

While both approaches have their use cases, declarative IaC is generally preferred for cloud environments because it simplifies state management and makes infrastructure changes predictable.

Main Technologies for Implementing IaC

Several technologies are commonly used to define and deploy infrastructure:

• Terraform – A widely adopted declarative IaC tool that works across multiple cloud providers.

• Bicep – A domain-specific language (DSL) for defining Azure infrastructure, designed as a more readable alternative to ARM templates.

• Pulumi – Allows writing IaC using general-purpose programming languages like Python, TypeScript, and Go.

• Ansible – Often used for configuration management but can also provision infrastructure in an imperative way.

• Cloud-Native Tools – Each cloud provider offers its own IaC tools (e.g., AWS CloudFormation, Azure Resource Manager).

For Azure-focused IaC, Bicep and Terraform are the most common choices.

Why the Build Pipeline Matters

Writing infrastructure code is just the first step. To make IaC truly effective, it should be integrated into a build pipeline that ensures:

• Automated validation – Linting, syntax checks, and security scans.

• Plan and review processes – Seeing infrastructure changes before applying them (e.g., terraform plan).

• Safe deployment – Applying changes incrementally and avoiding downtime.

A typical Azure DevOps or GitHub Actions pipeline for Terraform or Bicep would include:

1. Linting & validation – Checking for syntax errors.

2. Plan phase – Generating a preview of the changes.

3. Approval process – Requiring human approval for critical infrastructure updates.

4. Apply phase – Deploying changes only after approval.

Without a proper pipeline, IaC can become a manual, error-prone process—defeating its purpose.

IaC in Cloud Environments: Why It’s Critical

Cloud providers like Azure offer highly dynamic environments where infrastructure is created, modified, and destroyed frequently. Manually managing cloud resources is neither scalable nor reliable. IaC is essential for:

• Managing multiple environments (Dev, Staging, Production) consistently.

• Scaling infrastructure dynamically without manual intervention.

• Tracking changes in source control instead of relying on ad-hoc modifications.

• Disaster recovery by enabling rapid environment restoration.

Example: Provisioning an Azure AKS Cluster with Terraform

To see how IaC simplifies cloud resource management, consider deploying an Azure Kubernetes Service (AKS) cluster using Terraform:

resource "azurerm_resource_group" "example" {
  name     = "myResourceGroup"
  location = "East US"
}

resource "azurerm_kubernetes_cluster" "example" {
  name                = "myAKSCluster"
  location           = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  dns_prefix         = "myaks"
  
  default_node_pool {
    name       = "default"
    node_count = 2
    vm_size    = "Standard_DS2_v2"
  }

  identity {
    type = "SystemAssigned"
  }
}

This Terraform configuration defines an Azure resource group and an AKS cluster with a default node pool. Running terraform apply provisions the infrastructure automatically, ensuring consistency across environments.

Key Considerations When Implementing IaC in the Cloud

When using IaC in cloud environments, there are several things to keep in mind:

1. State Management

• Terraform stores state files that track deployed resources.

• Use remote state backends (e.g., Azure Storage) instead of local files to avoid conflicts.

• Enable state locking to prevent concurrent updates.

2. Security Best Practices

• Never hardcode secrets in IaC files; use Azure Key Vault.

• Apply least privilege principles with managed identities instead of storing credentials in code.

• Scan IaC files for security vulnerabilities before applying changes.

3. Modularization & Reusability

• Break infrastructure into reusable modules instead of monolithic files.

• Define separate IaC configurations for networking, compute, and applications.

• Use parameterization to make configurations flexible across environments.

4. Handling Cloud Drift

• Cloud environments can change outside of IaC tools (manual updates, API calls).

• Regularly run terraform plan or equivalent commands to detect drift.

• Implement policy enforcement (e.g., Azure Policy) to prevent unauthorized changes.

5. Cost Control

• IaC makes it easy to spin up resources, but costs can escalate quickly.

• Use resource tagging and budget monitoring to track expenses.

• Implement automatic resource cleanup for non-production environments.

Infrastructure as Code is a fundamental practice for managing cloud infrastructure efficiently. By using tools like Terraform or Bicep, integrating IaC into a build pipeline, and following best practices, teams can ensure their infrastructure is consistent, scalable, and secure.

When working in cloud environments—especially Azure—careful consideration of state management, security, and cost control is essential. While IaC simplifies many aspects of infrastructure provisioning, it still requires a well-thought-out approach to avoid pitfalls.

If you're not using IaC yet, now is the time to start!

Subscribe now

If you like my content enough to pay me a coffee…

Articles I enjoyed this week

• 5 Must-Know Deployment Strategies by Saurabh Dashora

• Trends #7: TypeScript is getting 10x faster! by Milan Milanović

• How Apple Pay Handles 41 Million Transactions a Day Securely 💸 by Neo Kim

Some time ago, a junior developer I was working with asked an interesting question:

"I know that passing a Supplier<T> to a method allows for lazy loading, but what happens under the hood? If the supplier calls a service method that fetches data from a REST API, is the API call made immediately? If not, how does dependency injection work in this case?"

This was a great question because it touched on multiple important concepts: functional interfaces, lazy evaluation, and dependency injection. While many Java developers use Supplier<T> in their code, not everyone fully understands its inner workings. So, let’s dive into it.

Subscribe now

A Quick Refresher: What is Supplier<T>?

Supplier<T> is a functional interface in Java that represents a function that takes no arguments but returns a value of type T.

Here’s its simple definition from java.util.function:

@FunctionalInterface
public interface Supplier<T> {
    T get();
}

• It has a single abstract method, get(), which returns a value but does not take any parameters.

• It is commonly used for lazy evaluation, deferred execution, and factory methods.

Basic Example

To see Supplier<T> in action, let’s define one that generates a greeting:

Supplier<String> greetingSupplier = () -> "Hello, World!";
System.out.println(greetingSupplier.get());  // Only now is the value generated

Since Supplier<T> does not execute immediately, it allows us to delay computations until they are actually needed.

What Happens at the JVM Level?

When you pass a Supplier<T> to a method, you are passing a lambda expression (or a method reference) that represents a piece of code to be executed later.

At the JVM level:

• The lambda expression or method reference is converted into an instance of a functional interface (Supplier<T>).

• If the lambda captures variables from the enclosing scope, the compiler generates a synthetic class that holds references to those captured variables.

• The actual code inside the lambda or method reference is not executed immediately. Instead, it is stored as an instance of Supplier<T> and invoked later using .get().

Example:

Supplier<String> lazySupplier = () -> "Hello, World!";

At runtime, the JVM creates an instance of a synthetic class implementing Supplier<String>, where get() returns "Hello, World!" when called.

Understanding the Lazy Execution of Supplier<T>

Let’s consider a slightly more interesting example. Suppose we have a method that retrieves data from an external service:

class DataService {
    public String fetchData() {
        System.out.println("Fetching data...");
        return "Data from API";
    }
}

If we create a Supplier<String> using a method reference:

DataService service = new DataService();
Supplier<String> dataSupplier = service::fetchData;

What happens here?

1. No API call is made yet – service::fetchData is just a reference, not an execution.

2. When .get() is called, only then does fetchData() execute.

Here’s a full example demonstrating this behavior:

public class LazyLoadingExample {
    public static void main(String[] args) {
        DataService service = new DataService();
        Supplier<String> dataSupplier = service::fetchData;
        
        System.out.println("Before calling get()");
        String result = dataSupplier.get();  // Triggers the actual API call
        System.out.println("Result: " + result);
    }
}

Console Output:

Before calling get()
Fetching data...
Result: Data from API

As you can see, fetchData() is not executed at the time of supplier creation, only when .get() is called.

How Dependency Injection Works with Supplier<T>

A natural follow-up question is:
"If the service is injected using a dependency injection (DI) framework like Spring, will it still work?"

Let’s see how Supplier<T> interacts with DI.

Spring Example

@Service
class DataService {
    public String fetchData() {
        System.out.println("Fetching data from REST API...");
        return "Data from API";
    }
}

@Component
class ConsumerComponent {
    private final DataService dataService;

    @Autowired
    public ConsumerComponent(DataService dataService) {
        this.dataService = dataService;
    }

    public void execute() {
        Supplier<String> dataSupplier = dataService::fetchData;

        System.out.println("Before calling get()");
        System.out.println("Fetched: " + dataSupplier.get()); // Triggers API call
    }
}

Spring’s dependency injection ensures that dataService is available when needed, and lazy evaluation means that the API call happens only when requested.

Real-World Use Cases for Supplier<T>

1. Avoiding Unnecessary Computations

public void process(Supplier<String> expensiveOperation) {
    if (shouldUseResult()) {
        System.out.println(expensiveOperation.get()); // Only called if needed
    }
}

1. Lazy Initialization

private Supplier<Connection> connectionSupplier = this::createConnection;

1. Deferred Logging

private static void log(Supplier<String> message) {
    if (isDebugEnabled()) {
        System.out.println(message.get());
    }
}

Key Takeaways

• Supplier<T> is a functional interface that provides a value on demand.

• When passing a method reference (service::fetchData), no execution happens until .get() is called.

• In Spring DI, injected services work as expected, and lazy evaluation ensures API calls are made only when needed.

• Common use cases include avoiding unnecessary computations, lazy initialization, and performance optimization.

Understanding how Supplier<T> works under the hood helps us write more efficient and performant code while leveraging modern Java practices.

If you’ve used Supplier<T> in an interesting way, I’d love to hear about it! Let’s continue the discussion in the comments.

Subscribe now

Articles I enjoyed this week

• Apache Kafka 🔥 Your Gateway to High-Demand Jobs - Sketech #22 by Nina

• Databricks Photon Engine: Boosting Query Performance and Optimizing Big Data Processing by Lorenzo Bradanini

Permanent Features

These features are finalized and fully integrated into JDK 24:

1. Ahead-of-Time Class Loading & Linking (JEP 483)

   • Part of Project Leyden, this feature improves JVM startup time by making an application's classes instantly available in a loaded and linked state when the JVM starts. It builds on Application Class Data Sharing (AppCDS) to reduce overhead, particularly beneficial for short-lived programs or cloud-based applications.

2. Class-File API (JEP 484)

   • A standardized API for parsing, generating, and transforming Java class files, now finalized after previews in JDK 22 and 23. It serves as an internal replacement for ASM in the JDK and supports tools and frameworks like Spring and Hibernate that manipulate bytecode.

3. Stream Gatherers (JEP 485)

   • Enhances the Stream API by allowing developers to define custom intermediate operations. This makes stream pipelines more flexible and expressive, enabling operations on infinite streams. The java.util.stream.Gatherers class provides standard implementations, and developers can create their own using functional interfaces like Integrator.

4. Synchronize Virtual Threads without Pinning (JEP 486)

   • Improves virtual thread performance by eliminating pinning (where a virtual thread remains tied to a platform thread) when using synchronized blocks or methods around blocking operations. This makes virtual threads more practical for a wider range of use cases.

5. Key Derivation Function API (JEP 478)

   • Introduces a new javax.crypto.KDF API for key derivation functions, enabling cryptographic algorithms like HMAC-based Extract-and-Expand (HKDF) and Argon2. This supports post-quantum cryptography efforts, such as Hybrid Public Key Encryption (HPKE), and enhances security for applications interacting with cryptographic hardware.

6. Late Barrier Expansion for G1 (JEP 491)

   • Optimizes the G1 garbage collector by shifting barrier expansion (used to track memory accesses) to a later stage in the C2 JIT compilation pipeline, simplifying implementation and potentially improving performance.

7. Remove the Windows 32-bit x86 Port (JEP 479)

   • Discontinues support for the 32-bit Windows x86 JVM, following its deprecation in JDK 21, as modern hardware overwhelmingly uses 64-bit architectures.

8. Permanently Disable the Security Manager (JEP 493)

   • Removes the Security Manager entirely (deprecated since JDK 17), reflecting its diminished role in modern Java security. Applications relying on it may require architectural changes.

9. ZGC: Remove the Non-Generational Mode (JEP 490)

   • Eliminates the non-generational mode of the Z Garbage Collector, streamlining maintenance and focusing on the generational mode, which is more efficient for most use cases.

10. Warn upon Use of Memory-Access Methods in sun.misc.Unsafe (JEP 498)

    • Issues runtime warnings when memory-access methods in sun.misc.Unsafe are invoked, encouraging migration to safer alternatives like the VarHandle API or Foreign Function & Memory API.

11. Deprecate the 32-bit Linux x86 Port for Removal (JEP 501)

    • Marks the 32-bit Linux x86 port as deprecated, with removal planned for a future release, aligning with the shift away from 32-bit architectures.

12. Linking Runtime Images without JMODs (JEP 482)

    • Allows jlink to create custom runtime images without JMOD files when built with the --enable-linkable-runtime option, reducing image size for cloud-optimized deployments.

Preview Features

These features are fully implemented but subject to change based on feedback:

1. Scoped Values (Fourth Preview) (JEP 487)

   • Enables sharing immutable data within and across threads more efficiently than thread-local variables. This fourth preview refines the feature introduced in JDK 20.

2. Primitive Types in Patterns, instanceof, and switch (Second Preview) (JEP 488)

   • Extends pattern matching to support primitive types in instanceof and switch statements, enhancing expressiveness (introduced in JDK 23).

3. Flexible Constructor Bodies (Second Preview) (JEP 492)

   • Allows more natural initialization logic in constructors by permitting statements before super() calls, reducing reliance on auxiliary methods (introduced in JDK 23).

4. Module Import Declarations (Second Preview) (JEP 494)

   • Simplifies importing all packages exported by a module with a single declaration, improving modularity (introduced in JDK 23).

5. Simple Source Files and Instance Main Methods (Fourth Preview) (JEP 495)

   • Evolves the Java language to ease beginners into programming by supporting streamlined single-class programs with implicit declarations (refined since JDK 21).

6. Structured Concurrency (Fourth Preview) (JEP 499)

   • Simplifies multithreaded programming by treating groups of related tasks as a single unit, enhancing reliability and observability (refined since JDK 21).

Incubator Features

These are still in development and provided for early feedback:

1. Vector API (Ninth Incubator) (JEP 489)

   • Enhances vector computations for performance on modern CPUs, adding support for 16-bit floats (Float16) and refining operations. It remains in incubation until Project Valhalla’s features mature.

Experimental Features

These are exploratory and disabled by default:

1. Generational Shenandoah (JEP 404)

   • Introduces an experimental generational mode to the Shenandoah garbage collector, aiming to reduce pause times by separating young and old objects.

2. Compact Object Headers (JEP 450)

   • Reduces object header size from 96-128 bits to 64 bits on 64-bit architectures (Project Lilliput), lowering memory usage but requiring explicit enabling due to potential risks.

3. Quantum-Resistant Module-Lattice-Based Key Encapsulation Mechanism (JEP 496)

   • Provides an implementation of a quantum-resistant key encapsulation mechanism (ML-KEM, FIPS 203), enhancing cryptographic security.

4. Quantum-Resistant Module-Lattice-Based Digital Signature Algorithm (JEP 497)

   • Implements a quantum-resistant digital signature algorithm (ML-DSA, FIPS 204), complementing JEP 496 for post-quantum cryptography.

Additional Notes

• Performance and Internal Changes: Features like Ahead-of-Time Class Loading, Compact Object Headers, and G1 optimizations target runtime efficiency, particularly for cloud and serverless environments.

• Deprecations and Removals: The removal of legacy components (e.g., Windows 32-bit port, Security Manager) reflects Java’s focus on modern platforms and security practices.

• Preview Continuity: Many preview features are iterations of prior work under projects like Amber (pattern matching, module imports), Loom (virtual threads, structured concurrency), and Panama (Vector API), indicating ongoing refinement.

Java 24 is a non-LTS release, supported for six months until JDK 25 (an LTS release) arrives in September 2025. Developers can explore these features to prepare for future standards while leveraging immediate benefits in performance and flexibility. For detailed examples and usage, the official JDK 24 documentation and JEP pages provide comprehensive resources.

Subscribe now

Learning to write compelling public technical content is a journey, and I’m still in the middle of it—learning and improving every day. Writing is a craft that evolves with practice, and the more we write, the better we understand how to connect with an audience.

So how does an engineer transition from writing structured documentation to crafting public tech content that resonates? This article explores the nuances of public technical writing, the mindset shift required, and how engineers can develop a unique voice that builds a following.

Subscribe now

The Key Difference: Documentation vs. Public Technical Writing

Many engineers equate technical writing with documentation—after all, writing API references, architecture diagrams, and system design documents is an essential part of software development. But documentation serves a different purpose than public writing:

• Documentation is structured, exhaustive, and neutral. It’s meant to be referenced, not necessarily read from start to finish. Clarity and completeness are more important than engagement.

• Public writing is engaging, opinionated, and designed to teach or persuade. The goal is to capture interest, provide insight, and sometimes even entertain. It doesn’t just inform—it tells a story.

When you write documentation, you assume the reader needs to know exactly how something works. But when you write for a public audience, you assume the reader needs to be drawn in before they even decide to care. This requires a shift from structuring information to structuring a narrative.

Write About What You Learn

One of the best ways to improve as a technical writer is to write about what you are learning. Sharing new concepts, ideas, and challenges not only reinforces your own understanding but also helps others who might be on the same journey. Writing about what you learn makes it easier to remember and apply the concepts in real-world scenarios. Additionally, it creates a sense of relatability with your readers, as they see your growth and can connect with similar experiences.

By documenting your learning process, you also establish yourself as someone who is continuously evolving, which can be inspiring to your audience. Even if you’re not an expert on a topic, writing about it from a learner’s perspective can provide valuable insights to others who are just starting.

Developing an Engaging Writing Style

Public technical writing isn’t just about what you say—it’s about how you say it. A few characteristics make public tech content stand out:

• Conversational yet authoritative tone – The best public-facing technical writing balances clarity with personality. It’s not as rigid as documentation but still maintains credibility.

• Storytelling and real-world examples – Instead of just explaining how a technology works, illustrate why it matters. Case studies, failures, and personal experiences make content relatable.

• Layered complexity – Unlike documentation, which often assumes the reader has already committed to learning, public writing should ease the reader in, starting with an accessible explanation before diving into depth.

Technical concepts don’t need to be dry. Think of your content as a conversation with an intelligent but skeptical reader—someone who needs to be convinced that what you’re writing is worth their time.

Choosing the Right Topics

A key difference between documentation and public writing is that documentation tells people how something works, while public writing often explores why it matters.

Some of the best public-facing technical content falls into these broad categories:

• Explaining complex topics simply – Distilling a challenging concept into an accessible explanation is an invaluable skill.

• Sharing lessons from experience – Writing about mistakes, lessons learned, or unconventional insights adds authenticity.

• Exploring trends and opinions – Well-reasoned opinions on where technology is headed can spark discussion and engagement.

• Guiding career and skill growth – Technical readers appreciate insights on how to improve in their field.

The best topics come from experience—things you’ve struggled with, problems you’ve solved, and ideas you’ve tested. If something surprised you or changed how you think, it will likely resonate with others.

Building a Personal Brand Through Writing

Public technical writing isn’t just about sharing knowledge—it’s about building a reputation. Your writing becomes part of your online presence, shaping how others perceive your expertise.

• Find your niche – Writing consistently about a specific area (e.g., cloud architecture, DevOps, or programming practices) helps establish you as an authority.

• Develop a unique voice – A distinctive perspective or writing style makes your content memorable. Avoid sounding like generic documentation.

• Engage with your audience – Writing isn’t a one-way street. Engaging with readers through comments, discussions, or follow-up posts helps build a following.

A strong personal brand is built through consistency. One well-written article won’t make you known, but regular, high-quality posts will.

Like any skill, technical writing improves with time and practice. I’m still learning, refining my style, and discovering what resonates with readers. The important thing is to start, experiment, and continuously learn from both successes and failures.

For engineers, transitioning from documentation to public technical writing requires a shift in approach. It’s about moving from structured information delivery to storytelling, engagement, and insight-sharing. The best public technical writers don’t just inform—they capture attention, challenge perspectives, and add value beyond what documentation provides.

By focusing on clear, engaging writing and developing a personal brand, engineers can build an audience that values their insights. Whether through blog posts, newsletters, or social media, good public technical writing can open doors, create connections, and establish a lasting presence in the tech community.

Subscribe now

Articles I enjoyed this week

• Transform Your Codebase to Intuitive Diagrams in a Few Seconds by The Master of Diagrams himself Saurabh Dashora

• System Design Simplified: A Beginner's Guide to Everything You Need to Know (Part 11.1) by Lorenzo Bradanini

• The Architecture That Gets You Here Won’t Take You There by Raul Junco

To make good decisions when designing a system, a solid understanding of the key technologies required to build such a platform is essential.

3 Core Technologies Behind Real-Time Communication Apps

Building a real-time communication platform requires more than just a sleek UI and scalable infrastructure. At its core, such an application relies on key technologies that enable instant messaging, seamless API interactions, and high-quality voice and video calls. While many developers are familiar with REST APIs and basic WebSockets, fewer have worked with the powerful protocols that make these platforms truly fast and scalable.

In this article, I want to highlight three essential but often overlooked technologies: WebSockets, gRPC, and WebRTC. These are the foundation of a Discord clone, yet many engineers,especially those new to system design,may not have had the chance to work with them in depth. By understanding their roles, strengths, and trade-offs, you can better design and optimize real-time applications.

Let’s dive into each of these technologies and explore why they are essential for a modern Discord clone.

1. WebSockets – Enabling Real-Time Messaging

At the heart of any instant messaging system lies WebSockets, a protocol designed for persistent, two-way communication between clients and servers. Unlike traditional HTTP, which follows a request-response model, WebSockets establish a continuous connection, allowing messages to flow in real time without the overhead of repeatedly opening new connections.

Why WebSockets Matter

WebSockets are particularly important for chat applications, where real-time message delivery is essential. With WebSockets:

• A client receives messages instantly rather than polling the server for updates.

• Users see presence indicators (e.g., "typing…" or "online now") with minimal delay.

• Event-driven interactions, such as notifications or real-time status updates, become seamless.

How They Work

A WebSocket connection begins as an HTTP request, but instead of closing after a response, it upgrades to a persistent, bidirectional connection. This allows both the client and server to send and receive messages at any time.

While WebSockets are powerful, they require careful handling of reconnections, message ordering, and scaling across multiple servers. That’s where additional technologies come in.

2. gRPC – Efficient API Communication for a Discord Clone

While WebSockets handle real-time interactions, a Discord clone still needs a reliable way to serve structured API requests, fetching message history, managing user data, handling authentication, and more. Many applications default to RESTful APIs with JSON payloads, but a more efficient alternative exists: gRPC (gRPC Remote Procedure Call).

What Makes gRPC Different?

gRPC is a modern RPC framework built on HTTP/2, offering several advantages over REST APIs:

• Binary data over Protobuf – Unlike JSON, which is text-based and verbose, gRPC uses Protocol Buffers (Protobuf), a compact and efficient binary format.

• Multiplexing – HTTP/2 allows multiple requests to be sent and received simultaneously over a single connection, reducing latency.

• Built-in streaming – gRPC natively supports bidirectional streaming, making it a powerful choice for live updates.

• Strong typing and auto-generated code – Protobuf enforces strict data contracts and generates client and server code automatically, reducing errors and improving maintainability.

Why gRPC Over REST?

For a Discord clone, gRPC offers clear benefits in terms of speed and efficiency, especially when handling high-throughput API calls. For example:

• Fetching thousands of messages in a channel is significantly faster with gRPC’s binary format and multiplexed requests.

• Streaming capabilities allow efficient delivery of real-time updates without requiring a dedicated WebSocket for every API call.

• Strong typing reduces the risk of API contract mismatches between services.

However, gRPC isn’t always the right choice for public APIs or third-party integrations, where REST and JSON remain more universally supported. But for internal service-to-service communication, it’s a game-changer.

3. WebRTC – Powering Real-Time Voice and Video Calls

A real-time communication platform wouldn’t be complete without voice and video capabilities. This is where WebRTC (Web Real-Time Communication) comes in. Unlike WebSockets and gRPC, which focus on messaging and data exchange, WebRTC is specifically designed for low-latency, peer-to-peer audio and video communication.

Why WebRTC Is Essential

WebRTC enables direct media streaming between users, reducing the need for centralized servers to process and relay audio/video data. This results in:

• Lower latency – Avoiding unnecessary hops through a backend server keeps voice and video lag to a minimum.

• Reduced server costs – Unlike traditional VoIP systems, WebRTC establishes peer-to-peer connections whenever possible.

• Built-in NAT traversal – WebRTC includes mechanisms to work around firewalls and NAT restrictions, making it easier to establish connections even in restrictive network environments.

How WebRTC Works

WebRTC sessions typically involve three key components:

1. Signaling – Before a direct connection is established, WebRTC relies on a signaling process (often using WebSockets or gRPC) to exchange connection details.

2. STUN/TURN Servers – These help devices discover their public IP addresses and relay data when direct peer-to-peer connections are not possible.

3. Peer-to-Peer Streaming – Once a connection is established, audio and video streams flow directly between users with minimal delay.

WebRTC is what makes Discord’s voice channels feel so responsive, even when hundreds of users are connected. It’s also the technology behind many modern video conferencing platforms.

Bringing It All Together

Building a Discord clone isn’t just about writing code,it’s about choosing the right technologies to deliver an experience that feels instantaneous and seamless. WebSockets, gRPC, and WebRTC each play a critical role:

• WebSockets enable persistent, bidirectional communication for messaging and live updates.

• gRPC provides a fast, efficient way to handle structured API requests and backend communication.

• WebRTC powers low-latency voice and video calls through peer-to-peer streaming.

Each of these technologies is powerful on its own, but together they form the backbone of real-time applications like a Discord clone. Whether you’re a junior engineer exploring real-time communication for the first time or a senior architect refining your system design, understanding these technologies will give you the tools to build highly responsive and scalable applications.

In the next sections, we’ll dive deeper into each of these technologies, exploring their implementation details, best practices, and potential challenges.

Subscribe now

Articles I enjoyed this week

• The Shopify Checkout Architecture by Franco Fernando

• Coding Challenge #85 - Time Zone Converter by John Crickett

I love the saying scratch your own itch. Over the years, I’ve built small tools to make my life easier. Nothing groundbreaking, but each of them taught me something valuable. Side projects, big or small, are an incredible way to learn. Whether it’s a basic open-source contribution, a command-line tool to streamline your development workflow, or even a small web app, everything you build reinforces your skills. If you hold yourself to a certain quality standard, side projects become the perfect sandbox to experiment, fail, and improve without pressure.

Not everyone wants to start a side project from scratch, and that’s fine. Open-source software (OSS) projects are an excellent alternative. Find a project you like, look for “help wanted” or “good first issue” tags, and contribute. If you’re comfortable, propose a new feature, a utility, or even write tests to improve an existing codebase.

Side projects aren’t just for entrepreneurs. You don’t need to launch a startup or aim for the next big SaaS product to benefit from them. If you’re thinking about changing jobs or expanding your expertise, a well-documented side project can serve as a portfolio that showcases your skills in a way no resume can. It’s also an opportunity to familiarize yourself with technologies outside your day job without the constraints of a corporate environment.

I say all this as someone who never truly built a portfolio of side projects, and I regret it. If you’re in the same boat, start now. You won’t regret having something tangible to show for your efforts.

Subscribe now

Different Types of Side Projects and How to Leverage Them

1. Create a Product That Can Be Sold

Some developers turn their side projects into revenue-generating products. This doesn’t mean you need to quit your job and become a full-time entrepreneur, but building something that others find valuable can be an interesting challenge. It could be a SaaS tool, a mobile app, or even a paid Notion template. Even if it never turns into a full-fledged business, launching a product forces you to think about user experience, scalability, and marketing, skills that are valuable even in a traditional job.

2. Contribute to Open-Source Software

If starting from scratch feels daunting, contributing to open-source software is one of the best ways to sharpen your skills. It exposes you to real-world codebases, best practices, and collaboration with experienced developers. Many OSS projects welcome contributions of all sizes, from fixing bugs to improving documentation to adding new features. Your contributions not only help the community but also build up your reputation in the industry.

3. Build a Tool for Yourself

Sometimes the best side projects are the ones you wish already existed. Maybe you need a command-line tool to quickly switch environments, a script to automate a boring task, or a browser extension that streamlines your workflow. These projects may never turn into products, but they serve a practical purpose and often teach you a lot along the way. Plus, if they’re useful to you, chances are they’ll be useful to others.

4. Experiment with New Technologies

If you’ve been meaning to learn a new programming language, cloud platform, or framework, a side project is the best way to do it. Want to play with IoT? Build a smart home automation project. Curious about mesh networks? Try setting one up and see how it works. The key is to make your learning hands-on, tutorials are great, but nothing beats solving a real problem.

Overcoming Common Challenges

One of the biggest obstacles to starting (and finishing) a side project is time. Between work, life, and other commitments, it’s easy to let a side project slip. The key is to set realistic expectations. A side project doesn’t need to be an immediate success; it just needs to keep moving forward.

Another challenge is motivation. If you start a project purely for career benefits, you might lose interest quickly. That’s why it’s important to pick something that genuinely excites you. Whether it’s a problem you want to solve, a technology you want to explore, or just a creative outlet, passion will keep you going.

Finally, perfectionism can be paralyzing. Many developers hesitate to share their work because they think it’s not good enough. But side projects are supposed to be messy. The best way to learn is to put something out there, get feedback, and improve over time.

Balancing Side Projects with Work and Life

A common concern is how to balance side projects with a full-time job and personal life. Here are a few ways to make it work:

• Set small, achievable goals. Instead of aiming for a fully completed project, break it into tiny milestones that you can tackle in short sessions.

• Make it a habit. Even dedicating just 30 minutes a few times a week can add up over time.

• Work on things that energize you. A good side project shouldn’t feel like extra work—it should be something you look forward to.

• Take breaks when needed. Avoid burnout by recognizing when you need to step away. It’s okay to pause and return when you feel refreshed.

• Don’t feel guilty for taking time off. If you want to spend a weekend playing video games, traveling, or just relaxing with friends and family, do it. Side projects should be fulfilling, not a source of pressure.

A common concern is how to balance side projects with a full-time job and personal life. Here are a few ways to make it work:

• Set small, achievable goals. Instead of aiming for a fully completed project, break it into tiny milestones that you can tackle in short sessions.

• Make it a habit. Even dedicating just 30 minutes a few times a week can add up over time.

• Work on things that energize you. A good side project shouldn’t feel like extra work—it should be something you look forward to.

• Take breaks when needed. Avoid burnout by recognizing when you need to step away. It’s okay to pause and return when you feel refreshed.

Showcasing and Promoting Your Work

A side project is only as valuable as its visibility. If no one knows about it, it won’t have much impact. Here’s how to make sure your efforts don’t go unnoticed:

• Document your work. Keep a README file updated, write about your process, and explain your decisions.

• Use GitHub effectively. Keep your repositories organized, use meaningful commit messages, and make your project approachable for others.

• Share your journey. Post updates on LinkedIn, Twitter, or a personal blog. People love following the progress of interesting projects.

• Engage with communities. Platforms like Reddit, Dev.to, and Hacker News can be great places to share what you’re working on and get valuable feedback.

• Showcase it in job interviews. A strong side project can be a talking point that demonstrates your technical ability and initiative better than a resume alone.

How to Make the Most of Your Side Projects and OSS Contributions

1. Keep Your Scope Realistic – Start small. A tool that automates a tedious task is a great first step. Avoid projects so large that they become overwhelming.

2. Treat It Like Production Code – Use version control, write documentation, and follow best practices. The closer it is to real-world standards, the more valuable it becomes for learning and showcasing your skills.

3. Track Your Progress – Maintain a simple log or portfolio of what you’ve built. Even if a project isn’t finished, documenting what you learned from it makes a difference.

4. Engage with the Community – Contribute to OSS, ask for feedback, and learn from others. Seeing how experienced maintainers handle issues and PRs is an education in itself.

5. Know When to Move On – Not every side project needs to be maintained forever. If you’ve learned what you wanted, it’s okay to move on to something new.

You don’t need to launch a business to benefit from side projects. You just need to start.

Subscribe now

Articles I enjoyed this week

• System Design Simplified: A Beginner's Guide to Everything You Need to Know (Part 9.2) by Lorenzo Bradanini

• How Do Websockets Work ✨ by Neo Kim

• I used to think testing in production was a bad joke. I was wrong. by Raul Junco

In a previous article of this series, we explored the high-level design of the system, outlining its key components and interactions. Now, we shift our focus to the backend architecture, ensuring that we have a solid foundation before we start coding. A well-defined architecture serves as a battle plan, helping to avoid unnecessary complexity, improve maintainability, and facilitate future scalability.

In this article, we will explore the Onion Architecture and how it is applied within a modular monolith. By progressively drilling down from a high-level black box to detailed module structures, we ensure a clear separation of concerns and a scalable design.

All the diagram in the article are just an example. When designing a solution they should live and evolve. Since I want you to be able to reproduce this kind of documentation for your project I have added the PlantUML code of each diagram.

Subscribe now

High-Level Black Box View

At the highest level, the system consists of two major components:

• Frontend: A React-based web application that communicates with the backend.

• Backend: A Spring Boot application handling all business logic and data persistence.

Diagram:

@startuml
package "System" {
    [Frontend] --> [Backend]
}
@enduml

Backend Architecture Drill-Down

Black Box View

The backend follows a modular monolith approach, meaning it consists of multiple independent modules while sharing a common codebase. This design promotes maintainability and scalability without the complexity of microservices.

Backend Modules:

1. User Management (Handles authentication, profiles, and permissions)

2. Messaging (Manages chat and real-time communication)

3. Channel Management (Organizes conversations and groups)

4. Notification Service (Delivers push and in-app notifications)

5. Media Processing (Handles file uploads, storage, and playback)

Modules communicate via synchronous REST APIs and asynchronous messaging (Azure Event Hubs) where necessary.

Black Box Diagram: Modular Monolith with Modules

@startuml
scale 1.2

package "Backend (Modular Monolith)" {
    package "User Management Module" {
    }
    package "Messaging Module" {
    }
    package "Channel Management Module" {
    }
    package "Notification Service Module" {
    }
    package "Media Processing Module" {
    }
}
"User Management Module" -[hidden]d-> "Messaging Module"

"Channel Management Module" -[hidden]d-> "Messaging Module"

"User Management Module" -[-> "Messaging Module" : "REST API"]
"Messaging Module" -[-> "Notification Service Module" : "Event Hub"]
"Channel Management Module" -[-> "Messaging Module" : "REST API"]
"User Management Module" -[-> "Channel Management Module" : "REST API"]
"Media Processing Module" -[-> "Messaging Module" : "Event Hub"]
@enduml

Each module is responsible for a distinct business function, ensuring a clear separation of concerns.

White Box View

Within each module, we apply Onion Architecture, structuring the internals into concentric layers that enforce dependency rules.

Onion Architecture Layers:

1. Core Layer (Domain): Contains domain models and business rules.

2. Application Layer: Defines use cases and orchestrates business logic.

3. Infrastructure Layer: Implements repositories, external integrations, and APIs.

Each module follows this layered approach to maintain a clean architecture.

White Box Diagram: Internal Structure of Modules with Onion Architecture

@startuml
scale 1.2

package "User Management Module" {
    package "Core Layer" {
        class User
        class Role
        class Permission
    }
    package "Application Layer" {
        class UserService
        class AuthService
    }
    package "Infrastructure Layer" {
        class UserRepository
        class AuthProvider
    }
}

package "Messaging Module" {
    package "Core Layer" {
        class Message
        class Conversation
    }
    package "Application Layer" {
        class MessagingService
    }
    package "Infrastructure Layer" {
        class ChatRepository
    }
}

@enduml

This white box view reveals the internal structure of each module, showing how classes interact within layers while adhering to the Onion Architecture principles.

Why Use Onion Architecture in a Modular Monolith?

• Separation of Concerns: Business logic remains independent of frameworks.

• Decoupled Dependencies: Core business logic does not depend on external services.

• Explicit Boundaries: Communication between layers follows well-defined interfaces.

• Maintainability: Changes in external technologies don’t impact the core.

• Scalability: Modules can be extracted into microservices if needed later.

• Testability: Domain logic can be tested in isolation without external dependencies.

This structure ensures that the backend remains well-organized, scalable, and adaptable while leveraging Azure technologies for storage, authentication, and messaging.

As said before these diagrams could be incomplete at the moment but they give an idea of what does it mean do decide the main software architecture and document it.

Let me know if you think I should go deeper, otherwise we will proceed with the next topics: some detail about the technology selection and the deployment view.

Subscribe now

Articles I enjoyed this week

• Organizational Skills Beat Algorithmic Wizardry by James Hague

• Coding Challenge #84 - Mandelbrot Set Explorer by John Crickett

• How (not to) fail a coding interview by Franco Fernando

Fear as a Business Model

The bigger the company, the more terrified it is of making the "wrong" IT decision. So, instead of empowering teams to build expertise and take control of their technology, they do the safest thing: throw money at a well-known vendor.

• Open source? Too risky. "What if there’s no support?" (As if paid support has ever magically fixed a production outage at 2 AM.)

• In-house expertise? Too dangerous. "What if they leave?" (Better to rely on expensive consultants who will never truly transfer knowledge.)

• Flexibility? Too unpredictable. "What if something goes wrong?" (Better to be locked into an outdated product for the next decade.)

And when things inevitably go south, guess what? There’s always someone to blame the external vendor, the consultant, the software itself. Never the people who made the decision.

Subscribe now

The Middle Manager’s Best Friend: Expensive Software

For middle managers who don't understand tech but need to "own" an initiative, commercial software is a godsend.

1. They buy it. (Big budgets make them look important.)

2. They don't have to manage it. (That's the vendor's problem.)

3. They have a built-in scapegoat. ("The tool isn't working, let’s escalate!")

It’s the perfect cycle. They’re not measured on results just on whether they purchased the “best” solution. Bonus points if the product comes with an army of consultants who will bill triple the cost of an internal team while delivering half the results.

Oracle DBMS: The Default Choice for No Reason

And if there’s one product that perfectly represents this mindset, it’s Oracle DBMS.

It doesn’t matter if the company’s workload could run just fine on PostgreSQL, MySQL, or even a managed cloud database. If it’s enterprise IT, Oracle must be considered. Why?

• It’s expensive. (And expensive means "serious.")

• It comes with premium support. (Which mostly involves escalating tickets until you give up.)

• It locks you in forever. (Try migrating off Oracle and see how much fun you have.)

Many enterprises don’t even question whether they need Oracle. It’s just assumed to be the right choice because that’s what other big companies do. It’s the IT equivalent of buying a Ferrari to drive to the grocery store completely unnecessary, but it makes people feel important.

And when the licensing costs spiral out of control? "Oh well, it’s Oracle. What can we do?"

This is why so many companies are now scrambling to escape Oracle’s grip after spending years and millions pretending that nothing else could possibly work.

Why Build Knowledge When You Can Overpay for Consultants?

Take SAP as a prime example. Instead of building an internal team that actually understands the platform, many enterprises happily pay external consultants three times more than an in-house expert would cost. Why?

• If something breaks, it’s the consultant’s fault.

• If things are slow, it’s the system’s fault.

• If budgets spiral out of control, "this is just how enterprise IT works."

Meanwhile, those same consultants ensure the company remains dependent on them by never fully documenting anything, keeping just enough critical knowledge in their own hands.

Vendor Lock-in: The Gift That Keeps on Taking

And let’s not forget the ultimate enterprise IT failure: vendor lock-in. The moment you adopt some obscure functionality that only works with a single vendor, you're doomed. Need to migrate later? Good luck! The cost and complexity will be so absurd that even suggesting a change will get you laughed out of the room.

Looking at you, Lotus Notes. A graveyard of unreadable archives, broken workflows, and companies still trying to escape your clutches decades later.

The IT Illusion Continues

The cycle keeps going because it benefits the wrong people. Enterprises spend billions not on better technology, but on safe decisions. IT should be about agility, adaptability, and ownership but in too many places, it's just a blame game wrapped in a fat invoice.

And the best part? When the same company that swore open source was too risky ends up migrating to Kubernetes, embracing Linux, and using PostgreSQL all after spending years and millions fighting against them.

Because nothing says "enterprise IT strategy" like paying extra to do what should have been obvious from the start.

Breaking the Cycle: How to Convince Management to Consider Alternatives

Challenging the status quo in enterprise IT isn’t easy. The fear-driven mindset, the love for big-name vendors, and the obsession with “safe” decisions make it difficult to push for open-source or cost-effective solutions. But it’s not impossible. Here’s how you can start shifting the conversation:

1. Speak Their Language: Cost and Risk Reduction

Management won’t care that PostgreSQL is technically superior to Oracle, but they will care about licensing cost savings and reduced vendor dependency. Instead of arguing about tech specs, frame the discussion around:

• How much money the company could save over 3–5 years.

• The hidden costs of vendor lock-in and migration difficulties.

• How avoiding proprietary dependencies makes the company more agile.

2. Leverage Success Stories

No one wants to be the first to take a risk, but they’re happy to follow if others have succeeded. Gather case studies of major companies that have successfully adopted open-source alternatives:

• Netflix, Uber, and Twitter running on open-source databases.

• Large financial institutions moving away from Oracle or SAP.

• Governments adopting Linux and open-source stacks to reduce costs.

Show that open source isn’t just for startups it’s a strategic move even for big players.

3. Start Small: Pilot Projects and Low-Risk Adoption

Instead of proposing a full-scale migration, suggest a pilot project using an open-source or alternative tool. For example:

• Deploy a new application on PostgreSQL instead of Oracle.

• Run a non-critical workload on an open-source solution.

• Implement a hybrid approach where the company can compare results side-by-side.

Once leadership sees it working without disaster, they’ll be more open to expanding it.

4. Expose the Myth of Enterprise Support

A key argument against open source is "we need enterprise support." But in reality:

• Many "supported" enterprise products have horrendous support experiences.

• Open-source solutions often have commercial support options (e.g., Red Hat, Percona, HashiCorp).

• Internal expertise is often more effective than waiting on vendor responses.

Show them real-world examples where companies got burned by expensive “support” contracts that delivered little value.

5. Demonstrate the Long-Term Strategic Advantage

Proprietary software locks you into a single vendor’s roadmap, while open-source tools give companies the flexibility to adapt and evolve. Position alternatives as strategic investments rather than just cost-cutting measures:

• Avoiding licensing audits and compliance headaches.

• Being able to scale or pivot without waiting for vendor updates.

• Hiring from a broader talent pool (many engineers prefer working with modern, open tools).

6. Make It About Business, Not IT

At the end of the day, management cares about business outcomes, not technology choices. Focus your arguments on:

• Faster time to market.

• Cost efficiency and budget flexibility.

• Competitive advantage by avoiding rigid, outdated enterprise solutions.

The more you align your pitch with business goals, the harder it will be for them to ignore.

Enterprise IT’s love affair with expensive, bloated software won’t end overnight. But by shifting the conversation, showing real-world successes, and making incremental changes, professionals can help their organizations move toward smarter, more flexible, and cost-effective solutions.

And who knows maybe one day, we’ll look back at Oracle DBMS, SAP consultants, and Lotus Notes the way we now look at dial-up internet: a necessary evil of the past that we’re glad to have moved on from.

Articles I enjoyed this week

• 4 Challenges of Distributed Systems - And Possible Solutions by Saurabh Dashora

• What Works in a Monolith Can Break a Microservice by Raul Junco

We focus on the internal design of the system, ensuring that each component serves its purpose efficiently and integrates seamlessly with others. At this stage, we do not discuss infrastructure aspects such as cloud deployment, load balancing, or CI/CD pipelines in depth; these will be addressed in a later chapter.

There is anyway a really important aspect of the platform that we need to consider. As we discussed in the third installment of this series, the constraint chapter, we opted for a cloud solution instead of on-prem or VPS.

From the technical constraints chapter

Decision Point: Given the need for scalability and low upfront cost for a Discord clone, cloud deployment is the preferred option.

Justification: Cloud infrastructure allows us to leverage auto-scaling, managed services, and global CDNs to minimize latency and optimize costs.

The cloud provider of choice for our example is MS Azure. Lately, I'm working a lot with this platform, and designing this system is a good way to practice a little more.

The components described in this chapter will, when possible, leverage the capabilities of MS Azure. It doesn't make any sense to deploy an application using a cloud provider and implementing everything custom. At least not at the beginning. There is always time to find out that we are in an edge case in terms of performance or specific functionality, but these kinds of problems, even if difficult to solve, are normally a consequence of a successful launch of an application.

So let's hope we will end up with one of these "standard cloud component" kinds of problems. The three major cloud providers Azure, AWS, and GCP all offer equivalent tools to design and implement our Discord clone example application. In case you want to follow my structure with another cloud provider, please post your component list of choice in the comments.

Subscribe now

Core Components Overview

A well-designed system is composed of clearly defined components, each responsible for specific functionality. In our practical example, we have chosen specific technologies to implement these components while following a modular monolith architectural approach. There are several distinct component but It would be extremely pretentious to design an example app using a Microservice architecture. The key system components include:

• Client Applications – Interfaces through which users interact with the system.

• API Gateway – Centralized entry point for client requests.

• Authentication & Authorization Service – Manages user identity and permissions.

• Real-Time Messaging Service – Handles real-time communication.

• User & Channel Management Service – Maintains user data and communication channels.

• Media Processing Service – Manages audio and video streaming.

• Storage Services – Handles persistent and ephemeral data.

• Notification Service – Sends real-time notifications.

• Analytics & Monitoring Service – Collects and processes system metrics.

Each of these components is designed with scalability, maintainability, and performance in mind. The golas and constraints were decided in the previous chapters.

Client Applications

Client applications provide the interface for end users to interact with the system. In our practical example, we defined some constraint in Chapter 3.1 about and those lead me to chose a web-only client using a Typescript framework. To challange my knowledge I chosed React. It is a major framework in the landscape and it can for sure cover any requirement I could have in term of UI. The client will communicate with the backend via REST and WebSocket APIs.

Responsibilities:

• Display user interface and handle user interactions.

• Communicate with backend services through API requests.

• Maintain session state and caching for performance optimization.

API Gateway

The API Gateway acts as the single entry point for all client requests, handling routing, load balancing, and security enforcement.

Responsibilities:

• Forward requests to appropriate backend services.

• Implement rate limiting and security policies.

• Handle authentication tokens and request validation.

As defined in the constraints , we will use Azure API Management as our API Gateway solution, ensuring a scalable and secure request-handling mechanism.

Authentication & Authorization Service

This service is responsible for user authentication, session management, and role-based access control.

Responsibilities:

• Authenticate users using OAuth2 and JWT.

• Manage permissions and access control lists (ACLs).

• Support third-party authentication (e.g., Google, GitHub login).

In our practical example, we have chosen Azure Active Directory (Azure AD) as our identity provider, integrating it with the API Gateway and other backend services.

Backend Service

The backend is responsible for handling business logic and processing client requests.As I said in the past I am a Java guy. Lately I'm using more Quarkus and "standard JEE" but my home base for backend with Java is still Spring Boot, so this is the backend framework of choice.

Responsibilities:

• Expose REST and WebSocket endpoints.

• Handle business logic for messaging, user management, and channels.

• Interact with databases, messaging systems, and external services.

Spring Boot was chosen due to its extensive ecosystem, strong community support, and seamless integration with other Java-based tools and frameworks. But mostly as said it is the Framework that I know best.

Real-Time Messaging Service

The messaging service handles the real-time exchange of messages between users, ensuring low latency and high throughput.

Responsibilities:

• Manage WebSocket connections for live messaging.

• Implement message delivery guarantees (at-least-once, at-most-once, exactly-once).

• Support presence and typing indicators.

As defined in the constraints , we will use Azure Event Hubs for event-driven communication, ensuring scalability and resilience in message delivery. This is another example where the cloud provider offer already an out of the box solution. My experience will make me lean more in the direction of Apache Kafka or Rabbit MQ for simplicity but Azure Event Hub dos exactly what we need without the necessity of managing the installation ourself.

User & Channel Management Service

This service is responsible for maintaining user profiles and managing communication channels.

Responsibilities:

• Store and retrieve user profile information.

• Manage chat rooms, groups, and user membership.

• Provide search and discovery features for channels.

I generally prefer to use Relational database when I can. I'm a big fan of DDD but I know the struggle of designing aggregates that can be managed easily in the real world. This part of the application will for sure need some hierarchical structure and relation between stored data objects. For this scenario relational databases are a straight forward choice for me.

We will use Azure SQL Database as our relational database for structured data storage. This choice provides a fully managed, scalable solution with built-in high availability, automatic backups, and advanced security features. Compared to PostgreSQL and MySQL, Azure SQL Database offers seamless integration with other Azure services, supports serverless compute and hyperscale storage, and includes intelligent performance tuning capabilities. While PostgreSQL is known for its advanced indexing and JSON support, and MySQL for its widespread adoption and simplicity, Azure SQL Database provides a balanced option optimized for enterprise-grade workloads in an Azure-native environment.

Storage Services

Storage services handle both persistent and temporary data storage needs.

Responsibilities:

• Store chat messages and media files.

• Maintain ephemeral storage for temporary messages.

• Provide backup and disaster recovery mechanisms.

The second major database system. After users data channels and so on we need a place to persist the messages and the files exchanged.

For file storage, we will use Azure Blob Storage, which provides a highly available, durable, and scalable solution for unstructured data. This service is ideal for storing chat media such as images, voice messages, and attachments. It supports automatic replication, ensuring data resilience, and integrates seamlessly with other Azure services, such as Azure Content Delivery Network (CDN), to optimize content delivery performance. Given the need for efficient media storage and retrieval in our system, Azure Blob Storage aligns well with our requirements for scalability and reliability.

Notification Service

This service ensures users receive notifications for relevant events.

Responsibilities:

• Send push notifications to mobile and web clients.

• Deliver email and in-app notifications.

• Manage notification preferences for users.

We will integrate Azure Notification Hubs for push notifications, as it provides a scalable, cross-platform solution for sending notifications to various client applications. Azure Notification Hubs supports high-throughput push notifications, offering integration with both APNs (Apple Push Notification service) and FCM (Firebase Cloud Messaging), ensuring reliable and efficient message delivery. Its ability to segment audiences and personalize notifications makes it an ideal choice for our system's real-time engagement needs.

Analytics & Monitoring Service

To maintain system health and performance, we need a dedicated service for collecting metrics and logs.

Responsibilities:

• Track system performance (e.g., latency, request throughput).

• Monitor user engagement and feature usage.

• Provide alerts for anomalies and failures.

As defined in the constraints , we will use Azure Monitor for monitoring and Azure Monitor Metrics for performance tracking and visualization. Azure Monitor provides centralized logging, metric collection, and alerting capabilities, allowing us to gain real-time insights into application performance and system health. Compared to Prometheus and Grafana, which require self-managed setups and manual scaling, Azure Monitor offers a fully managed solution with seamless integration into the Azure ecosystem. It supports automatic scaling, intelligent anomaly detection, and deep integration with Azure security and compliance features, making it a robust choice for our monitoring needs.

Media Processing Service - OPTIONAL

This is an optional component that would be nice to implement but that can be kept out of an MVP.

I will anyway describe the responsibility and the choices made on the topic.

The media processing service enables users to send and receive voice and video streams, supporting live calls and media playback.

Responsibilities:

• Encode and decode audio/video streams.

• Provide media storage and retrieval.

• Enable live streaming and conferencing.

For media handling, we will leverage Azure Communication Services, which provides built-in support for real-time voice, video, and chat communication. This service is fully managed, allowing us to integrate seamless peer-to-peer and group communication capabilities without handling complex infrastructure. It supports SDKs for multiple platforms, ensuring interoperability between web and mobile clients. Additionally, Azure Communication Services integrates natively with other Azure solutions, improving scalability and security for our media processing requirements.

By defining these components in detail, we establish a solid foundation for our application’s design. In the next chapters, we will explore how these components interact within an infrastructure, addressing scalability, deployment strategies, and cloud considerations.

This chapter needs to describe the basic architecture of the software components themselves. I think though that it would make this chapter too long and convoluted. So stay tuned for part two of the design process, where we will do a component drill-down and decide what will be implemented where and the common structure of the applications.

Subscribe now

Articles I enjoyed this week

• Database sharding case study: PostgreSQL by Franco Fernando

• The C4 Model for Software Architecture by Simon Brown

• For the friends who speak Portuguese: Por que nos deixamos definir pela nossa profissão? by Paula Alves (@ondeestapaula)

• 8 Key Protocols You Can’t Ignore, 5 Steps to Understand How VPN Tunneling Works, and 7 Smart Strategies to Reduce Latency – Sketech #18 by Nina

Everything seemed to be on track until a discussion arose in a meeting about configuring Kafka topics across the on-prem and cloud environments. The decision was made to use a replication mechanism where services always publish to the "real" topic, while consumers retrieve messages from a "replica" topic.

This approach introduces a challenge: many services must now configure both the real and replica topics solely to enable testing. And here is where the debate began.

Subscribe now

What Are Architectural Antipatterns?

At the core of this issue is a fundamental question: should production configurations (or even code) be altered for the sake of tests? This is a classic antipattern.

In software architecture, an antipattern is a seemingly reasonable solution that, over time, introduces significant long-term problems. Unlike bad practices, which are poor choices from the outset, antipatterns often stem from well-intentioned decisions that gradually degrade system quality.

Example: Changing Production Code to Allow Tests

Returning to the Kafka configuration case, modifying production settings to facilitate testing introduces several risks:

• Increased complexity in production configurations, raising the likelihood of misconfigurations.

• Unintended dependencies between test environments and production settings, reducing flexibility and increasing operational risks.

• Higher maintenance burden, as teams must validate and manage multiple configuration paths.

A better approach would involve designing the system for testability from the outset, using techniques like dependency injection, feature toggles, or environment-specific overrides. This way, teams can ensure comprehensive test coverage without introducing risky production changes.

How Far Should We Go to Avoid Architectural Antipatterns?

Avoiding antipatterns is important, but rigidly rejecting anything that resembles one can lead to paralysis by analysis another form of inefficiency. Instead of focusing solely on avoidance, architects should prioritize pragmatic trade-offs.

1. Recognize Context and Constraints

Some antipatterns arise from real-world constraints such as tight deadlines, team expertise, or evolving business needs. For instance, a startup might allow minor code structure shortcuts to meet time-to-market goals, with the understanding that refactoring will follow. In contrast, a large enterprise with strict maintainability requirements may find the same decision introduces long-term risks.

Example Edge Case: A team working on a legacy system with poor test coverage might temporarily expose private methods to improve testability. While this could be justifiable as an interim step, making it a widespread practice would weaken system encapsulation over time.

2. Prioritize Long-Term Sustainability

Short-term workarounds can be tempting, but architects should advocate for decisions that minimize future refactoring costs. Strategies such as modular design, clear API boundaries, and automated testing help prevent antipatterns from spiraling out of control.

Example: Instead of modifying production code to accommodate tests, better alternatives include:

• Applying dependency inversion to support test mocks.

• Refactoring monolithic functions into smaller, testable components.

• Using test doubles (mocks, stubs, fakes) rather than exposing implementation details.

A real-world failure occurred when multiple teams needed to test private logic in a shared library. To accommodate testing, they made private methods public, creating unintended dependencies that later obstructed refactoring. A better approach would have been using a well-defined interface with dependency injection to facilitate testing without compromising design principles.

3. Balance Theory and Practice

Architectural purity isn’t always practical. The key is early detection and incremental refactoring identifying when an antipattern is forming and addressing it before it becomes an unmanageable problem.

Example: A team working with a legacy codebase might need to introduce an antipattern as a temporary workaround. Instead of rejecting the change outright, they could document it with a clear plan for future refactoring.

Edge Case: In highly regulated industries like finance or healthcare, exposing production logic for tests could introduce security and compliance risks. In such cases, alternative approaches such as testing through APIs or improving testability through refactoring should be prioritized.

Finding the Right Balance

Architectural antipatterns emerge when seemingly good solutions introduce long-term complexity (The good old temporary fix). While avoiding them is important, blindly chasing architectural perfection can be just as harmful. A skilled architect understands when to accept imperfection in service of progress and when to invest in long-term maintainability. Making pragmatic trade-offs, considering business constraints, and planning for refactoring are key to sustainable software architecture.

Subscribe now

Articles I enjoyed this week

• What is CDN? by Milan Milanović

• 4 API Design Mistakes You Must Avoid (Or Risk Total Chaos!), 6 Essential Kafka Concepts You Need to Master, Forward vs Reverse Proxies Explained in 7 Easy Steps! - Sketech #17 by Nina

Anticipation is not a magical talent; it is a skill forged through experience and exposure to diverse situations. When you’ve encountered enough varied challenges, patterns begin to emerge, allowing you to predict what might come next. This capacity to anticipate makes you better prepared and more adaptable in any given situation.

Subscribe now

Anticipation in Action

Let’s consider a scenario familiar to many engineers: a high-stakes production outage. When systems fail, there is no time for trial and error. Engineers who have honed their anticipation skills can quickly zero in on potential root causes. They know, for example, that a sudden spike in resource usage might point to a memory leak or an unoptimized query. They’ve seen these patterns before, and this familiarity enables them to act decisively and efficiently.

Similarly, when adopting a new tool or programming language, anticipation plays a key role. Experienced professionals know the common pitfalls poor documentation, unexpected edge cases, or integration challenges. They proactively seek out these potential issues, often asking the right questions before they even arise. This foresight accelerates the learning process and helps mitigate risks early.

How to Build Anticipation

Developing the ability to anticipate takes time, but it is achievable for anyone willing to put in the effort. Here are some strategies to help:

1. Broaden Your Exposure: Seek out diverse projects, teams, and technologies. The more varied your experiences, the more patterns you’ll recognize over time.

2. Learn from Others: Collaborate with colleagues, participate in code reviews, and engage in technical discussions. Learning from others’ experiences can give you insights you might not encounter on your own.

3. Reflect on Past Experiences: After completing a project or solving a problem, take time to reflect. What went well? What didn’t? Documenting these lessons helps you recognize similar situations in the future.

4. Stay Curious: Continuously learning keeps your skills sharp. Whether it’s a new framework, a different programming paradigm, or a deeper understanding of system internals, every new piece of knowledge adds to your ability to anticipate.

5. Simulate Scenarios: If you’re learning something new, actively think about possible failure points or challenges. Try to preemptively address them, even if you’ve never encountered them before.

The Experience Paradox

Here’s the catch: anticipation is largely a byproduct of experience. But you don’t need to wait decades to start building it. By being intentional about exposing yourself to challenges and learning from them, you can accelerate the process.

For those early in their careers, leverage the experiences of others. Ask questions like, “What should I watch out for?” or “What do you wish you had known when you started?” Senior colleagues, mentors, and even industry articles can provide a wealth of foresight.

Why It Matters

Anticipation doesn’t just make you a better engineer; it makes you a more reliable and effective team member. When you can foresee issues and take steps to address them, you reduce risks for your team and projects. This skill inspires trust and confidence among your peers and stakeholders, paving the way for career growth.

In a fast-paced, ever-evolving industry, the ability to anticipate is a superpower. It allows you to stay ahead of the curve, adapt to change, and deliver value consistently. While experience remains the foundation of anticipation, deliberate effort and curiosity can fast-track its development.

So, embrace new challenges, learn voraciously, and reflect deeply. The more you cultivate this skill, the better prepared you’ll be for whatever comes your way—because in the world of technology, the unexpected is always just around the corner.

Subscribe now

Articles I enjoyed this week

• How To Do Well in System Design Interviews? by Saurabh Dashora

• Space Complexity by Franco Fernando

• How API Pagination, Kafka Use Cases and Security Practices Solve Data Handling, Scalability and Protection Challenges Sketech #16 by Nina

Every little contribution help. If you want to help me produce this content you can do it here.

This year, by pure coincidence, I kept seeing ads on social media about digital drawing and painting.

I already own an iPad, which I bought last year with the intention of using it for note-taking. As you can imagine, that plan didn’t quite work out. However, I did purchase the Procreate app to experiment with digital drawing. Months went by, but those ads, combined with the fact that I already had the tools, nudged me to give digital drawing another try.

I have some experience with paper and ink pens, so I’m not starting from scratch. But saying I’m rusty would be a massive understatement.

I began by doodling some imaginary characters, and somehow, a strange “Forkman” emerged from my brain a roundish figure without arms and a trident for a head.

After this first attempt, I decided to challenge myself: draw Forkman from a 30-degree angle. I figured it would be a good way to get familiar with proportions, perspective, and overall drawing fundamentals.

Needless to say, it was a huge struggle. The proportions were off, but the hardest part was drawing the fork head at an angle. How much of each spike would be visible? How thick should I make them? How would one spike overlap the others?

It took several tries and even duct-taping three pens together as a makeshift model only to realize that what I drew didn’t make any sense. Not just because Forkman is an absurd doodle with shaky lines, but because the proportions and perspective I wanted to train were completely distorted.

After taking a day off and watching a couple of YouTube videos about drawing, I remembered the most basic technique: break down what you want to draw into simpler shapes.

So, I gave it a shot. First, I created a main rectangular parallelepiped at a 30-degree angle as the frame. Then, I carved out three smaller rectangular parallelepipeds for the spikes of the fork head.

Using this new framework, I redrew my figure. And, unsurprisingly, the results were much better. The drawing itself is still rough let’s call it “garbage with potential” but it has some sense of perspective now, even if it is still incomplete.

At the end of this adventure, one thing became crystal clear to me: I had completely overlooked a basic principle I use every day as a software engineer. Decomposing problems into smaller, manageable parts is second nature in my work. It’s effective; I know it works. So why didn’t I apply it here?

This realization started to take root in my mind, forming a fascinating parallel between drawing and problem-solving.

Subscribe now

Drawing and Coding: The Art of Simplifying Complexity

Artists and software engineers might seem worlds apart, but they share a common approach to managing complexity: breaking down the big picture into smaller, manageable parts. This similarity between figure drawing and the divide-and-conquer strategy in software engineering offers valuable lessons in both disciplines.

Decomposing Complexity: Drawing the Basics

When an artist begins a figure drawing, they don’t start with fine details. Instead, they decompose the figure into basic shapes an oval for the head, rectangles for the torso, cylinders for the limbs. These shapes form the foundational structure, helping the artist establish proportions and relationships between parts. Only once the foundation is correct do they add depth, texture, and detail.

Divide and Conquer in Software Engineering

Software engineers follow a similar strategy when tackling complex systems. Using the divide-and-conquer approach, they break down a large problem into smaller, independent components. For example, designing an e-commerce platform might involve splitting the system into modules like user authentication, product catalogs, shopping carts, and payment processing. Each module is developed and tested individually, with clearly defined boundaries ensuring the parts integrate smoothly.

The Key Parallel: Boundaries and Integration

Both disciplines rely on clearly defined boundaries to maintain focus and ensure integration. In drawing, boundaries between shapes prevent distortion, ensuring that the oval head connects properly to the rectangular torso. Similarly, in software, well-defined interfaces between components ensure that each module can work independently while still fitting seamlessly into the larger system.

Iterative Refinement

Another shared principle is iterative refinement. In drawing, rough shapes are progressively refined into detailed artwork. In software engineering, a system evolves through prototyping, testing, and continuous improvement.

By embracing these principles simplification, defined boundaries, and iterative refinement artists and engineers alike can transform overwhelming complexity into elegant results, whether on canvas (iPad for me) or in code.

Subscribe now

Articles I enjoyed this week

• How Traffic Management Tools, API Testing and CI/CD Streamline Modern Software Architecture - Sketech #15 by Nina

• Computer Science Papers Every Developer Should Read by Milan Milanović

• Event Sourcing is like Time traveling by Raul Junco

• A Comprehensive Guide to Database Sharding by Franco Fernando