Think of this, a feature ships to production. A security review happens afterwards, or a penetration test finds something, or worse, an incident report lands in your inbox.

The vulnerability is real. The fix is expensive. And somewhere in the conversation, someone says "we need to add security to this."

That phrase is the problem. Security isn't something you add to software. It's something you build into it from the beginning. The moment you're talking about adding security to something that already exists, you're already in damage control mode.

Secure by Design is a different mindset entirely whereby you define security requirements before you make architecture decisions. You understand the threat model before writing a single class. You identify and enforce business rules at the domain layer. All of these things comes with what engineering has to offer, not a layer that tops up what has been built already.

The CI/CD pipeline catches what human review misses. Every layer of the system is designed with an attacker's perspective in mind, not as an afterthought, but as a foundational requirement.

This isn't a security team's responsibility. It's an engineering team's responsibility. And it starts before the first pull request.

In this handbook, I'll take you through all you need to understand on how your engineering team can cultivate the discipline of having security in mind whilst designing.

Table of Contents

• Prerequisites

• What Secure by Design Actually Means

• Threat Modeling: Understanding Your Attack Surface Before You Build

• Security as a Business Rule

• Encryption Standards: The Organizational Decision

• Database Security

• CORS: The Boundary Your API Enforces

• Structured Logging and Field-Level Masking

• CI/CD Security Gates

• Microservices and Internal Service Security

• Data Privacy and Compliance as Engineering Requirements

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Building APIs and backend systems in any language or framework

• General software architecture concepts: layers, services, gateways

• What CI/CD pipelines are and how they work at a high level

• Basic understanding of what encryption and hashing mean

You don't need a security background. This article approaches every concept from an engineering and architecture perspective.

What Secure by Design Actually Means

Secure by Design isn't a checklist. It's not a set of tools you install. It's a way of thinking about software that treats security requirements the same way you treat functional requirements. In this mode of work, you treat your security requirements as things that must be satisfied before the system is considered complete.

Most teams treat security passively. Something breaks, something gets flagged, and something gets patched. The cycle repeats. The system accumulates technical security debt the same way it accumulates any other technical debt, just with higher stakes.

Secure by Design teams treat security proactively. Before a feature is built, the engineering team asks: what are the threats against this feature? Where is the data sensitive? What happens if an attacker controls this input? What is the blast radius if this component is compromised? The answers shape the architecture, not the other way around.

This produces fundamentally different systems. Not because the individual components are different, but because the design decisions at every layer reflect an understanding of what can go wrong.

Perfect instances are as follows :
The API gateway rate-limits by default because the design accounted for abuse.
The domain layer enforces business rules because the design identified where those rules belong.
The CI/CD pipeline catches secrets in code because the design included that gate from the start. etc

The cost of getting security right at design time is a fraction of the cost of trying to fix or manage it. And the cost of managing it is a fraction of the cost of a major incident. Its just a matter of time!

Threat Modeling: Understanding Your Attack Surface Before You Build

Threat modeling is the process of systematically identifying what can go wrong with a system before it's built. It's a formal engineering activity, not a security team exercise.

The goal is simple: understand who might attack your system, what they might want, how they might try to get it, and what the impact would be if they succeeded. With that understanding, you make deliberate design decisions that reduce the likelihood and impact of those attacks.

The Four Questions of Threat Modeling

1. What are we building?

This particular usecase starts by mapping the system. What are the components? How do they communicate? Where does data flow? Where are the trust boundaries, the points where data crosses from one context of trust to another?

A trust boundary exists between your API gateway and the internet, between your service layer and the database, and between your system and a third-party integration. Every trust boundary is a potential attack surface.

Here you have to draw the data flow, map every place where data enters the system, where it's stored, where it's processed, and where it leaves. This gives you a complete picture of what you're protecting.

2. What can go wrong?

In this usecase, you ask for each component and each data flow, what can an attacker do. Here comes STRIDE. This is an acronymn of laid down questions that helps fulfil this particular usecase.

• Spoofing: Can an attacker pretend to be someone they're not? Can they forge a token, impersonate a user, or claim an identity they don't own?

• Tampering: Can an attacker modify data in transit or at rest? Can they change a transaction amount, modify a callback payload, or alter a stored record?

• Repudiation: Can a user deny having performed an action? Are there sufficient audit logs to prove what happened, when, and by whom?Can we prove that a user performed am action on the system?

• Information Disclosure: Can an attacker learn something they shouldn't? Can they read another user's data, extract internal system information from error responses, or discover internal infrastructure details from stack traces?

• Denial of Service: Can an attacker prevent legitimate users from accessing the system? Can they exhaust resources, trigger expensive operations, or overwhelm the system with traffic?

• Elevation of Privilege: Can an attacker gain permissions they weren't granted? Can a regular user access admin functions, or can an external caller reach internal APIs?

3. What are we going to do about it?

For each identified threat, we decide on a countermeasure. Mitigate it by reducing the likelihood or impact. Transfer it by using a managed service that handles it. Accept it if the risk is genuinely low and the mitigation cost is too high. Eliminate it by changing the design so the threat no longer applies.

The decision is explicit and documented. Not implicit or assumed.It must be documented.

4. Did we do a good enough job?

After the system is built, verify that the countermeasures were actually implemented. Threat modeling is a living document, not a one-time exercise. When the system changes, the threat model must be revisited.

What Threat Modeling Produces

A threat model produces two things that are genuinely valuable: a list of security requirements that must be satisfied before the system ships, and an understanding of where the high-risk areas are, so engineering effort is focused correctly.

Without a threat model, security is applied uniformly and often superficially. Every component gets the same level of attention regardless of its actual risk level. With a threat model, you know which components are high-risk, which data flows are sensitive, and where the engineering effort should be concentrated.

Security as a Business Rule

Domain-Driven Design teaches us that business logic makes or breaks an application. The domain layer is where the rules that define the system's correctness live. Security requirements are business rules, and they belong in the domain layer alongside every other business rule.

A sales agent shouldn't be able to create a sale without confirmed coverage. That's a business rule. It belongs in the domain entity or domain service that creates sales, enforced at the point of creation, impossible to bypass from any layer above.

A payment shouldn't transition from pending to completed without going through the processing state. That's a business rule. It belongs in the Payment entity's state machine, enforced at the entity level, impossible to corrupt through the API or the infrastructure layer.

An account transfer shouldn't proceed if the source account is flagged for fraud review. That's both a business rule and a security requirement. It belongs in the domain service that orchestrates transfers, enforced before any money moves.

When security requirements are encoded as domain business rules, they can't be bypassed by calling the API directly, by using a different client, or by accessing the database through an ORM. The rule is enforced at the point where the domain object is created or its state is changed. Every path through the system hits the domain layer. The domain layer enforces the rule.

Value Objects strengthen this further. A Money value object that validates on construction means no invalid amount can ever exist in the domain. An AccountNumber value object that validates format and check digits means no malformed account number can enter the system. The validation isn't a controller check that can be skipped. It's an intrinsic property of the type itself.

This is the engineering mechanism for Secure by Design at the domain level: encode security requirements as constraints on domain types and domain operations, and make them impossible to bypass.

Encryption Standards: The Organizational Decision

One of the most dangerous security decisions in most organizations is the one that's not made: what encryption standard does the organization use?

When there is no organizational standard, every developer makes their own choice. One team uses AES-128. Another uses AES-256 with CBC mode. A third uses AES-256 with GCM mode. A fourth is still using MD5 for something.

Nobody intended for this to happen. It happened because nobody made the decision at the organizational level and enforced it.

The vulnerabilities that come from ad-hoc encryption choices are serious and often subtle. Padding oracle attacks exploit specific combinations of cipher mode and error handling. CBC mode with improper IV generation is vulnerable to attacks that GCM mode is not. Weak key lengths can be brute-forced. Exposing stack traces during encryption failures reveals internal implementation details that help attackers.

Every organization that handles sensitive data must make these decisions explicitly and enforce them as engineering standards:

1. Which Symmetric Encryption Algorithm and Mode?

Symmetric encryption uses the same key to encrypt and decrypt data. It is fast and efficient, making it the right choice for encrypting large amounts of data at rest or in transit.

AES-256 with GCM mode is the current standard for most applications. AES stands for Advanced Encryption Standard. The 256 refers to the key size in bits: usually a longer key means more possible combinations and a harder brute force attack.

GCM (Galois/Counter Mode) provides authenticated encryption, meaning it both encrypts the data and produces an authentication tag that detects whether the ciphertext has been tampered with. You get confidentiality and integrity in one operation.

CBC (Cipher Block Chaining) mode is still used but requires careful handling of initialization vectors (IVs) and message authentication codes (MACs) to achieve the same properties GCM provides natively. Getting this wrong opens the door to padding oracle attacks, where an attacker can decrypt data or forge ciphertext by carefully observing how the system responds to modified ciphertext.

2. Which Hashing Algorithm for Passwords?

Hashing is a one-way operation. You can't reverse a hash back into the original value. This is why you store a hash of a password, not the password itself. When a user logs in, you hash what they typed and compare it to the stored hash.

bcrypt, scrypt, and Argon2 are the current standards for password hashing. These algorithms are deliberately slow and computationally expensive, which makes brute force attacks impractical even when an attacker obtains the hash database.

SHA-256 isn't a password hashing algorithm. It's a general-purpose cryptographic hash function that is fast by design...and this is exactly what you don't want for passwords. An attacker can try billions of SHA-256 hashes per second on modern hardware.

MD5 isn't a hashing algorithm for anything sensitive. It was broken years ago and should never appear in any security-sensitive context. These aren't just my opinions. They're the product of cryptographic research and real-world attacks.

3. Which Asymmetric Algorithms for Signing and Key Exchange?

Asymmetric encryption uses a pair of keys: a public key that anyone can see and a private key that only you hold. Data encrypted with the public key can only be decrypted with the private key. A signature created with the private key can be verified by anyone with the public key.

Use RSA-2048 at a minimum for asymmetric operations. Use RS256 or ES256 for JWT signing in high-security contexts. RS256 uses RSA with SHA-256 for signing. ES256 uses Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve. EC keys are generally preferred over RSA at equivalent security levels because they produce smaller keys and signatures while providing the same cryptographic strength.

4. How Encryption is Delivered to Developers

The most important decision is that you don't implement encryption from scratch per project. Staff engineers build encryption utilities as internal packages or cloud functions. Then you can import and use them. You should never write the cryptographic primitives yourself. This eliminates an entire category of implementation failures at the source.

When encryption implementation is centralized, fixing a vulnerability means fixing it in one place. When it's scattered across every project, fixing a vulnerability means finding every implementation first, which is often impossible.

Database Security

The database is where the most sensitive data in most systems lives. It's also one of the most frequently misconfigured components in the entire stack.

SQL Injection

SQL injection is 25 years old. It has existed since 1998. It still appears in production systems because engineering standards aren't enforced.

The cause is always the same: string concatenation. A developer takes user input and glues it directly into a SQL string. The database can't distinguish between the query the developer intended and the query the attacker constructed.

-- developer intended this
SELECT * FROM users WHERE email = 'user@example.com'

-- attacker passes: anything@example.com' OR '1'='1
SELECT * FROM users WHERE email = 'anything@example.com' OR '1'='1'
-- returns every user in the table

The fix is parameterized queries or ORMs, always. The query structure is fixed. The values are passed separately. The database treats them as data, not as part of the query structure.

Static analysis in the CI/CD pipeline must flag raw SQL string concatenation. This is a zero-tolerance policy. Raw SQL strings with user input concatenated are never acceptable and must not reach production.

Principle of Least Privilege for Database Access

The application's database user should have exactly the permissions it needs and nothing more. A read-only reporting endpoint should connect as a user with SELECT permissions only. It shouldn't have INSERT, UPDATE, or DELETE. An API that only writes shouldn't have DROP TABLE permissions.

This limits the blast radius of a successful SQL injection or credential leak. If the application can only SELECT from specific tables, an attacker who compromises the database credentials can only SELECT from those tables. They can't DROP the database, INSERT false records, or UPDATE account balances.

This is a database provisioning decision that must be made explicitly for each application component and enforced at the infrastructure level.

All Database Connections Must Be Encrypted

Database connections must use TLS. An unencrypted database connection transmits query results in plaintext on the network. Any component between the application and the database that can observe network traffic can read every query result.

In cloud environments, services often communicate over internal networks that feel secure but are not. Encrypting database connections isn't optional.

Here's what enforcing TLS on a database connection looks like in practice:

final connection = await Connection.open(
  Endpoint(
    host: 'your-db-host.example.com',
    port: 5432,
    database: 'your_database',
    username: dbUser,
    password: dbPassword,
  ),
  settings: ConnectionSettings(
    sslMode: SslMode.require,
  ),
);

var connectionString =
    "Host=your-db-host.example.com;" +
    "Port=5432;" +
    "Database=your_database;" +
    "Username=db_user;" +
    "Password=db_password;" +
    "SSL Mode=Require;" +
    "Trust Server Certificate=false;";

await using var dataSource = NpgsqlDataSource.Create(connectionString);

Setting SSL Mode=Require means the connection will fail entirely if the database server doesn't support TLS. This is the correct posture. A connection that silently falls back to plaintext when TLS is unavailable provides no protection at all.

Database Credentials Must Live in Vaults

Database credentials must be fetched from a secrets manager at runtime. Not stored in configuration files, committed to version control, or hardcoded in connection strings.

Here's how runtime credential fetching works in practice:

final dbHost = Platform.environment['DB_HOST']!;
final dbUser = Platform.environment['DB_USER']!;
final dbPassword = Platform.environment['DB_PASSWORD']!;

final connection = await Connection.open(
  Endpoint(
    host: dbHost,
    database: 'your_database',
    username: dbUser,
    password: dbPassword,
  ),
  settings: ConnectionSettings(sslMode: SslMode.require),
);

builder.Configuration.AddAzureKeyVault(
    new Uri("https://your-vault.vault.azure.net/"),
    new DefaultAzureCredential()
);

var connectionString = builder.Configuration["DatabaseConnectionString"];

Connection pooling must also be properly controlled. An unbounded connection pool can exhaust the database server's available connections, taking it down for all tenants. Configure pool size deliberately:

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.ConnectionStringBuilder.MaxPoolSize = 20;
dataSourceBuilder.ConnectionStringBuilder.MinPoolSize = 5;
dataSourceBuilder.ConnectionStringBuilder.ConnectionIdleLifetime = 300;
await using var dataSource = dataSourceBuilder.Build();

Stored Procedures as a Parameterization Strategy

A stored procedure is a named, pre-compiled SQL block stored inside the database itself. Instead of sending a full SQL string from your application, you call the procedure by name and pass parameters separately.

Because the SQL structure is fixed inside the database and the parameters are always treated as data (never concatenated into the query string), stored procedures are resistant to SQL injection.

CREATE OR REPLACE PROCEDURE get_user_by_email(p_email VARCHAR(255))
LANGUAGE plpgsql
AS $$
BEGIN
    SELECT id, first_name, last_name, email
    FROM users
    WHERE email = p_email;
END;
$$;

public async Task<User?> FindUserByEmail(string email)
{
    await using var command = dataSource.CreateCommand("get_user_by_email");
    command.CommandType = CommandType.StoredProcedure;
    command.Parameters.AddWithValue("p_email", email);

    await using var reader = await command.ExecuteReaderAsync();
    if (await reader.ReadAsync())
    {
        return new User
        {
            Id = reader.GetGuid(0),
            FirstName = reader.GetString(1),
            LastName = reader.GetString(2),
            Email = reader.GetString(3)
        };
    }
    return null;
}

An attacker who passes ' OR '1'='1 as the email value gets exactly that string as the parameter. The database never interprets it as SQL syntax. The procedure only executes the fixed query defined at creation time. This is one of the reasons stored procedures remain a legitimate security tool, not just a performance optimization.

CORS: The Boundary Your API Enforces

Cross-Origin Resource Sharing is the browser security mechanism that controls which domains can make requests to your API from web pages.

The most common CORS misconfiguration in production is also the most dangerous: wildcard CORS.

Access-Control-Allow-Origin: *

This tells every browser that any web page on the entire internet can make authenticated requests to your API using that user's credentials. An attacker hosts a malicious web page, a user visits it, and the attacker's page can make requests to your API as that user.

In development, wildcard CORS is convenient. In production, it's a vulnerability.

Every production API must configure CORS with explicit allowed origins. Not wildcard patterns. Not *.yourapp.com. Explicit, enumerated domains that are allowed to make cross-origin requests.

Access-Control-Allow-Origin: https://app.yourproduct.com
Access-Control-Allow-Origin: https://admin.yourproduct.com

Domain matching must be exact. If the origin header doesn't match one of the explicitly allowed origins, the browser won't include the response.

The allowed methods and allowed headers must also be explicit. The default deny posture applies: if it's not explicitly allowed, it's not allowed.

This is a configuration decision made at the API gateway or the framework level. It applies uniformly to all API endpoints, not endpoint by endpoint where individual developers might misconfigure it.

Structured Logging and Field-Level Masking

Logging is one of the most overlooked security surfaces in most systems. Developers add log statements to help debug. Those log statements travel to a logging platform. That logging platform retains logs for months or years. Those logs contain whatever the developer thought was useful to log when they were debugging at 11pm during an incident.

The result is that production logs often contain information that shouldn't be shared. For example, full request and response bodies, authorization headers with bearer tokens, user IDs paired with sensitive operations, account numbers, and sometimes passwords in plaintext because someone logged the raw request body before validation ran.

Again, this isn't hypothetical. These are real patterns found in real production logging platforms.

The engineering control is field-level masking applied at the logging framework level. Sensitive fields are defined once in the logging configuration. The framework masks those fields automatically in every log statement, in every environment, regardless of what the developer puts in the log statement.

Sensitive fields that must never appear in logs include: passwords, tokens and authorization headers, full account numbers and card numbers, BVN and NIN, any national identifier, encryption keys and secrets, and full request bodies for endpoints that handle sensitive data.

The masking must be framework-level, not developer-level. If you add a log statement, you shouldn't have to remember to mask sensitive fields. The framework handles it. You'll just log whatever is useful for debugging. The framework produces a log entry where sensitive fields are replaced with masked values.

Here's what field-level masking looks like in practice:

class SecureLogger {
  final Logger _logger;

  static const _sensitiveKeys = {
    'password', 'authorization', 'token',
    'account_number', 'card_number', 'bvn', 'nin', 'secret', 'api_key',
  };

  SecureLogger(this._logger);

  void info(String message, {Map<String, dynamic>? data}) {
    _logger.info(message, _mask(data));
  }

  void error(String message, {Map<String, dynamic>? data, Object? error}) {
    _logger.error(message, _mask(data), error);
  }

  Map<String, dynamic>? _mask(Map<String, dynamic>? data) {
    if (data == null) return null;
    return data.map((key, value) {
      if (_sensitiveKeys.contains(key.toLowerCase())) {
        return MapEntry(key, '***MASKED***');
      }
      if (value is Map<String, dynamic>) return MapEntry(key, _mask(value));
      return MapEntry(key, value);
    });
  }
}

final logger = SecureLogger(Logger('PaymentService'));

logger.info('Processing payment', data: {
  'transaction_id': 'txn_001',
  'amount': 50000,
  'account_number': '0123456789',
  'authorization': 'Bearer eyJ...',
});

// output:
// Processing payment
// { transaction_id: txn_001, amount: 50000,
//   account_number: ***MASKED***, authorization: ***MASKED*** }

public class MaskSensitiveFieldsPolicy : IDestructuringPolicy
{
    private static readonly HashSet<string> SensitiveFields =
        new(StringComparer.OrdinalIgnoreCase)
        {
            "password", "authorization", "token", "account_number",
            "card_number", "bvn", "nin", "secret", "api_key"
        };

    public bool TryDestructure(
        object value,
        ILogEventPropertyValueFactory factory,
        out LogEventPropertyValue result)
    {
        if (value is not IDictionary<string, object> dict)
        {
            result = null!;
            return false;
        }

        var properties = dict.Select(kvp => new LogEventProperty(
            kvp.Key,
            SensitiveFields.Contains(kvp.Key)
                ? factory.CreatePropertyValue("***MASKED***")
                : factory.CreatePropertyValue(kvp.Value, true)));

        result = new StructureValue(properties);
        return true;
    }
}

Log.Logger = new LoggerConfiguration()
    .Destructure.With<MaskSensitiveFieldsPolicy>()
    .WriteTo.Console()
    .CreateLogger();

This applies in every environment without exception, not just production. Development logs are frequently exported to third-party logging platforms, and they're often searched by multiple team members. A developer who tests against a real account in development and logs the request body has put real user data into the logging platform where it doesn't belong.

CI/CD Security Gates

The CI/CD pipeline is the last automated gate before code reaches production. It's also one of the most consistently underused security controls in most engineering organizations.

Most pipelines run tests and check formatting. Security gates are the additional checks that catch the security-relevant issues that human code review consistently misses.

Secret Detection

Every push to every branch must be scanned for secrets. API keys, database passwords, private keys, connection strings with credentials embedded, and JWT secrets in configuration files.

Gitleaks is a free, open-source tool purpose-built for this. Here's how you integrate it into a GitHub Actions pipeline:

# .github/workflows/security.yml
name: Security Gates

on:
  push:
    branches: ["*"]
  pull_request:
    branches: ["*"]

jobs:
  secret-detection:
    name: Scan for secrets
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

When Gitleaks finds a secret, it fails the pipeline, outputs the exact file and line number, and blocks the merge. You'll need to remove the secret, rotate the credential (because it touched version control and must be considered compromised), and push a clean commit before the pipeline passes.

The scan must run on the full Git history, not just the latest commit. A secret added three commits ago and removed in the next is still in the repository history and should be treated as compromised.

Your organization should also have a defined response procedure: who's notified when a secret is detected, which credentials are rotated, and in what timeframe. Detection without response isn't a security control.

Static Analysis for Security

Static analysis tools analyze code for vulnerability patterns without running it. They catch raw SQL string concatenation, unsafe deserialization, hardcoded credentials, deprecated cryptographic functions, missing input validation, and dangerous function calls.

Semgrep is a free, open-source static analysis tool with a large library of security rules maintained by the security community. Here's how it fits into a pipeline:

  static-analysis:
    name: Static analysis
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: semgrep/semgrep-action@v1
        with:
          config: >-
            p/owasp-top-ten
            p/secrets
            p/sql-injection
        env:
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}

The p/owasp-top-ten ruleset catches patterns corresponding to OWASP Top 10 vulnerabilities. The p/sql-injection ruleset specifically flags string concatenation in database queries. When Semgrep finds a match, the pipeline fails and identifies the exact file, line, and rule that triggered. The code can't merge until the issue is resolved.

For .NET projects, Microsoft Security Code Analysis and Roslyn Analyzers provide similar capabilities integrated directly into the build process.

The rules must be configured deliberately. Not every warning represents an actual vulnerability. Your team will define which rules are blocking, which are advisory, and which are suppressed. This configuration is itself a security decision that must be reviewed periodically.

Dependency Vulnerability Scanning

Every dependency in the project is a potential attack surface. OWASP Dependency-Check is a free tool that scans project dependencies against the National Vulnerability Database (NVD) and flags known CVEs.

  dependency-scan:
    name: Dependency vulnerability scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: dependency-check/Dependency-Check_Action@main
        with:
          project: "your-project-name"
          path: "."
          format: "HTML"
          args: >
            --failOnCVSS 7
            --enableRetired

      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: dependency-check-report
          path: reports/

The --failOnCVSS 7 flag means the pipeline fails if any dependency has a known vulnerability with a CVSS score of 7 or higher. CVSS (Common Vulnerability Scoring System) scores range from 0 to 10. A score of 7 or above is considered high severity. You can adjust this threshold based on your risk tolerance.

For Node.js projects, npm audit provides similar functionality out of the box. For Dart projects, dart pub deps combined with a vulnerability database check covers the dependency surface.

Environment-Specific Configuration Validation

Before deploying to production, the pipeline must validate that the production configuration meets the required security standards. This isn't just checking that configuration files exist. It's actively asserting that specific security-critical settings are correct.

Here's what that validation looks like as a pipeline step:

  config-validation:
    name: Validate production configuration
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v3

      - name: Validate security configuration
        run: |
          if grep -r "debugEndpoint\|swagger-ui\|/debug" src/ --include="*.dart" --include="*.cs"; then
            echo "ERROR: Debug endpoints found in production build"
            exit 1
          fi

          if grep -r "AllowAnyOrigin\|\*" config/ --include="*.yaml" --include="*.json"; then
            echo "ERROR: Wildcard CORS configuration detected"
            exit 1
          fi

          if grep -rE "(password|secret|key)\s*=\s*['\"][^$\{]" config/ --include="*.yaml" --include="*.json"; then
            echo "ERROR: Hardcoded credentials detected in configuration"
            exit 1
          fi

          if grep -r "showStackTrace.*true\|expose_errors.*true" config/ --include="*.yaml"; then
            echo "ERROR: Stack trace exposure enabled in production config"
            exit 1
          fi

This script runs before every production deployment. Debug endpoints, wildcard CORS, hardcoded credentials, and stack trace exposure are all blocking failures. The deployment can't proceed until every check passes.

Different Workflows for Different Environments

Development, staging, and production must have different pipeline workflows. Not just different deployment targets, but different validation requirements. The production pipeline is stricter than the staging pipeline. The staging pipeline is stricter than the development pipeline.

The production pipeline includes the full set of security gates. The development pipeline might skip some of the longer-running gates to preserve developer velocity. But the production pipeline never skips them.

This layered approach means that code progressively passes through stricter security validation as it approaches production. By the time it reaches the production deployment gate, it has already passed through multiple layers of automated security validation in lower environments.

Microservices and Internal Service Security

Building microservices introduces a security challenge that monolithic architectures don't have: every service-to-service communication is a potential attack surface.

In a monolith, a method call between components is a function call in memory. It can't be intercepted, forged, or tampered with in transit.

In a microservices architecture, every service call is a network request. Network requests can be intercepted, forged, and tampered with. Services that implicitly trust each other because they're "internal" are making a dangerous assumption.

Every microservice must treat incoming requests as untrusted by default, including requests from other internal services. Authentication is required for every service-to-service communication. The API gateway handles external authentication. Internal service-to-service authentication must be handled separately.

Two patterns cover the main scenarios: mTLS for synchronous calls and authenticated event streams for asynchronous communication.

mTLS for synchronous service-to-service calls (mutual TLS) means both services present certificates to each other. The Payment Service calling the Account Service must present a valid certificate that the Account Service trusts. If the certificate is missing or invalid, the connection is rejected before any application code runs. This is cryptographic proof of identity: no bearer token to steal, no API key to rotate.

Payment Service                    Account Service
      |                                  |
      |-- presents its certificate ----> |
      |                                  |-- verifies certificate against trusted CA
      |                                  |-- rejects connection if invalid
      | <-- presents its certificate --- |
      |-- verifies certificate           |
      |                                  |
      |-- authorized request ----------> |
      |                                  |-- processes because identity is proven

Authenticated event streams for asynchronous communication mean every message published to a broker carries a signature that consuming services verify before processing. A service that publishes a PaymentCompleted event signs it with its private key. The consuming service verifies the signature before acting on the event. A forged event without a valid signature is discarded.

class PaymentEventPublisher {
  final KafkaProducer _producer;
  final EventSigner _signer;

  Future<void> publishPaymentCompleted(Payment payment) async {
    final event = PaymentCompletedEvent(
      paymentId: payment.id,
      amount: payment.amount,
      timestamp: DateTime.now().toIso8601String(),
    );

    final signature = await _signer.sign(jsonEncode(event.toJson()));

    await _producer.send(
      topic: 'payment.completed',
      value: jsonEncode({
        'payload': event.toJson(),
        'signature': signature,
        'publisher': 'payment-service',
      }),
    );
  }
}

class AccountEventConsumer {
  final EventVerifier _verifier;
  final AccountService _accountService;

  Future<void> onMessage(KafkaMessage message) async {
    final data = jsonDecode(message.value);
    final isValid = await _verifier.verify(
      jsonEncode(data['payload']),
      data['signature'] as String,
      data['publisher'] as String,
    );

    if (!isValid) {
      logger.warning('Invalid signature from ${data['publisher']} — discarding');
      return;
    }

    final event = PaymentCompletedEvent.fromJson(data['payload']);
    await _accountService.handlePaymentCompleted(event);
  }
}

Services must not be directly accessible from the internet without going through the API gateway. The gateway is the single entry point. It handles rate limiting, authentication, and routing for all external traffic. Services behind the gateway are internal: they're still not trusted by each other, but they're not exposed externally.

Overengineering is itself a security risk. An application that should be a well-designed monolith but is implemented as microservices introduces operational complexity that the team doesn't have the capacity to manage. Multiple deployment pipelines, multiple service boundaries, an API gateway, message brokers, and distributed tracing all require dedicated engineering capacity to operate securely. A monolith that isn't resourced to maintain properly is far less dangerous than a microservices architecture that isn't resourced to operate at all.

Choose your architecture based on what your team can actually operate securely, not based on what's fashionable.

Data Privacy and Compliance as Engineering Requirements

Data privacy requirements are engineering requirements. They're not legal requirements that engineering accommodates. They're engineering requirements that engineering owns.

Under Nigeria's NDPA 2023, personal data must be processed only for specified, explicit, and legitimate purposes. BVN data has specific residency and handling requirements enforced by CBN guidelines. Under PCI-DSS, any environment that stores, processes, or transmits cardholder data is in scope for compliance.

These requirements have concrete engineering implications.

1. Data Minimization

You can collect and store only the personal data that is actually needed for the specified purpose. An API that collects more data than it needs is creating compliance risk. A response that returns more data than the caller needs is both a BOPLA vulnerability and a data minimization violation.

2. Purpose Limitation

Data collected for one purpose must not be used for a different purpose without proper basis. The engineering implication is that data that flows within the system must be documented and enforced. Data from one service must not flow to another service that uses it for an unauthorized purpose.

3. Data Residency

Certain categories of data must be stored in specific geographic regions. This is an infrastructure requirement that must be designed into the system architecture, not patched in after deployment.

4. Retention and Deletion

Personal data must be deleted when the purpose for which it was collected is fulfilled, or when the retention period defined in the privacy notice expires. The engineering implication is that every category of personal data must have a defined retention policy and an automated deletion mechanism. Manual deletion policies that depend on someone remembering to delete data aren't compliant.

5. Audit Logging

Every access to personal data must be logged with sufficient detail to demonstrate compliance. Who accessed what data, when, for what stated purpose. This audit log must be tamper-evident and retained for the required period.

Here's what all five of these policies look like implemented together in a single feature (a user profile endpoint):

class UserProfileService {
  final UserRepository _repository;
  final AuditLogger _auditLogger;
  final DataResidencyValidator _residencyValidator;

  UserProfileService(this._repository, this._auditLogger, this._residencyValidator);

  Future<UserProfileResponse> getProfile(
    String requestingUserId,
    String targetUserId,
    String purpose,
  ) async {
    if (!_isValidPurpose(purpose)) {
      throw UnauthorizedException('Invalid or undeclared access purpose');
    }

    final user = await _repository.findById(targetUserId);
    if (user == null) throw NotFoundException('User not found');

    _residencyValidator.assertCompliant(user.dataRegion, requestingUserId);

    await _auditLogger.log(AuditEntry(
      action: 'READ_USER_PROFILE',
      actorId: requestingUserId,
      resourceId: targetUserId,
      purpose: purpose,
      timestamp: DateTime.now(),
      dataFieldsAccessed: ['first_name', 'last_name', 'email'],
    ));

    return UserProfileResponse(
      id: user.id,
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
    );
  }

  bool _isValidPurpose(String purpose) {
    const validPurposes = {
      'user_self_view',
      'customer_support_verified',
      'compliance_audit',
    };
    return validPurposes.contains(purpose);
  }
}

class DataRetentionService {
  final UserRepository _repository;
  final AuditLogger _auditLogger;

  Future<void> enforceRetentionPolicy() async {
    final cutoff = DateTime.now().subtract(const Duration(days: 2555));
    final expiredUsers = await _repository.findInactiveUsersBefore(cutoff);

    for (final user in expiredUsers) {
      await _auditLogger.log(AuditEntry(
        action: 'AUTOMATED_DATA_DELETION',
        resourceId: user.id,
        purpose: 'retention_policy_enforcement',
        timestamp: DateTime.now(),
      ));

      await _repository.anonymize(user.id);
    }
  }
}

This single service demonstrates all five compliance policies in working code. Purpose is declared on every access. Data residency is validated before returning data. The audit log captures every access with full context. The response returns only the fields needed. And a scheduled job enforces deletion automatically without anyone having to remember.

These requirements must be part of the requirements specification for every feature that handles personal data. Not addressed after the feature is built. Addressed in the design.

Conclusion

Security isn't a feature you add to software. It's a property you engineer into it from the beginning.

Threat modeling before architecture decisions means you understand what you're protecting and what you're protecting it against before you decide how to build it.

Security as a business rule means the domain layer enforces security requirements the same way it enforces any other business rule, impossible to bypass, impossible to forget.

Encryption standards as an organizational decision means no developer is choosing cryptographic primitives by preference or convenience.

Database security means the application can only do what it needs to do, and an attacker who compromises one component can't compromise everything.

CORS configuration means the browser security mechanism is actually enforcing the boundary, not bypassed by a wildcard.

Structured logging with field-level masking means sensitive data never ends up in a log file regardless of what developers log.

And CI/CD security gates mean automated validation catches what human review misses, on every push, before every deployment.

None of these are exotic or difficult concepts. They're engineering disciplines that require deliberate decisions and deliberate enforcement. The decision not to make them is itself a decision, and it has consequences that show up in incident reports.

The most expensive place to address a security vulnerability is after it has been exploited. The second most expensive place is after it has shipped to production. The least expensive place is in the design, before a single line of code exists.

That's what Secure by Design means in practice. Not perfect security or zero risk. Just deliberate, documented, enforceable decisions about how the system handles adversarial conditions, made before the system is built, so the engineering is sound from the start.

One of the things to look forward to as an technology enthusiast is the day when applications are built with security as an integral part of that development process. Not as an afterthought or something that needs to pass just for deployment to happen. This is why you need to understand, accept, and adopt Secure by Design as a standardized process, not only in the Application Security Field but also in core software engineering.

Happy Secured Coding!

I've reviewed production systems where JWTs had no expiry. Systems where API keys were hardcoded in source code and committed to public repositories. Systems where OAuth redirect URIs used wildcards. Systems where Basic Auth was being used for financial APIs over what was supposed to be HTTPS but nobody checked.

Every single one of those was a live vulnerability waiting to be exploited.

Most of these problems didn't come from careless engineers. They came from engineers who understood how to make the mechanism work but didn't understand the failure modes. Nobody told them what happens when it breaks. Nobody defined what the organizational standard was. They picked what they knew, implemented it well enough to pass code review, and moved on.

This article is about changing that. Not just how each mechanism works, but when to use it, when not to use it, and exactly how it fails in production.

Before anything else, let's clear up a confusion that causes real vulnerabilities. Authentication answers: who are you? Authorization answers: what are you allowed to do?

A system that authenticates perfectly but authorizes poorly will still serve unauthorized data. A system that authorizes perfectly but authenticates weakly is trivially bypassed. Both must be correct, independently.

Table of Contents

• Prerequisites

• The Foundation: What You Must Get Right Before Choosing a Mechanism

• 1. Basic Authentication

• 2. API Keys

• 3. Bearer Token Authentication

• 4. JWT - JSON Web Token

• 5. OAuth 2.0

• 6. OpenID Connect (OIDC)

• 7. Mutual TLS (mTLS)

• Choosing the Right Mechanism

• The Organizational Discipline That Ties Everything Together

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• What an API is and how HTTP requests and responses work

• A basic understanding of what a token or session is

• General software architecture concepts: what a gateway is, and what a service layer is

• Familiarity with Dart or C# syntax

You don't need a security background. Every concept here is explained from an engineering perspective.

The Foundation: What You Must Get Right Before Choosing a Mechanism

Before you even think about which mechanism to use, three things must be in place. No mechanism saves you if these are missing.

1. TLS isn't Optional

Every API communicates over HTTPS. Every endpoint and environment, not just production. Not just the endpoints that handle card numbers. All of them.

Without TLS, every mechanism in this article can be intercepted. Basic Auth tokens, API keys, bearer tokens, JWT all travel in HTTP headers. HTTP headers are plaintext without TLS.

Your infrastructure must enforce TLS 1.2 minimum. TLS 1.0 and 1.1 have known vulnerabilities. SSLv3 is catastrophically broken. If a client tries to negotiate an older protocol version, the connection must be rejected at the infrastructure layer. This is a configuration decision, not something you handle in code.

2. Production APIs Must Not Be Accessible on Public Tooling Without Proper Controls

A production API accessible over the internet through Postman or Swagger without proper access controls is a problem waiting to happen.

Development and testing must use dedicated environments with separate credentials that have zero access to production data.

3. Production Data Must Not Be Copied to Development or Test Environments

This isn't just good practice. Under Nigeria's NDPA 2023, personal data must be processed only for specified, explicit, and legitimate purposes. Copying production personal data to a development environment creates direct legal exposure. Under PCI-DSS, any environment that stores, processes, or transmits cardholder data is in scope for compliance.

The engineering answer is synthetic test data and anonymized datasets in every non-production environment, always.

With that in place, here are the seven mechanisms.

1. Basic Authentication

How It Works

The client sends a username and password on every single request. The credentials are combined as username:password, encoded in Base64, and placed in the Authorization header.

Authorization: Basic am9objpzZWNyZXQxMjM=

That encoded string is john:secret123 in Base64. Base64 isn't encryption. It's encoding. Anyone who captures that header can decode it in seconds using any Base64 decoder available online.

Dart:

// server-side basic auth validation
String? extractBasicAuthCredentials(Request request) {
  final authHeader = request.headers['authorization'];
  if (authHeader == null || !authHeader.startsWith('Basic ')) return null;

  final encoded = authHeader.substring(6);
  final decoded = utf8.decode(base64.decode(encoded));
  return decoded; 
}

Handler basicAuthMiddleware(Handler handler, UserService userService) {
  return (Request request) async {
    final credentials = extractBasicAuthCredentials(request);
    if (credentials == null) {
      return Response.unauthorized(
        'Missing credentials',
        headers: {'WWW-Authenticate': 'Basic realm="API"'},
      );
    }

    final parts = credentials.split(':');
    if (parts.length != 2) return Response.unauthorized('Invalid credentials');

    final isValid = await userService.validateCredentials(parts[0], parts[1]);
    if (!isValid) return Response.unauthorized('Invalid credentials');

    return handler(request);
  };
}

C#:

public class BasicAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    private readonly IUserService _userService;

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.ContainsKey("Authorization"))
            return AuthenticateResult.Fail("Missing Authorization header");

        var authHeader = Request.Headers["Authorization"].ToString();
        if (!authHeader.StartsWith("Basic "))
            return AuthenticateResult.Fail("Invalid Authorization scheme");

        var encoded = authHeader.Substring(6);
        var decoded = Encoding.UTF8.GetString(Convert.FromBase64String(encoded));
        var parts = decoded.Split(':');

        if (parts.Length != 2)
            return AuthenticateResult.Fail("Invalid credentials format");

        var isValid = await _userService.ValidateCredentials(parts[0], parts[1]);
        if (!isValid)
            return AuthenticateResult.Fail("Invalid credentials");

        var claims = new[] { new Claim(ClaimTypes.Name, parts[0]) };
        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, Scheme.Name);

        return AuthenticateResult.Success(ticket);
    }
}

The Real Problem With Basic Auth

Credentials travel on every single request. One intercepted request gives an attacker the username and password permanently. There's no expiry. There's no revocation short of changing the password. Base64 provides zero security.

No rate limiting on a Basic Auth endpoint is an open invitation for brute force. An attacker with a list of common passwords will systematically try every one. If nothing stops them, they'll eventually get in.

When to Use It

Basic auth works for internal server-to-server communication within a tightly controlled environment where the connection is always encrypted and the API surface is not exposed to the internet. Never use it for user-facing APIs, for anything handling sensitive data, or without TLS.

2. API Keys

An API key is simply a unique secret string that a server issues to a client to identify it. When you sign up to use a third-party service like a payment gateway, or an SMS platform, you're issued a key. Every request your application makes to that service includes that key so the service knows it's you calling, can track your usage, and can apply the right permissions and rate limits to your requests.

It's not tied to a user. It's tied to your application. That's the fundamental difference between an API key and a user authentication token

How It Works

A static secret string is issued to a client and sent in a header on every request.

X-API-Key: sk_live_abc123xyz

Dart:

class ApiKeyService {
  final ApiKeyRepository _repository;

  ApiKeyService(this._repository);

  Future<Result<ApiKeyContext, AppException>> validateApiKey(
    String apiKey,
    String callerDomain,
  ) async {
    final keyRecord = await _repository.findByKey(apiKey);

    if (keyRecord == null) {
      return Result.failure(AppException.unauthorized('Invalid API key'));
    }

    if (keyRecord.isExpired) {
      return Result.failure(AppException.unauthorized('API key has expired'));
    }

    if (keyRecord.isRevoked) {
      return Result.failure(AppException.unauthorized('API key has been revoked'));
    }

    // validate that the calling domain is allowed for this key
    if (!keyRecord.allowedDomains.contains(callerDomain)) {
      return Result.failure(
        AppException.forbidden('Calling domain not authorized for this API key'),
      );
    }

    return Result.success(ApiKeyContext(
      clientId: keyRecord.clientId,
      environment: keyRecord.environment,
      allowedScopes: keyRecord.allowedScopes,
    ));
  }
}

Handler apiKeyMiddleware(Handler handler, ApiKeyService apiKeyService) {
  return (Request request) async {
    final apiKey = request.headers['x-api-key'];
    if (apiKey == null || apiKey.isEmpty) {
      return Response(401, body: jsonEncode({'error': 'API key required'}));
    }

    final origin = request.headers['origin'] ?? request.headers['host'] ?? '';
    final result = await apiKeyService.validateApiKey(apiKey, origin);

    if (result.isFailure) {
      return Response(403, body: jsonEncode({'error': result.error?.message}));
    }

    return handler(request);
  };
}

C#:

public class ApiKeyMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IApiKeyService _apiKeyService;

    public async Task InvokeAsync(HttpContext context)
    {
        if (!context.Request.Headers.TryGetValue("X-API-Key", out var apiKey))
        {
            context.Response.StatusCode = 401;
            await context.Response.WriteAsync("API key required");
            return;
        }

        var callerDomain = context.Request.Headers["Origin"].ToString()
            ?? context.Request.Host.Value;

        var result = await _apiKeyService.ValidateApiKey(apiKey, callerDomain);

        if (!result.IsSuccess)
        {
            context.Response.StatusCode = 403;
            await context.Response.WriteAsync(result.Error);
            return;
        }

        context.Items["ApiKeyContext"] = result.Value;
        await _next(context);
    }
}

The Real Problem With API Keys

API keys are static. They don't expire automatically. A key found in a public GitHub repository, a Slack message, or a log file is a live credential until someone notices and rotates it.

One of the most common gaps I've seen in large-scale organizations is that APIs called by multiple clients have no domain allowlisting. The same key works from any domain. This makes it possible to share keys across clients and across environments, which means a staging key can call production, a mobile key can be used from a web client, and there's no real boundary between any of them.

No API key should work for multiple clients or multiple environments. Keys must be tied to specific allowed domains and specific environments. This isn't optional.

Never hardcode API keys in source code. Never commit them to Git. .gitignore is not enough. Keys must be fetched from a trusted secrets manager at runtime: vaults, Azure App Configuration, AWS Secrets Manager. API key rotation must be a scheduled organizational practice, not a reaction to a suspected leak.

When to Use It

Use API keys for server-to-server communication, public APIs where you need to identify and rate-limit callers, and developer tools and integrations. Any scenario where a human user isn't the direct caller.

3. Bearer Token Authentication

How It Works

The client authenticates once through a login flow and receives a token. That token travels in the Authorization header on all subsequent requests.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

There are no credentials after the initial login. The token is what travels. The server validates the token on every request.

Dart:

class BearerTokenMiddleware {
  final TokenValidator _validator;

  BearerTokenMiddleware(this._validator);

  Handler call(Handler handler) {
    return (Request request) async {
      final authHeader = request.headers['authorization'];

      if (authHeader == null || !authHeader.startsWith('Bearer ')) {
        return Response(401, body: jsonEncode({'error': 'Bearer token required'}));
      }

      final token = authHeader.substring(7);
      final validationResult = await _validator.validate(token);

      if (validationResult.isFailure) {
        return Response(401, body: jsonEncode({'error': validationResult.error?.message}));
      }

      final updatedRequest = request.change(
        context: {'auth_claims': validationResult.value},
      );

      return handler(updatedRequest);
    };
  }
}

C#:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Secret"]!)
            ),
            ClockSkew = TimeSpan.Zero
        };
    });

The Real Problem With Bearer Tokens

Token theft is the biggest problem. If an attacker gets hold of a valid bearer token, they can use it until it expires or is manually revoked. This is why token expiry is not a nice-to-have. It's what limits the damage when a token is compromised. Short-lived access tokens with refresh token rotation is the correct pattern.

When to Use It

They work well in most modern web and mobile APIs, user authentication flows, and in any API where stateless, scalable authentication is needed.

4. JWT – JSON Web Token

How It Works

JWTs are a specific format for bearer tokens, not a separate authentication mechanism. They're self-contained tokens that carry claims about the user inside the token itself.

A JWT has three parts separated by dots:

Header.Payload.Signature
eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ.SIGNATURE

The header specifies the signing algorithm. The payload carries the claims: user ID, role, expiry time, and issued at time. The signature is a cryptographic hash that proves the token came from your server and hasn't been tampered with.

The server validates the signature cryptographically and trusts the claims inside. No database lookup is needed. This is what makes JWTs stateless and scalable.

Dart:

class JwtService {
  final String _secret;
  final String _issuer;
  final Duration _accessTokenExpiry;

  JwtService({
    required String secret,
    required String issuer,
    Duration accessTokenExpiry = const Duration(minutes: 15),
  })  : _secret = secret,
        _issuer = issuer,
        _accessTokenExpiry = accessTokenExpiry;

  String generateAccessToken(User user) {
    final now = DateTime.now();
    final payload = {
      'sub': user.id,
      'role': user.role.name,
      'iat': now.millisecondsSinceEpoch ~/ 1000,
      'exp': now.add(_accessTokenExpiry).millisecondsSinceEpoch ~/ 1000,
      'iss': _issuer,
      
    };

    return _sign(payload);
  }

  Result<JwtClaims, AppException> validateToken(String token) {
    try {
      final claims = _verifyAndDecode(token);

      final exp = claims['exp'] as int;
      if (DateTime.fromMillisecondsSinceEpoch(exp * 1000).isBefore(DateTime.now())) {
        return Result.failure(AppException.unauthorized('Token has expired'));
      }

      if (claims['iss'] != _issuer) {
        return Result.failure(AppException.unauthorized('Invalid token issuer'));
      }

      return Result.success(JwtClaims.fromMap(claims));
    } on SignatureVerificationException {
      return Result.failure(AppException.unauthorized('Invalid token signature'));
    } catch (e) {
      return Result.failure(AppException.unauthorized('Token validation failed'));
    }
  }
}

C#:

public class JwtService
{
    private readonly JwtSettings _settings;

    public string GenerateAccessToken(User user)
    {
        var securityKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_settings.Secret)
        );

       
        var credentials = new SigningCredentials(
            securityKey,
            SecurityAlgorithms.HmacSha256
        );

        var claims = new[]
        {
            new Claim(JwtRegisteredClaimNames.Sub, user.Id),
            new Claim(ClaimTypes.Role, user.Role.ToString()),
            new Claim(JwtRegisteredClaimNames.Iat,
                DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString()),
           
        };

        var token = new JwtSecurityToken(
            issuer: _settings.Issuer,
            audience: _settings.Audience,
            claims: claims,
            expires: DateTime.UtcNow.AddMinutes(15),
            signingCredentials: credentials
        );

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

JWT Failure Modes

JWTs are excellent when implemented correctly. When implemented incorrectly, they can be catastrophic. Every failure is an implementation failure, not a standard failure. Here are the ones I've seen that cause real problems.

1. The algorithm confusion attack

The JWT header specifies which algorithm was used to sign it. If your server accepts whatever algorithm the token claims, an attacker sets the algorithm to none and strips the signature entirely. Your server accepts any token as valid.

2. Weak signing secrets

A weak JWT secret can be brute-forced offline. The attacker doesn't need access to your server. They take the token, run it through a cracker, discover the secret, and can now sign any token they want as any user they want.

Use cryptographically strong secrets of at least 256 bits. For high-security contexts use RS256 or ES256 with asymmetric keys.

3. No expiry

A JWT without an exp claim never becomes invalid. Set an expiry, always. For short-lived access tokens, choose 15 minutes to 1 hour. Refresh tokens handle session continuity.

4. Sensitive data in the payload

The payload is Base64 encoded, not encrypted. Anyone who gets the token can decode and read everything inside. Never put passwords, full account numbers, BVN, or sensitive PII in a JWT payload. Put identifiers instead. Let the server fetch the sensitive data.

5. No revocation strategy

Because JWTs are stateless, the server doesn't track issued tokens. A stolen token is valid until it expires.

The fix: maintain a token blocklist for explicitly revoked tokens, or use short expiry with refresh token rotation so the damage window is small.

When to Use JWTs

Use them for stateless APIs at scale, microservices where services need to verify identity without calling a central auth server on every request, and mobile applications. They're good for any system where stateless authentication scalability matters more than the complexity of managing token revocation.

5. OAuth 2.0

How It Works

OAuth 2.0 is an authorization framework, not an authentication protocol. It lets a user grant a third-party application access to their resources without sharing their password with that third party.

You have used this every time you logged into an app with Google, or saw "Allow this app to access your account."

Four parties are involved: the Authorization Server that issues tokens, the Resource Server that hosts the protected API, the Client which is the application requesting access, and the Resource Owner which is the user.

The Authorization Code flow works like this:

1. The client redirects the user to the Authorization Server with a request for specific scopes

2. The user authenticates and approves the requested scopes

3. The Authorization Server redirects back to the client with an authorization code

4. The client exchanges the code for an access token server-side

5. The client uses the access token to call the Resource Server

Dart:

class OAuthClient {
  final String _clientId;
  final String _clientSecret;
  final String _redirectUri;
  final String _authorizationEndpoint;
  final String _tokenEndpoint;

  OAuthClient({
    required String clientId,
    required String clientSecret,
    required String redirectUri,
    required String authorizationEndpoint,
    required String tokenEndpoint,
  })  : _clientId = clientId,
        _clientSecret = clientSecret,
        _redirectUri = redirectUri,
        _authorizationEndpoint = authorizationEndpoint,
        _tokenEndpoint = tokenEndpoint;

  String buildAuthorizationUrl(List<String> scopes) {
   
    final state = _generateSecureState();

    final params = {
      'response_type': 'code',
      'client_id': _clientId,
      'redirect_uri': _redirectUri,
      'scope': scopes.join(' '),
      'state': state,
    };

    final uri = Uri.parse(_authorizationEndpoint)
        .replace(queryParameters: params);

    return uri.toString();
  }

  Future<Result<OAuthTokens, AppException>> exchangeCodeForTokens(
    String code,
    String state,
    String expectedState,
  ) async {
   
    if (state != expectedState) {
      return Result.failure(
        AppException.unauthorized('Invalid state parameter'),
      );
    }

    final response = await http.post(
      Uri.parse(_tokenEndpoint),
      headers: {'Content-Type': 'application/x-www-form-urlencoded'},
      body: {
        'grant_type': 'authorization_code',
        'code': code,
        'redirect_uri': _redirectUri,
        'client_id': _clientId,
        'client_secret': _clientSecret,
      },
    );

    if (response.statusCode != 200) {
      return Result.failure(AppException.unauthorized('Token exchange failed'));
    }

    final tokens = OAuthTokens.fromJson(jsonDecode(response.body));
    return Result.success(tokens);
  }

  String _generateSecureState() {
    final bytes = List<int>.generate(32, (_) => Random.secure().nextInt(256));
    return base64Url.encode(bytes);
  }
}

C#:

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = "OAuth2";
})
.AddCookie()
.AddOAuth("OAuth2", options =>
{
    options.ClientId = builder.Configuration["OAuth:ClientId"]!;
    options.ClientSecret = builder.Configuration["OAuth:ClientSecret"]!;
    options.CallbackPath = "/auth/callback";
    options.AuthorizationEndpoint = "https://auth.provider.com/authorize";
    options.TokenEndpoint = "https://auth.provider.com/token";
    options.SaveTokens = true;
    options.Scope.Add("openid");
    options.Scope.Add("profile");

    options.Events = new OAuthEvents
    {
        OnCreatingTicket = async context =>
        {
            var userInfoRequest = new HttpRequestMessage(
                HttpMethod.Get,
                "https://auth.provider.com/userinfo"
            );
            userInfoRequest.Headers.Authorization =
                new AuthenticationHeaderValue("Bearer", context.AccessToken);

            var response = await context.Backchannel.SendAsync(userInfoRequest);
            var userInfo = await response.Content.ReadFromJsonAsync<JsonDocument>();

            context.Identity!.AddClaim(new Claim(
                ClaimTypes.NameIdentifier,
                userInfo!.RootElement.GetString("sub")!
            ));
        }
    };
});

OAuth 2.0 Failure Modes

1. Misconfigured redirect URIs

If the authorization server doesn't strictly validate redirect URIs, an attacker substitutes their own URI and intercepts the authorization code. Use exact match validation to prevent this.

2. Tokens in URLs

Access tokens can appear in server logs, browser history, or referrer headers because someone put them in a query parameter instead of an Authorization header. Tokens belong in Authorization headers. URLs appear in logs, while authorization headers don't.

When to Use OAuth 2.0

It works well in any scenario where a third party needs delegated access to user resources, like social login, API integrations between organizations, or partner system integrations.

6. OpenID Connect (OIDC)

How It Works

OAuth 2.0 handles authorization. OpenID Connect adds authentication on top of OAuth 2.0. It doesn't just tell you what the user approved. It tells you who the user actually is.

OIDC issues an ID token alongside the access token. The ID token is a JWT containing verified identity claims: subject identifier, email, name, profile picture, and when the authentication happened.

Dart:

class OidcService {
  final String _issuer;
  final String _clientId;
  final JwtValidator _jwtValidator;

  OidcService({
    required String issuer,
    required String clientId,
    required JwtValidator jwtValidator,
  })  : _issuer = issuer,
        _clientId = clientId,
        _jwtValidator = jwtValidator;

  Future<Result<UserIdentity, AppException>> validateIdToken(
    String idToken,
  ) async {
    final claimsResult = await _jwtValidator.validate(idToken);
    if (claimsResult.isFailure) {
      return Result.failure(claimsResult.error!);
    }

    final claims = claimsResult.value!;

    if (claims['iss'] != _issuer) {
      return Result.failure(AppException.unauthorized('Invalid token issuer'));
    }


    final aud = claims['aud'];
    final audiences = aud is List ? aud : [aud];
    if (!audiences.contains(_clientId)) {
      return Result.failure(
        AppException.unauthorized('Token not intended for this client'),
      );
    }

    return Result.success(UserIdentity(
      subject: claims['sub'] as String,
      email: claims['email'] as String?,
      name: claims['name'] as String?,
      emailVerified: claims['email_verified'] as bool? ?? false,
    ));
  }
}

C#:

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    options.Authority = "https://accounts.google.com";
    options.ClientId = builder.Configuration["OIDC:ClientId"]!;
    options.ClientSecret = builder.Configuration["OIDC:ClientSecret"]!;
    options.ResponseType = "code";
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("email");
    options.SaveTokens = true;
    options.GetClaimsFromUserInfoEndpoint = true;

    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        NameClaimType = "name",
        RoleClaimType = "role"
    };
});

When to Use OIDC

It's good for any application that needs to verify user identity through a trusted identity provider, like enterprise SSO or social login. It works well for any system where you want to delegate identity verification to a trusted third party rather than managing user credentials yourself.

Google Sign-In, Microsoft Azure AD, Okta, Auth0 all implement OIDC. If your question is "who is this person" rather than just "is this request authorized," OIDC is the right framework.

7. Mutual TLS (mTLS)

How It Works

In regular TLS, the client verifies the server's certificate. The server trusts any client that can establish a connection.

In mutual TLS, both parties verify each other's certificates. The server only accepts connections from clients with a certificate issued by a trusted Certificate Authority. The client can't fake its identity because it needs a real certificate.

There's no bearer token or API key. The certificate is the authentication.

Dart (client-side mTLS):

class MtlsHttpClient {
  final http.Client _client;

  MtlsHttpClient._internal(this._client);

  static Future<MtlsHttpClient> create({
    required String certificatePath,
    required String privateKeyPath,
    required String trustedCaPath,
  }) async {
    final context = SecurityContext(withTrustedRoots: false);

    // load the client certificate
    context.useCertificateChainBytes(
      await File(certificatePath).readAsBytes(),
    );

    // load the client private key
    context.usePrivateKeyBytes(
      await File(privateKeyPath).readAsBytes(),
    );

    // only trust this specific CA
    context.setTrustedCertificatesBytes(
      await File(trustedCaPath).readAsBytes(),
    );

    final httpClient = HttpClient(context: context);
    final client = IOClient(httpClient);

    return MtlsHttpClient._internal(client);
  }

  Future<http.Response> get(String url, {Map<String, String>? headers}) {
    return _client.get(Uri.parse(url), headers: headers);
  }

  Future<http.Response> post(
    String url, {
    Map<String, String>? headers,
    Object? body,
  }) {
    return _client.post(Uri.parse(url), headers: headers, body: body);
  }
}

C#:

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        httpsOptions.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
        httpsOptions.ClientCertificateValidation = (certificate, chain, errors) =>
        {
            if (errors != SslPolicyErrors.None)
                return false;

            var expectedThumbprint = "your-trusted-cert-thumbprint";
            return certificate.Thumbprint == expectedThumbprint;
        };
    });
});

public class MtlsMiddleware
{
    private readonly RequestDelegate _next;

    public async Task InvokeAsync(HttpContext context)
    {
        var clientCert = context.Connection.ClientCertificate;

        if (clientCert == null)
        {
            context.Response.StatusCode = 401;
            await context.Response.WriteAsync("Client certificate required");
            return;
        }

        if (!IsValidClientCertificate(clientCert))
        {
            context.Response.StatusCode = 403;
            await context.Response.WriteAsync("Invalid client certificate");
            return;
        }

        await _next(context);
    }

    private bool IsValidClientCertificate(X509Certificate2 cert)
    {
        if (cert.NotAfter < DateTime.UtcNow) return false;

        var trustedThumbprints = new HashSet<string>
        {
            "THUMBPRINT_SERVICE_A",
            "THUMBPRINT_SERVICE_B",
        };

        return trustedThumbprints.Contains(cert.Thumbprint);
    }
}

The Real Problem With mTLS

The issue here is certificate management. Certificates expire. If rotation isn't automated, an expired certificate breaks service-to-service communication at the worst possible time. The CA infrastructure itself must be secured. A compromised CA means every certificate it issued is compromised.

For teams without the operational capacity to manage a full PKI, API keys with strict domain allowlisting and rotation schedules may be the more practical answer. mTLS is the right architecture, but it's also the most demanding to operate correctly.

When to Use mTLS

Use mTLS for high-security service-to-service communication, like payment gateways or banking APIs. It also works well for microservices in regulated environments where compliance requires cryptographic proof of identity at the transport layer. Every communication between internal services in a high-security system should be treated as sensitive. mTLS provides that foundation.

Choosing the Right Mechanism

Choosing an authentication mechanism is an architectural decision. Here's the framework:

For user-facing web and mobile applications: choose bearer tokens with JWT. Short-lived access tokens with refresh token rotation. Rate limiting on all authentication endpoints.

For third-party delegated access: use OAuth 2.0. When you also need to verify user identity, add OIDC on top.

For enterprise SSO: choose OpenID Connect with an enterprise identity provider.

For server-to-server, lower security requirements: use API keys with domain allowlisting, environment-specific keys, and scheduled rotation.

For service-to-service in regulated high-security environments: use mTLS.

For internal tooling in tightly controlled environments: Basic Auth is the floor, and only if TLS is guaranteed. For everything else, use something stronger.

You should choose your authentication mechanism based on who the caller is, what the data sensitivity is, and what the compliance requirements are. Not by convention or by what the last project used. And not by what's easiest to implement.

The Organizational Discipline That Ties Everything Together

Getting the technical implementation right is half the work. The other half is organizational.

API key rotation must be scheduled and proactive, not a reaction to a suspected leak. Every key has a defined maximum lifetime and a rotation schedule that engineering owns.

No API key works for multiple clients or multiple environments. A staging key is a staging key. A mobile client key is a mobile client key. Cross-environment key reuse is a security boundary collapse.

Secrets never live in source code, application code, or in configuration files committed to the repository. Secrets are fetched from a trusted secrets manager at runtime. This is an engineering standard, not a preference.

Encryption algorithms must be an organizational standard, not a developer decision made per project. Someone at the staff engineer or architect level defines which algorithm, which mode, and which key length the organization uses. Every project uses the standard, and no developer implements encryption from scratch per project.

Organizations should build and maintain internally shared packages for cryptographic operations. Developers import the package. They never write encryption themselves. This eliminates an entire category of cryptographic implementation failures that come from ad-hoc choices.

Structured logging with field-level masking must be enforced at the framework level. Authorization headers, tokens, passwords, account numbers, and any sensitive field must never appear in logs in any environment (production, staging, or development). The masking applies at the logging framework level so no individual developer can accidentally log sensitive data even if they try.

Conclusion

Every mechanism in this article works when implemented correctly. And at the same time, every mechanism fails in predictable, documented ways when implemented incorrectly.

JWT algorithm confusion attacks have caused real authentication bypasses. Misconfigured OAuth redirect URIs have caused real account takeovers. Missing state parameters have enabled real CSRF attacks. Weak signing secrets have led to real impersonation at scale. Hardcoded API keys in repositories have exposed production systems to unauthorized access.

These aren't theoretical failure modes. They appear in production systems at organizations of every size. The engineers who built those systems weren't incompetent. They just weren't told about the failure modes. Nobody defined the organizational standard or enforced it in the pipeline.

The engineering discipline is knowing exactly how each mechanism breaks before you write the first line of code, and building your implementation to avoid those failure modes from the start. That's the difference between authentication that works and authentication that holds up under adversarial conditions.

Happy Coding!

This article is different. It looks at each OWASP API Security Top 10 vulnerability from the inside: what engineering decision allowed it to exist, which architectural principle was violated, and what the engineering standard should be to prevent it from ever shipping to production.

I've spent years building production applications at scale in regulated financial environments. The vulnerabilities in this list aren't theoretical. I've seen most of them in real systems. Some of them I caught before they reached production. Some of them were already live when I arrived. Every single one of them was preventable...and not by security tools, but by engineering discipline.

That's the lens this article uses.

Table of Contents

• Prerequisites

• What is the OWASP API Security Top 10?

• 1. Broken Object Level Authorization (BOLA)

• 2. Broken Authentication

• 3. Broken Object Property Level Authorization (BOPLA)

• 4. Unrestricted Resource Consumption

• 5. Broken Function Level Authorization (BFLA)

• 6. Unrestricted Access to Sensitive Business Flows

• 7. Security Misconfiguration

• 8. Improper Inventory Management

• 9. Unsafe Consumption of APIs

• 10. Server-Side Request Forgery (SSRF)

• Engineering Vulnerabilities Beyond the OWASP List

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Building APIs in any language or framework

• Basic understanding of authentication: what tokens and sessions are

• What a database query looks like at a high level

• General software architecture concepts, like layers, services, and gateways

You don't need a security background. This article explains every vulnerability from an engineering perspective, not a security analyst perspective.

What is the OWASP API Security Top 10?

OWASP stands for Open Web Application Security Project. It's a non-profit foundation that produces freely available security guidance for engineers and organizations. The OWASP API Security Top 10 is a regularly updated list of the most critical API vulnerabilities found in production systems globally.

It's not a theoretical list. It's compiled from real security incidents, penetration test findings, and vulnerability reports from production systems across industries. Every item on this list has caused real data breaches, real financial losses, and real regulatory penalties in real organizations.

Understanding this list isn't optional for engineers building APIs. It's foundational knowledge.

1. Broken Object Level Authorization (BOLA)

What it is

A user is authenticated and they have a valid token. But they can access data that doesn't belong to them simply by changing an identifier in the request.

GET /api/accounts/12345/transactions

User A is authenticated and owns account 12345. They change the account number:

GET /api/accounts/99999/transactions

If the API returns User B's transactions, BOLA exists. The user is authenticated but the API isn't verifying that the authenticated user owns the requested resource.

This is the most common API vulnerability in the world. It consistently tops the OWASP list because it's so easy to introduce and so easy to miss in code review.

The Engineering Failure

BOLA happens when authorization is treated as a binary question: is this user authenticated? Yes or no. The API checks whether the user has a valid token and stops there. It never asks the second question: does this authenticated user own the specific resource they're requesting?

The authentication isn't ID-agnostic. It proves who you are but it never proves whether the thing you are asking for belongs to you.

The Engineering Fix

Authorization must happen at the service layer, not just at the API gateway. The API gateway can verify that the token is valid. Only the service layer knows whether the authenticated user owns the resource being requested.

Dart (service layer enforcement):

class TransactionService {
  final TransactionRepository _repository;
  final AuthContext _authContext;

  TransactionService(this._repository, this._authContext);

  Future<Result<List<Transaction>, AppException>> getTransactions(
    String accountId,
  ) async {
    final currentUserId = _authContext.currentUserId;

    // fetch the account first
    final account = await _repository.findAccountById(accountId);

    if (account == null) {
      return Result.failure(AppException.notFound('Account not found'));
    }

    // verify ownership before returning any data
    if (account.ownerId != currentUserId) {
      return Result.failure(
        AppException.forbidden('Access denied to this account'),
      );
    }

    final transactions = await _repository.findByAccountId(accountId);
    return Result.success(transactions);
  }
}

C#:

public async Task<Result<IEnumerable<Transaction>>> GetTransactions(
    string accountId,
    ClaimsPrincipal currentUser)
{
    var userId = currentUser.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    var account = await _repository.FindAccountByIdAsync(accountId);

    if (account == null)
        return Result.Failure<IEnumerable<Transaction>>("Account not found");

    // ownership check — never skip this
    if (account.OwnerId != userId)
        return Result.Failure<IEnumerable<Transaction>>("Access denied");

    var transactions = await _repository.FindByAccountIdAsync(accountId);
    return Result.Success(transactions);
}

The ownership check must happen on every request that accesses a specific resource. Not just on first load or on write operations. Every single request.

2. Broken Authentication

What it is

Weak tokens, no token expiry, no rate limiting on authentication endpoints, or sessions that never terminate on logout. Any weakness in the mechanism that identifies who's making a request.

The Engineering Failure

Authentication is treated as a solved problem once it's working. Engineers implement login, get a token back, and move on. The failure modes (like what happens when a token is stolen, or if an attacker hammers the login endpoint with a list of passwords, or when a user logs out) are never designed for.

The authentication mechanism must be designed for adversarial conditions, not just for happy path usage.

The Engineering Fix

Token expiry is mandatory. Access tokens should be short-lived: 15 minutes to 1 hour. Refresh tokens handle session continuity. Short-lived access tokens limit the damage window when a token is stolen.

Rate limiting on authentication endpoints is mandatory. A login endpoint without rate limiting is an open invitation for brute force attacks. An attacker with a list of 10 million email and password combinations will systematically try every one.

Sessions must actually terminate on logout. If you're using stateful sessions, the session must be invalidated server-side on logout. If you're using JWT, maintain a token blocklist or use a very short expiry with refresh token rotation.

Dart:

class AuthService {
  final TokenRepository _tokenRepository;
  final RateLimiter _rateLimiter;

  AuthService(this._tokenRepository, this._rateLimiter);

  Future<Result<AuthTokens, AppException>> login(
    String email,
    String password,
    String ipAddress,
  ) async {
    // rate limit by IP to prevent brute force
    final isAllowed = await _rateLimiter.checkLimit(
      key: 'login:$ipAddress',
      maxAttempts: 5,
      windowSeconds: 300,
    );

    if (!isAllowed) {
      return Result.failure(
        AppException.rateLimited('Too many login attempts. Try again later.'),
      );
    }

    final user = await _validateCredentials(email, password);

    if (user == null) {
      return Result.failure(
        AppException.unauthorized('Invalid credentials'),
      );
    }

    // short-lived access token
    final accessToken = _generateAccessToken(user, expiryMinutes: 15);

    // longer-lived refresh token, stored server-side
    final refreshToken = _generateRefreshToken(user);
    await _tokenRepository.storeRefreshToken(user.id, refreshToken);

    return Result.success(AuthTokens(
      accessToken: accessToken,
      refreshToken: refreshToken,
    ));
  }

  Future<void> logout(String userId, String refreshToken) async {
    // invalidate the refresh token server-side on logout
    await _tokenRepository.revokeRefreshToken(userId, refreshToken);
  }
}

C#:

public async Task<Result<AuthTokens>> Login(
    LoginRequest request,
    string ipAddress)
{
    var isAllowed = await _rateLimiter.CheckLimit(
        key: $"login:{ipAddress}",
        maxAttempts: 5,
        windowSeconds: 300);

    if (!isAllowed)
        return Result.Failure<AuthTokens>("Too many login attempts.");

    var user = await _userService.ValidateCredentials(
        request.Email,
        request.Password);

    if (user == null)
        return Result.Failure<AuthTokens>("Invalid credentials");

    var accessToken = _tokenService.GenerateAccessToken(user, expiryMinutes: 15);
    var refreshToken = _tokenService.GenerateRefreshToken(user);

    await _tokenRepository.StoreRefreshToken(user.Id, refreshToken);

    return Result.Success(new AuthTokens(accessToken, refreshToken));
}

public async Task Logout(string userId, string refreshToken)
{
    await _tokenRepository.RevokeRefreshToken(userId, refreshToken);
}

3. Broken Object Property Level Authorization (BOPLA)

What it is

The API returns more data than the user needs. Internal flags, admin permissions, and sensitive fields that should never leave the server end up in the response payload. Or worse: the API accepts more data than the user should be able to set, allowing users to modify fields they should never touch.

A user fetches their profile and the response includes isAdmin: false, internalAccountScore: 742, or fraudRiskLevel: "low". None of these should ever be in a user-facing response.

Or a user updates their profile and the request body includes "role": "admin". The API processes it. The user has just promoted themselves to admin.

The Engineering Failure

This is a structure problem. It happens when systems are built without a deliberately designed response schema. Some developers return the raw database entity directly because it's easier. Some lack the domain knowledge to properly structure their data layer. The result is that internal data leaks into external responses.

This is also an Interface Segregation Principle violation. The response interface forces the consumer to receive data it should never have access to.

The Engineering Fix

Every API endpoint must have an explicit, deliberately designed response DTO. The response DTO contains only the fields the caller is authorized to receive. The domain entity never travels directly to the response.

Dart:

//Wrong returning the domain entity directly - exposes internal fields
Future<Response> getProfile(Request request) async {
  final user = await _userRepository.findById(userId);
  return Response.ok(jsonEncode(user.toJson())); // exposes everything
}

// Correct : explicit response DTO — only what the caller should see
class UserProfileResponse {
  final String id;
  final String firstName;
  final String lastName;
  final String email;

  const UserProfileResponse({
    required this.id,
    required this.firstName,
    required this.lastName,
    required this.email,
  });

  Map<String, dynamic> toJson() => {
    'id': id,
    'first_name': firstName,
    'last_name': lastName,
    'email': email,
    // isAdmin, internalScore, fraudRiskLevel — never here
  };
}

Future<Response> getProfile(Request request) async {
  final user = await _userRepository.findById(userId);

  final response = UserProfileResponse(
    id: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
  );

  return Response.ok(jsonEncode(response.toJson()));
}

C#:

// Wrong = returning the domain model directly
public async Task<IActionResult> GetProfile(string userId)
{
    var user = await _repository.FindByIdAsync(userId);
    return Ok(user); 
}

// Correct explicit response DTO
public record UserProfileResponse(
    string Id,
    string FirstName,
    string LastName,
    string Email);

public async Task<IActionResult> GetProfile(string userId)
{
    var user = await _repository.FindByIdAsync(userId);

    var response = new UserProfileResponse(
        user.Id,
        user.FirstName,
        user.LastName,
        user.Email
        // IsAdmin, InternalScore, FraudRiskLevel — never exposed
    );

    return Ok(response);
}

For incoming requests, use a request DTO that only accepts the fields a user is permitted to modify. Never bind directly to a domain entity in an update operation.

4. Unrestricted Resource Consumption

What it is

No rate limiting. A caller can spam critical APIs thousands of times per minute, such as with scraping, brute forcing, or denial of service attacks. The API accepts every request without any throttling or limit on consumption.

The Engineering Failure

Rate limiting is treated as optional or as a future concern. It's deferred to "when we need to scale" or "when we see abuse." By the time abuse is visible, the damage is already happening. A financial API without rate limiting can be brute-forced for valid account numbers, scraped for pricing data, or simply overwhelmed into unavailability.

The Engineering Fix

Rate limiting must be implemented at the API gateway layer, before requests reach the service layer. This isn't a service responsibility. The gateway is the right enforcement point because it can handle this for all services simultaneously without each service reimplementing it.

Different endpoints need different limits. Authentication endpoints need strict limits (5 attempts per 5 minutes per IP). Public read endpoints need moderate limits. Write operations on sensitive resources need strict limits.

Dart (middleware approach):

class RateLimitMiddleware {
  final RateLimiter _limiter;

  RateLimitMiddleware(this._limiter);

  Handler call(Handler innerHandler) {
    return (Request request) async {
      final clientIp = request.headers['x-forwarded-for'] ?? 'unknown';
      final endpoint = request.url.path;

      final limit = _getLimitForEndpoint(endpoint);
      final isAllowed = await _limiter.checkLimit(
        key: '$clientIp:$endpoint',
        maxRequests: limit.maxRequests,
        windowSeconds: limit.windowSeconds,
      );

      if (!isAllowed) {
        return Response(
          429,
          body: jsonEncode({'error': 'Rate limit exceeded'}),
          headers: {'Retry-After': '60'},
        );
      }

      return innerHandler(request);
    };
  }

  RateLimit _getLimitForEndpoint(String path) {
    if (path.contains('/auth/login')) {
      return RateLimit(maxRequests: 5, windowSeconds: 300);
    }
    if (path.contains('/transactions')) {
      return RateLimit(maxRequests: 100, windowSeconds: 60);
    }
    return RateLimit(maxRequests: 1000, windowSeconds: 60);
  }
}

C#:

// using AspNetCoreRateLimit
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("auth", limiterOptions =>
    {
        limiterOptions.PermitLimit = 5;
        limiterOptions.Window = TimeSpan.FromMinutes(5);
        limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        limiterOptions.QueueLimit = 0;
    });

    options.AddFixedWindowLimiter("standard", limiterOptions =>
    {
        limiterOptions.PermitLimit = 100;
        limiterOptions.Window = TimeSpan.FromMinutes(1);
    });

    options.RejectionStatusCode = 429;
});

// apply per controller
[EnableRateLimiting("auth")]
[HttpPost("login")]
public async Task<IActionResult> Login(LoginRequest request) { }

[EnableRateLimiting("standard")]
[HttpGet("transactions")]
public async Task<IActionResult> GetTransactions() { }

5. Broken Function Level Authorization (BFLA)

What it is

A regular user gets access to functions or endpoints that should only be accessible to admins or privileged roles. The frontend hides the button, but the endpoint is still there, wide open.

A regular user token is used to call an admin endpoint. It works. The attacker now has admin functionality with a non-admin account.

Security through obscurity is not security. Hiding admin resources at the UI level doesn't equal security.

The Engineering Failure

RBAC (Role-Based Access Control) is either not implemented or implemented incorrectly. Authorization checks are missing at the function level. The assumption is that if a user can't see the admin button in the UI, they can't call the admin API. This assumption is always wrong. Any developer tool can call any API endpoint directly, bypassing the UI entirely.

The Engineering Fix

Every function must check the caller's role before executing. This check must happen in the service layer, not the UI layer, and not the API gateway alone. The gateway can verify that a token is valid. Only the service layer knows what roles are required for each specific operation.

Dart:

class UserManagementService {
  final AuthContext _authContext;
  final UserRepository _repository;

  UserManagementService(this._authContext, this._repository);

  Future<Result<void, AppException>> deleteUser(String targetUserId) async {
    final currentUser = _authContext.currentUser;

    // role check - this must happen in the service layer
    if (!currentUser.hasRole(UserRole.admin)) {
      return Result.failure(
        AppException.forbidden('Admin role required for this operation'),
      );
    }

    await _repository.deleteUser(targetUserId);
    return Result.success(null);
  }

  Future<Result<List<User>, AppException>> getAllUsers() async {
    final currentUser = _authContext.currentUser;

    if (!currentUser.hasRole(UserRole.admin)) {
      return Result.failure(
        AppException.forbidden('Admin role required'),
      );
    }

    final users = await _repository.findAll();
    return Result.success(users);
  }
}

C#:

[ApiController]
[Route("api/admin/users")]
[Authorize]
public class UserManagementController : ControllerBase
{
    private readonly IUserManagementService _service;

    [HttpDelete("{userId}")]
    [Authorize(Roles = "Admin")] 
    public async Task<IActionResult> DeleteUser(string userId)
    {
        await _service.DeleteUser(userId);
        return NoContent();
    }

    [HttpGet]
    [Authorize(Roles = "Admin")]
    public async Task<IActionResult> GetAllUsers()
    {
        var users = await _service.GetAllUsers();
        return Ok(users);
    }
}

Role checks at the attribute level in C# and explicit role validation in the service layer in Dart both achieve the same thing: the check happens in code, not in the UI, and not in the API consumer's behavior.

6. Unrestricted Access to Sensitive Business Flows

What it is

Core business logic that should have strict guardrails has none. Users can bypass business rules and trigger flows that should never be allowed in their situation.

A sales agent creates a sale for a customer in an area that doesn't have coverage. The endpoint that creates the sale never verified that coverage exists. A business rule was violated. In financial terms, this causes loss. In operational terms, this causes the kind of problems that take months to untangle.

The Engineering Failure

Business logic isn't identified and isn't enforced at the domain layer. Domain-Driven Design exists precisely for this reason: business logic breaks or makes your application. When the domain layer isn't properly designed, and business rules aren't explicitly encoded, users can bypass them.

The guardrails are missing because the engineers didn't know the guardrails were supposed to exist there. This is a domain knowledge problem as much as a technical problem.

The Engineering Fix

Business rules belong in the domain layer. This is what Value Objects and domain entities enforce. A sale can't be created unless coverage is confirmed. That rule is encoded into the domain, not into the API endpoint or the UI.

Dart:

class Sale {
  final String agentId;
  final String customerId;
  final CoverageArea coverageArea;
  final SaleStatus status;

  Sale._({
    required this.agentId,
    required this.customerId,
    required this.coverageArea,
    required this.status,
  });

  // business rule enforced at domain creation - no coverage, no sale
  static Result<Sale, DomainException> create({
    required String agentId,
    required String customerId,
    required CoverageArea coverageArea,
  }) {
    if (!coverageArea.hasActiveCoverage) {
      return Result.failure(
        DomainException('Cannot create sale: customer area has no active coverage'),
      );
    }

    return Result.success(Sale._(
      agentId: agentId,
      customerId: customerId,
      coverageArea: coverageArea,
      status: SaleStatus.pending,
    ));
  }
}

C#:

public class Sale
{
    private Sale(string agentId, string customerId, CoverageArea area)
    {
        AgentId = agentId;
        CustomerId = customerId;
        CoverageArea = area;
        Status = SaleStatus.Pending;
    }

    public string AgentId { get; }
    public string CustomerId { get; }
    public CoverageArea CoverageArea { get; }
    public SaleStatus Status { get; private set; }

    // factory enforces the business rule no coverage, no sale
    public static Result<Sale> Create(
        string agentId,
        string customerId,
        CoverageArea coverageArea)
    {
        if (!coverageArea.HasActiveCoverage)
            return Result.Failure<Sale>(
                "Cannot create sale: no active coverage in this area");

        return Result.Success(new Sale(agentId, customerId, coverageArea));
    }
}

The endpoint that creates a sale calls the domain factory. The domain factory enforces the business rule. The rule can't be bypassed through the API because the API can't create a Sale that bypasses the factory.

7. Security Misconfiguration

What it is

A developer's personal debugging process shipped to production. Verbose error messages exposing stack traces. Debug endpoints left active. Permissive CORS allowing any origin. Sensitive data in logs. The developer's local configuration running in a production environment.

The Engineering Failure

These types of issues tend to happen when there's no separation between development, staging, and production configurations. There's no pipeline gate that catches misconfiguration before it reaches production. Each developer manages their own configuration, which means every developer's habits and debugging preferences can end up in production.

The Engineering Fix

Set up different workflows for every environment. The production pipeline must include static analysis, configuration validation, and linting that catches debug endpoints, permissive CORS, verbose error logging, and exposed secrets before a merge is allowed.

Dart (environment-aware error handling):

class ErrorHandler {
  final Environment _environment;

  ErrorHandler(this._environment);

  Response handleException(Object error, StackTrace stackTrace) {
 
    logger.error('Unhandled exception', error: error, stackTrace: stackTrace);

    if (_environment.isProduction) {
      
      return Response.internalServerError(
        body: jsonEncode({'error': 'An internal error occurred'}),
      );
    }

    
    return Response.internalServerError(
      body: jsonEncode({
        'error': error.toString(),
        'stackTrace': stackTrace.toString(),
      }),
    );
  }
}

C#:

app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        context.Response.StatusCode = 500;
        context.Response.ContentType = "application/json";

        var error = context.Features.Get<IExceptionHandlerFeature>();
        if (error != null)
        {
            // log internally with full details
            logger.LogError(error.Error, "Unhandled exception");
        }

        // return generic message to caller
        await context.Response.WriteAsync(
            JsonSerializer.Serialize(new { error = "An internal error occurred" })
        );
    });
});

// CORS - explicit allowed origins, never wildcard in production
builder.Services.AddCors(options =>
{
    options.AddPolicy("ProductionPolicy", policy =>
    {
        policy.WithOrigins(
            "https://app.yourproduct.com",
            "https://admin.yourproduct.com"
        )
        .AllowedMethods("GET", "POST", "PUT", "DELETE")
        .AllowedHeaders("Authorization", "Content-Type");
        
    });
});

CORS in production must use explicit allowed origins. Wildcard CORS in production is a direct security failure that allows any web page on the internet to make authenticated requests to your API using the visitor's credentials.

8. Improper Inventory Management

What it is

Deprecated APIs, decommissioned endpoints, and outdated API versions still running on the server. Nobody knows they exist and nobody owns them. But attackers find them and exploit them because old endpoints are often less secured than current ones.

The Engineering Failure

API lifecycle management is nobody's formal responsibility. Endpoints get created and features change. The old endpoint version is forgotten rather than retired. Over time, the API surface area grows with dead endpoints that still respond to requests, often without the security controls applied to newer endpoints.

The Engineering Fix

Someone must own the API inventory. This is a formal engineering responsibility, not an optional practice. Every API endpoint must be documented, versioned, and have a defined lifecycle: active, deprecated, or decommissioned.

Deprecated endpoints should return a response header indicating their deprecation date. Decommissioned endpoints must return 410 Gone, not continue to process requests.

Dart:

// deprecated endpoint wrapper
Handler deprecatedEndpoint({
  required Handler handler,
  required DateTime removalDate,
  required String replacementEndpoint,
}) {
  return (Request request) async {
    final response = await handler(request);

    // add deprecation headers so clients know to migrate
    return response.change(headers: {
      'Deprecation': 'true',
      'Sunset': HttpDate.format(removalDate),
      'Link': '<$replacementEndpoint>; rel="successor-version"',
      'Warning': '299 - "This endpoint is deprecated and will be removed on ${removalDate.toIso8601String()}"',
    });
  };
}

// decommissioned endpoint
Future<Response> decommissionedEndpoint(Request request) async {
  return Response(
    410,
    body: jsonEncode({
      'error': 'This endpoint has been permanently removed',
      'replacement': '/api/v2/accounts',
    }),
  );
}

C#:

// mark endpoints as deprecated using ApiVersion attributes
[ApiController]
[ApiVersion("1.0", Deprecated = true)]
[Route("api/v{version:apiVersion}/accounts")]
public class AccountsV1Controller : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetAccount(string id)
    {
        Response.Headers.Add("Deprecation", "true");
        Response.Headers.Add("Sunset", "Sat, 01 Jan 2027 00:00:00 GMT");
        Response.Headers.Add("Link", "</api/v2/accounts/{id}>; rel=\"successor-version\"");

        // still process the request during deprecation period
        return Ok(_service.GetAccount(id));
    }
}

// gone - permanent removal
[ApiController]
[Route("api/v1/legacy/accounts")]
public class LegacyAccountsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return StatusCode(410, new { error = "This endpoint has been permanently removed", replacement = "/api/v2/accounts" });
    }
}

9. Unsafe Consumption of APIs

What it is

Your application integrates with third-party services and trusts their data without validation or guardrails. Whatever the external API returns, your application processes it directly.

A third-party payment callback returns a transaction status. Your application trusts it without verifying the signature or validating the data structure. An attacker sends a forged callback to your callback URL. Your application processes it as legitimate.

The Engineering Failure

External services are treated as trusted by default. There's no defined contract for what valid data from an external service looks like. There's no validation layer between the external service response and the application's processing logic.

Trust is assumed rather than verified.

The Engineering Fix

Every integration with an external service must have a defined contract. The contract specifies what valid data looks like, what fields are required, and what the valid ranges and formats are. Every response from an external service is validated against this contract before any processing happens.

Dart:

class PaymentCallbackService {
  final String _webhookSecret;

  PaymentCallbackService(this._webhookSecret);

  Future<Result<PaymentStatus, AppException>> processCallback(
    Map<String, dynamic> payload,
    String signature,
    String rawBody,
  ) async {
    // step 1: verify the signature before processing anything
    final isValid = _verifySignature(rawBody, signature, _webhookSecret);
    if (!isValid) {
      logger.warning('Invalid webhook signature received');
      return Result.failure(
        AppException.unauthorized('Invalid webhook signature'),
      );
    }

    // step 2: validate the payload structure against our contract
    final validationResult = _validateCallbackPayload(payload);
    if (validationResult.isFailure) {
      logger.warning('Invalid callback payload: ${validationResult.error}');
      return Result.failure(validationResult.error!);
    }

    // step 3: only now do we trust and process the data
    final status = PaymentStatus.fromString(payload['status'] as String);
    return Result.success(status);
  }

  bool _verifySignature(String body, String signature, String secret) {
    final hmac = Hmac(sha256, utf8.encode(secret));
    final digest = hmac.convert(utf8.encode(body));
    final expectedSignature = 'sha256=${base64.encode(digest.bytes)}';
    return expectedSignature == signature;
  }

  Result<void, AppException> _validateCallbackPayload(
    Map<String, dynamic> payload,
  ) {
    if (!payload.containsKey('transaction_id')) {
      return Result.failure(
        AppException.validation('Missing required field: transaction_id'),
      );
    }
    if (!payload.containsKey('status')) {
      return Result.failure(
        AppException.validation('Missing required field: status'),
      );
    }
    final validStatuses = {'success', 'failed', 'pending'};
    if (!validStatuses.contains(payload['status'])) {
      return Result.failure(
        AppException.validation('Invalid status value: ${payload['status']}'),
      );
    }
    return Result.success(null);
  }
}

C#:

public class PaymentCallbackService
{
    private readonly string _webhookSecret;
    private readonly ILogger<PaymentCallbackService> _logger;

    public async Task<Result<PaymentStatus>> ProcessCallback(
        string rawBody,
        string signature,
        PaymentCallbackDto payload)
    {
        // verify signature first
        if (!VerifySignature(rawBody, signature))
        {
            _logger.LogWarning("Invalid webhook signature received");
            return Result.Failure<PaymentStatus>("Invalid webhook signature");
        }

        // validate payload
        if (string.IsNullOrEmpty(payload.TransactionId))
            return Result.Failure<PaymentStatus>("Missing transaction_id");

        var validStatuses = new[] { "success", "failed", "pending" };
        if (!validStatuses.Contains(payload.Status))
            return Result.Failure<PaymentStatus>($"Invalid status: {payload.Status}");

        return Result.Success(Enum.Parse<PaymentStatus>(payload.Status, true));
    }

    private bool VerifySignature(string body, string signature)
    {
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(_webhookSecret));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
        var expectedSignature = $"sha256={Convert.ToBase64String(hash)}";
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expectedSignature),
            Encoding.UTF8.GetBytes(signature)
        );
    }
}

It must be a standard of engineering to create verified contracts with external services before integration begins. Never trust, always verify.

10. Server-Side Request Forgery (SSRF)

What it is

An API accepts a URL as input and makes a server-side request to that URL. An attacker provides a URL that points to internal infrastructure: http://169.254.169.254/latest/meta-data/ (AWS metadata service), http://internal-database:5432, or http://admin-panel.internal. The server makes the request from inside the network, bypassing external firewalls.

Most payment systems take callback URLs or redirect URLs in the request. If the API forwards requests to those URLs without validation, it will happily make requests to internal infrastructure on behalf of the attacker.

The Engineering Failure

This is a design flaw that must be caught at the architectural layer, not the code layer. Any API that accepts URLs as input and makes server-side requests to those URLs is a potential SSRF target. The design decision to accept arbitrary URLs must come with the design decision to strictly validate those URLs.

The Engineering Fix

Any API that accepts a URL must validate it against a list of allowed domains before making any request. This is a design decision. The allowlist is part of the API's specification, not an afterthought.

Dart:

class WebhookService {
  // only these domains are allowed to receive callbacks
  static const _allowedDomains = {
    'api.yourpartner.com',
    'hooks.yourintegration.com',
    'callbacks.trustedservice.io',
  };

  Future<Result<void, AppException>> registerCallbackUrl(String url) async {
    // validate before storing or using
    final validationResult = _validateCallbackUrl(url);
    if (validationResult.isFailure) {
      return Result.failure(validationResult.error!);
    }

    await _webhookRepository.save(url);
    return Result.success(null);
  }

  Result<void, AppException> _validateCallbackUrl(String url) {
    final uri = Uri.tryParse(url);

    if (uri == null) {
      return Result.failure(AppException.validation('Invalid URL format'));
    }

    // must be HTTPS in production
    if (uri.scheme != 'https') {
      return Result.failure(
        AppException.validation('Callback URL must use HTTPS'),
      );
    }

    // must be in the allowlist
    if (!_allowedDomains.contains(uri.host)) {
      return Result.failure(
        AppException.validation(
          'Callback URL domain is not in the approved list',
        ),
      );
    }

    // block internal IP ranges explicitly
    if (_isInternalAddress(uri.host)) {
      return Result.failure(
        AppException.validation('Callback URL cannot point to internal addresses'),
      );
    }

    return Result.success(null);
  }

  bool _isInternalAddress(String host) {
    final privateRanges = [
      '127.', '10.', '172.16.', '172.17.', '172.18.',
      '192.168.', '169.254.', 'localhost', '0.0.0.0',
    ];
    return privateRanges.any((range) => host.startsWith(range));
  }
}

C#:

public class WebhookService
{
    private static readonly HashSet<string> AllowedDomains = new()
    {
        "api.yourpartner.com",
        "hooks.yourintegration.com",
        "callbacks.trustedservice.io"
    };

    public async Task<Result<bool>> RegisterCallbackUrl(string url)
    {
        var validationResult = ValidateCallbackUrl(url);
        if (!validationResult.IsSuccess)
            return Result.Failure<bool>(validationResult.Error);

        await _repository.SaveCallbackUrl(url);
        return Result.Success(true);
    }

    private Result<bool> ValidateCallbackUrl(string url)
    {
        if (!Uri.TryCreate(url, UriKind.Absolute, out var uri))
            return Result.Failure<bool>("Invalid URL format");

        if (uri.Scheme != "https")
            return Result.Failure<bool>("Callback URL must use HTTPS");

        if (!AllowedDomains.Contains(uri.Host))
            return Result.Failure<bool>("Domain not in approved list");

        if (IsInternalAddress(uri.Host))
            return Result.Failure<bool>("Internal addresses are not permitted");

        return Result.Success(true);
    }

    private bool IsInternalAddress(string host)
    {
        var internalPrefixes = new[]
        {
            "127.", "10.", "172.16.", "192.168.",
            "169.254.", "localhost", "0.0.0.0"
        };
        return internalPrefixes.Any(p => host.StartsWith(p));
    }
}

Engineering Vulnerabilities Beyond the OWASP List

The OWASP list covers the most critical and most common API vulnerabilities. But engineering experience surfaces additional patterns that can create serious security gaps.

APIs Called by Multiple Clients Without Domain Allowlisting

Some APIs called by multiple clients don't enforce which domains are allowed to call them. This makes it possible for people to share API keys and access resources from unauthorized origins.

In large-scale organizations, this is a major security gap that often goes unnoticed because the API technically works correctly from every client.

The fix: every API that accepts an API key must also validate the calling domain. API keys and allowed domains must be explicitly paired.

Exposing Secrets in Code and Logs

A developer leaves secret keys, public keys, and credentials in their code, in their repository, or on their machine. Adding files to .gitignore isn't enough. These datasets must be fetched from a trusted secrets manager at runtime, never stored in source code.

Organizations must use vaults, Azure App Configuration, AWS Secrets Manager, or equivalent systems. This must be an engineering standard, not a developer preference. The vault access pattern must be standardized so developers don't have to figure this out per project.

Microservices Talking to Each Other Without a Gateway

If you are building microservices, every communication between services must be treated as sensitive. There must be an API gateway that handles authentication for all services. Services must not trust each other implicitly. Every inter-service call must be authenticated.

Communication between microservices should use event brokers like Kafka for asynchronous flows, or mTLS for synchronous flows. No microservice should be directly accessible from the internet without going through the gateway.

Encryption Without Organizational Standards

Organizations must have standardized encryption algorithms. Not developer-chosen algorithms, not algorithm-of-the-week, and not whatever the developer found in a Stack Overflow answer. A staff-level engineering decision must specify which algorithm, which mode, and which key length is the organizational standard.

The vulnerabilities that come from ad-hoc encryption choices are serious: padding oracle attacks, weak key lengths, IV reuse, and stack traces during encryption failures that reveal internal implementation details to callers.

The engineering control: expose internally built packages or cloud functions for encryption that projects import rather than implement. Developers use the package. They never write encryption from scratch per project.

SQL Injection

SQL injection is 25 years old. It's been in existence since 1998. But it still happens because engineering standards aren't enforced.

It happens because developers build queries with string concatenation, taking user input and gluing it into a SQL string. The fix is parameterized queries or prepared statements, always. Raw SQL strings with user input concatenated are never acceptable.

Dart:

//Wrong  string concatenation — SQL injection vulnerability
Future<User?> findUser(String email) async {
  final query = "SELECT * FROM users WHERE email = '$email'";
  // attacker passes: admin@example.com' OR '1'='1
  // query becomes: SELECT * FROM users WHERE email = 'admin@example.com' OR '1'='1'
  // returns all users
  return await database.rawQuery(query);
}

// parameterized query — injection proof
Future<User?> findUser(String email) async {
  final results = await database.query(
    'users',
    where: 'email = ?',    
    whereArgs: [email],     
  );
  return results.isNotEmpty ? User.fromMap(results.first) : null;
}

C#:

// Wrong string concatenation
public async Task<User?> FindUser(string email)
{
    var query = $"SELECT * FROM Users WHERE Email = '{email}'";
    return await _context.Users.FromSqlRaw(query).FirstOrDefaultAsync();
}

// Correct parameterized query using EF Core
public async Task<User?> FindUser(string email)
{
    return await _context.Users
        .Where(u => u.Email == email)
        .FirstOrDefaultAsync();
}

// Correct parameterized raw SQL when needed
public async Task<User?> FindUserRaw(string email)
{
    return await _context.Users
        .FromSqlRaw("SELECT * FROM Users WHERE Email = {0}", email)
        .FirstOrDefaultAsync();
}

This is a major vulnerability that comes from core engineering decisions that should be under strict governance and compliance principles. These principles help establish development standards on projects and in organizations.

This could also be enforced at CI CD level. If static analysis in the CI/CD pipeline doesn't catch raw SQL string concatenation, your team should add it. This is a vulnerability class that should never reach production.

Conclusion

Every vulnerability in this list has one thing in common: it was preventable. Not by security tools applied after the fact, but by engineering discipline applied during design and development.

• BOLA is prevented by ID-aware authorization in the service layer.

• Broken authentication is prevented by proper token design and rate limiting.

• BOPLA is prevented by explicit response DTOs.

• Unrestricted resource consumption is prevented by rate limiting at the gateway.

• BFLA is prevented by role checks in code, not in the UI.

• Sensitive business flow exposure is prevented by domain-driven design and proper business rule enforcement.

• Security misconfiguration is prevented by environment-specific pipelines with automated gates.

• Improper inventory management is prevented by formal API lifecycle ownership.

• Unsafe API consumption is prevented by contract-first external integrations.

• SSRF is prevented by URL allowlisting as a design decision.

The pattern is consistent. Security isn't something you add to an application. It's something you engineer into the architecture from the beginning. Every decision in this article is an engineering decision: where does this check belong in the architecture? Which layer is responsible for this validation? What does the domain enforce? What does the gateway enforce? What does the pipeline catch?

Security by design isn't a security team's responsibility. It's an engineering team's responsibility. And it starts with understanding exactly what these vulnerabilities are, where they come from, and what the engineering standard is to prevent them.

As software engineers, this kind of next level thinking ensures our code doesn't fail these security tests.

Happy Secured Coding!

Then something strange happened. The number dropped: 120, then 55. That's when I knew something wasn't right.

I didn't break anything. Nothing changed in the package. People did not stop using it.

The window moved.

That was my introduction to one of the most misunderstood things about pub.dev: the 30-day rolling download figure it shows you is not a total. It is not a cumulative count. It is a window. And when the spike that got you those initial downloads falls outside that window, your number collapses, even though every single person who downloaded your package still has it installed.

That realization sent me down a rabbit hole. If pub.dev is only showing me a 30-day window, is there a way to see the full picture? Is there an API that exposes more? What is pub.dev actually doing under the hood?

This article is about what I found, and the tool I built out of it.

Table of Contents

• The Problem With the 30-Day Window

• How pub.dev Actually Calculates Downloads

• The APIs Behind pub.dev

• The Metrics Endpoint: The Full Story

• Building PubTrace

• How PubTrace Computes Its Numbers

• How This Helps Engineers

• A Note on the Unofficial Endpoint

• Conclusion

The Problem With the 30-Day Window

When you publish a package on pub.dev, the platform shows you a download count. If you look at any package page right now, you'll see a number labeled "downloads." Most developers assume this is the total number of times their package has been downloaded since it was published.

It is not.

pub.dev shows a 30-day rolling window. It counts how many times your package was downloaded in the last 30 days, and only the last 30 days. Everything before that is invisible.

Here is what that means in practice. You launch a package. You share it on Twitter, on LinkedIn, in developer communities. You get a spike. 200 downloads in the first week. Then things settle - maybe 10 downloads a week later.

At launch: 200 downloads are visible. After 5 weeks: 50 downloads are visible (only the last 30 days), and maybe 40 downloads after 10 weeks.

The number dropped by 75%, but your package was not abandoned or broken. It was quietly being used by the 200 people who already installed it. The downloads kept coming in, just at a slower rate than the initial spike.

The window moved and the spike fell out of it. But what was displayed on pub.dev made it look like your package was dying.

For someone tracking their package's growth, that can be misleading.

How pub.dev Actually Calculates Downloads

Before looking at the APIs, it is worth understanding how pub.dev counts downloads in the first place.

pub.dev counts how many times a package archive has been downloaded from its servers. When you run pub get or flutter pub get in a project, the pub tool checks your local PUB_CACHE first. If the package is already cached, it uses the cached version and no download happens. A download is only counted when the package is not in your cache.

This means the download count is not a measure of how many projects use your package. It is a measure of how many times developers had to fetch it fresh from the server. If 1000 developers use your package but they all already had it cached, the download count for that period is zero.

pub.dev is transparent about this. From their official scoring documentation: "The download count is not a direct measure of how many users a package has. A package can have high usage with relatively low download counts, because the pub client caches the downloads in the PUB_CACHE."

So the number you see on pub.dev is already an undercount of actual usage. And on top of that, it is only showing you the last 30 days of that undercount.

The APIs Behind pub.dev

When I realized pub.dev was only showing me a window, the first thing I did was look for APIs that might expose more. pub.dev has an official API documentation page at pub.dev offical api documentation. Let's walk through what is documented there.

The Score Endpoint

GET https://pub.dev/api/packages/{package}/score

This is the official endpoint that powers the download number you see on pub.dev. You can call it yourself right now:

curl https://pub.dev/api/packages/dart_exceptor/score

The response looks like this:

{
  "grantedPoints": 150,
  "maxPoints": 160,
  "likeCount": 5,
  "downloadCount30Days": 174,
  "tags": [
    "sdk:dart",
    "sdk:flutter",
    "platform:android",
    "platform:ios",
    "platform:linux",
    "platform:macos",
    "platform:web",
    "platform:windows"
  ]
}

downloadCount30Days is the number pub.dev shows on the package page. It is the 30-day rolling window. Nothing more, nothing less.

likeCount is how many developers have liked the package.

grantedPoints and maxPoints are the pub points score from the pana analyzer.

This endpoint is officially supported and officially documented. It will not change without announcement.

The Package Metadata Endpoint

GET https://pub.dev/api/packages/{package}

curl https://pub.dev/api/packages/dart_exceptor

This endpoint is part of the Hosted Pub Repository Specification V2, which is what the pub command line tool itself uses to resolve and download packages. It returns full package metadata: every published version, the pubspec for each version, the publish timestamps, and the package's overall information.

This is what PubTrace uses to determine when a package was first published. If a package was published six weeks ago, it only has six weeks of history, not 52. The article needs to be honest about that. PubTrace reads the first publish date from this endpoint and uses it to label charts accurately.

The response is large. The important fields for PubTrace are:

{
  "name": "dart_exceptor",
  "latest": {
    "version": "1.1.2",
    "published": "2026-07-12T10:00:00.000Z"
  },
  "versions": [
    {
      "version": "1.0.0",
      "published": "2026-07-01T10:00:00.000Z"
    }
  ]
}

The Publisher Endpoint

GET https://pub.dev/api/packages/{package}/publisher

curl https://pub.dev/api/packages/dart_exceptor/publisher

Response:

{
  "publisherId": null
}

Or for a verified publisher:

{
  "publisherId": "dart.dev"
}

PubTrace uses this to show who built the package. If the package is under a verified publisher, that is displayed. If not, the uploader's identity is shown as unverified.

This endpoint is officially documented and officially supported.

The Metrics Endpoint: The Full Story

Here is where things get interesting.

While exploring pub.dev's public surface, I found an endpoint that is not in the official API documentation but is publicly accessible and used by pub.dev itself internally:

GET https://pub.dev/api/packages/{package}/metrics

curl https://pub.dev/api/packages/dart_exceptor/metrics

pub.dev is explicit about this distinction. From their official api documentation: "pub.dev may expose API endpoints that are available publicly, but unless they are documented here, we don't consider them as officially supported, and may change or remove them without notice."

The metrics endpoint is one of these. It is public. Anyone can call it. But it is not officially supported, which means it could change. PubTrace uses it because it is the only source of the data that matters, and every number it produces from this endpoint is independently verifiable by anyone with a terminal.

The response from this endpoint includes a scorecard object with weeklyVersionDownloads. This is what pub.dev's own weekly chart is powered by. It contains 52 entries, one for each week over the last year, newest first. Each entry breaks down downloads by version range: total downloads, major version range, minor version range, and patch version range.

A simplified version of the relevant section looks like this:

{
  "scorecard": {
    "weeklyVersionDownloads": {
      "totalWeeklyDownloads": [45, 38, 62, 71, 28, 19, 33, ...],
      "majorRangeWeeklyDownloads": [...],
      "minorRangeWeeklyDownloads": [...],
      "patchRangeWeeklyDownloads": [...]
    }
  }
}

The array has 52 entries. Index 0 is the most recent week. Index 51 is the oldest week in the dataset.

pub.dev shows you the sum of roughly the last 4 entries in totalWeeklyDownloads (approximately 30 days). The full 52 entries are sitting right there in the API response. Unused. Invisible to anyone looking at the pub.dev UI.

That is when I decided to build something.

Building PubTrace

When I understood what the metrics endpoint exposed, the question was simple: why call these APIs manually every time I want to check a package's history, when I could build something the entire Dart and Flutter community could use?

That is how PubTrace was born.

PubTrace is a free tool that shows the full 52-week download history of any Dart or Flutter package on pub.dev. No account needed. No sign up. Just go to pubtrace.dev, type in any package name, and see the complete picture that pub.dev does not show you.

What PubTrace Does

PubTrace is a free, open tool available at https://pubtrace.dev. You type in any package name published on pub.dev and PubTrace shows you:

The cumulative download chart. A 52-week line chart showing total downloads growing over time. Not a 30-day window. Not a weekly bar chart. A running total that shows the true growth trajectory of any package.

The real numbers. Total downloads across the full history window, likes, pub points, and the publisher information , all pulled directly from pub.dev's own APIs at the moment you request the page.

How old the data is. PubTrace shows you when the data was last fetched. The cache is explicit. There is no pretense of real-time data. It is fresh within an hour.

The verify panel. Every page has a verify section showing the exact curl commands used to fetch the data. You can copy any command, run it in your terminal, and reproduce every number yourself. This is the most important feature on PubTrace. It means you never have to trust PubTrace. You can verify it yourself, right now.

Here is what looking up dart_exceptor on PubTrace shows compared to pub.dev:

pub.dev shows: 174 downloads (30-day window) PubTrace shows: 174 downloads cumulatively over 8 weeks, with a chart showing exactly when the downloads came in and how the number grew

Both numbers are sourced from the same pub.dev data. PubTrace just shows the full picture.

Any developer, any package, no account required. Go to https://pubtrace.dev and try it.

The Architecture Decision: No Database

The most important architectural decision in PubTrace was to not store any data.

Every number you see on PubTrace is fetched live from pub.dev's APIs at the moment you request a package. There is no database of download history. There is no historical record. Every chart is computed fresh, on the server, from pub.dev's own data, right now.

This was a deliberate choice for one reason: honesty.

If PubTrace stored its own historical data, you would have to trust that PubTrace's data is correct. You would have to trust that I collected it accurately, that I did not have downtime during a collection window, that my storage was not corrupted. You would be trusting a middleman.

With the no-database architecture, you never have to trust PubTrace. Every number PubTrace shows you can be reproduced with a curl command. PubTrace is a computation layer on top of pub.dev's own data, not a source of truth in its own right.

The 1-Hour Cache

Fetching live from pub.dev on every request would be wasteful and disrespectful to pub.dev's servers. PubTrace caches responses for one hour. This means:

If you look up dart_exceptor at 3pm, PubTrace fetches from pub.dev and caches the result. If someone else looks up dart_exceptor at 3:30pm, they get the cached result. At 4pm, the cache expires and the next request fetches fresh data.

The cache is explicit and displayed to users. You can see when the data was last fetched. There is no pretense that the data is real-time. It is fresh within an hour.

The Verify Panel

Every package page on PubTrace has a Verify panel. It shows the exact curl commands used to fetch the data for that package. Any developer can copy those commands, run them in their terminal, and reproduce every number PubTrace shows.

This is not just a nice feature. It is the entire point. PubTrace's value is not that you trust it. It is that you do not have to.

How PubTrace Computes Its Numbers

Understanding the computation helps you trust the output.

The Cumulative Chart

PubTrace takes the 52 weekly download entries from the metrics endpoint and computes a running total. Week 52 is the starting point. Each subsequent week adds its downloads to the running total. The result is a cumulative growth chart that shows the true trajectory of a package's download history.

This is fundamentally different from what pub.dev shows. pub.dev shows a bar chart of weekly downloads, which makes a consistent package with steady 30 downloads per week look flat. PubTrace shows a line chart of cumulative downloads, which shows that same package growing steadily, week after week.

Both are showing the same data. The cumulative view shows the full story.

The Young Package Rule

If a package was published less than 52 weeks ago, PubTrace labels the chart with the actual number of weeks of data available. A package published 8 weeks ago will show 8 weeks of history, clearly labeled. PubTrace does not extrapolate or estimate missing weeks. It shows exactly what is in the data and nothing more.

The Truncated History Rule

The metrics endpoint stores 52 weeks of data. For packages that are more than a year old, the data before 52 weeks ago is simply not available from this endpoint. PubTrace is transparent about this. The chart shows 52 weeks. It does not claim to show lifetime downloads from day one for old packages.

For packages younger than 52 weeks, the chart shows everything since launch, which is the complete history.

The Sanity Check

Every computation PubTrace does can be verified against the raw API response. The cumulative total for a package is the sum of all 52 entries in totalWeeklyDownloads. You can run the curl command yourself, sum the array, and get the same number PubTrace shows. If they differ, something is wrong, and I'd like to know about it.

How This Helps Engineers

For Package Authors

The most immediate value is understanding your own package's real growth. The number on pub.dev today is not your package's story. It is a snapshot of the last 30 days. PubTrace shows you the full 52-week trajectory so you can see whether your package is growing, stable, or declining, and make decisions based on real data.

For Portfolio and Evidence

A lot of engineers in the Dart and Flutter community are building portfolios and applying for senior roles that require demonstrating community contribution and technical impact. A download count of 55 on pub.dev is not compelling evidence. A cumulative chart showing 174 downloads growing steadily over 8 weeks, with a verifiable source, tells a very different story.

PubTrace gives you the full picture and gives you the tools to prove it. The verify panel exists specifically so that the numbers are independently confirmable. There is no need to trust you. The data speaks for itself and it is verifiable from pub.dev's own APIs.

For the Community

Any developer can look up any public package on pub.dev through PubTrace. You can compare packages side by side. You can see how a package grew over its first year. You can make more informed decisions about which packages to depend on, not just based on pub.dev's current 30-day window, but based on the full trajectory.

For Dart and Flutter Ecosystem Transparency

The Dart and Flutter ecosystem is growing. More packages are being published every week. But the tools for understanding that growth have been limited to pub.dev's 30-day window and its weekly bar chart. PubTrace adds a layer of historical visibility that was always in the data but never surfaced in the UI.

Every calculation is derived from pub.dev's own public APIs. Nothing is invented. Nothing is estimated beyond what the API provides. The goal is honest, quality data that any engineer can verify.

Conclusion

pub.dev's 30-day rolling download figure tells you something. It does not tell you everything. For package authors trying to understand their growth and for the community trying to make informed decisions about dependencies, that window is not enough.

The data for a fuller picture exists. pub.dev exposes weekly download history through its metrics endpoint. The official APIs expose metadata, publisher information, and scores. PubTrace combines all of these, computes a cumulative view, and presents it in a way that is honest, verifiable, and useful.

No database. No estimates. No trust required. Every number traceable to a curl command against pub.dev's own APIs.

If you publish packages on pub.dev, your numbers are probably better than pub.dev is making them look. Go see the real story.

Visit https://pubtrace.dev. Type in your package name or any package you are curious about. Check the verify panel. Run the curl commands yourself. Share the link with your team.

The data was always there. Now it is visible.

One of the patterns that explicitly helps you manage complex hierarchical scenarios is the Composite Design Pattern.

So what does this pattern really do?

Let me give you an example. You have a dataset and you want a common interface to be responsible for managing that dataset, ensuring one method is used for everything. You also want to allow a blueprint to manage this data and allow the data to grow as much as it can. This is a great fit for the Composite Design Pattern in object composition.

Here are some other clear use cases:

• A shopping cart contains individual items. It also has bundles of items sold together. Both need a price.

• A tax system has individual taxpayers. It also has family groups and corporate groups. All of them need tax calculated, discounts applied, and year-to-date totals computed.

• A file system has individual files. It also has folders that contain files or other folders. Both need a size.

The naïve approach is to write separate logic for individuals and groups, then add a type check wherever you need to handle both. But the logic diverges. The type checks multiply. And every new operation means updating both branches. The code becomes harder to extend and harder to trust.

The Composite Design Pattern eliminates this entirely. It defines a common interface that both individual objects and groups implement. The calling code never checks types. It calls the same method on a leaf or a composite and gets the correct result either way.

Table of Contents

• Prerequisites

• What is the Composite Design Pattern?

• The Three Layers

• Real World Example One: Shopping Cart Pricing

• Real World Example Two: Tax Management

• The Power of Nested Composites

• The Composite Pattern in C#

• When to Use the Composite Pattern

• When Not to Use It

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Object-oriented programming: abstract classes, interfaces, and inheritance

• What a design pattern is at a conceptual level

• Basic Dart or C# syntax

You don't need prior experience with structural design patterns. This article introduces the Composite pattern from first principles with real production examples.

What is the Composite Design Pattern?

The Composite Design Pattern is a structural design pattern. Where creational patterns deal with how objects are created and behavioral patterns deal with how objects communicate, structural patterns deal with how objects are composed and related to each other.

The Composite pattern specifically deals with part-whole hierarchies. It lets you compose objects into tree structures and then work with those trees as if every node in the tree is the same type of thing.

The core idea is deceptively simple: define a common interface, make individual objects implement it, and make groups of objects implement it too. Now everything in the hierarchy responds to the same methods and the calling code never needs to distinguish between a leaf and a composite.

This is what "treating individual objects and groups through a unified interface" means in practice. One method call, any object in the hierarchy, correct result regardless of whether you are calling it on a single item or a nested group containing hundreds of items.

The Three Layers

The Composite pattern has three distinct layers. Understanding each one before looking at code makes the implementation much clearer.

The Component Layer

This is the abstract class or interface that defines the contract for every object in the hierarchy. It declares the methods that both individual objects and groups must implement.

The Component is what makes uniform treatment possible: because everything in the hierarchy implements this interface, everything responds to the same method calls.

The Leaf Layer

A Leaf is a concrete implementation of the Component. It represents an individual object with no children, like a single item in a shopping cart, a single taxpayer, or a single file. The Leaf implements the Component methods with its own specific logic.

The Composite Layer

A Composite is also a concrete implementation of the Component. But unlike a Leaf, it holds a collection of children. Each child is a Component, which means each child can be either a Leaf or another Composite.

The Composite implements the Component methods by delegating to its children and aggregating the results.

The relationship between these layers is what enables the tree structure and the uniform interface simultaneously.

Real World Example One: Shopping Cart Pricing

A shopping cart needs to calculate prices. Individual items have their own prices. Bundles group multiple items and their price is the sum of their contents. Both need to respond to getPrice().

The Component

abstract class PriceComponent {
  double getPrice();
}

PriceComponent is the contract. Every object in the cart hierarchy must implement getPrice(). That is the entire interface: one method that's uniform across all objects.

The Leaf

class CartItem extends PriceComponent {
  final int id;
  final String name;
  final double price;

  CartItem({required this.id, required this.name, required this.price});

  @override
  double getPrice() {
    return price;
  }
}

CartItem is the Leaf. It represents a single item in the cart. Its getPrice() returns its own price directly. There's no delegation or children. Just its own value.

The Composite

class ItemBundle extends PriceComponent {
  final int bundleId;
  final String bundleName;
  final List<PriceComponent> _items = [];

  ItemBundle({required this.bundleId, required this.bundleName});

  void add(PriceComponent component) {
    _items.add(component);
  }

  void remove(PriceComponent component) {
    _items.remove(component);
  }

  @override
  double getPrice() {
    return _items.fold(0, (total, item) => total + item.getPrice());
  }
}

ItemBundle is the Composite. It holds a list of PriceComponent children. Its getPrice() delegates to its children using fold, summing up whatever each child returns.

The critical detail: _items is a List<PriceComponent>, not a List<CartItem>. This means an ItemBundle can contain both CartItem leaves and other ItemBundle composites. The hierarchy can nest as deeply as needed.

Using It

void main() {
  
  final burger = CartItem(id: 1, name: 'Burger', price: 5.99);
  final fries = CartItem(id: 2, name: 'Fries', price: 2.99);
  final drink = CartItem(id: 3, name: 'Drink', price: 1.99);
  final apple = CartItem(id: 4, name: 'Apple', price: 0.99);

 
  final comboMeal = ItemBundle(bundleId: 1, bundleName: 'Combo Meal');
  comboMeal
    ..add(burger)
    ..add(fries)
    ..add(drink);


  final cart = ItemBundle(bundleId: 0, bundleName: 'My Cart');
  cart
    ..add(comboMeal) 
    ..add(apple);    

  // same method call on everything
  print('Burger: \$${burger.getPrice()}');           
  print('Combo Meal: \$${comboMeal.getPrice()}');    
  print('Full Cart: \$${cart.getPrice()}');          
}

burger.getPrice() calls the Leaf implementation directly. comboMeal.getPrice() calls the Composite implementation which delegates to its three children. cart.getPrice() calls the Composite implementation which delegates to the combo meal composite and the apple leaf.

The calling code treats all of them identically: getPrice(), result, done.

Real World Example Two: Tax Management

This example shows the Composite pattern applied to a more complex domain. A tax management system needs to calculate tax amounts, apply discounts, and compute year-to-date totals. These calculations need to work for individual taxpayers and for groups of taxpayers through exactly the same interface.

The Component

abstract class TaxManager {
  num getTaxAmount();
  num getTaxDiscount();
  num getTotalTaxYTD();
}

TaxManager defines three methods. Every object in the tax hierarchy must implement all three. A single taxpayer implements them with their own data. A group implements them by aggregating across all members. The calling code calls any of these methods on any object and gets the correct result.

The Leaf

class SingleUser extends TaxManager {
  final num _amount;
  final List<num> _allTaxes;

  SingleUser(this._amount, this._allTaxes);

  @override
  num getTaxAmount() {
    return _amount;
  }

  @override
  num getTaxDiscount() {
   
    return _amount % 2 == 0 ? _amount : (_amount / 2);
  }

  @override
  num getTotalTaxYTD() {
    num total = 0;
    for (final tax in _allTaxes) {
      total += tax;
    }
    return total;
  }
}

SingleUser is the Leaf. It represents one individual taxpayer. _amount is their current tax amount. _allTaxes is a list of their tax payments over the year. Each method operates on this person's data only.

getTaxDiscount() applies a simple discount rule: even amounts receive the full amount, odd amounts receive half. This rule lives on the individual and is automatically propagated through any group that contains this user.

getTotalTaxYTD() sums the user's historical tax payments to produce their year-to-date total.

The Composite

class UserGroup extends TaxManager {
  final String groupName;
  final List<TaxManager> _members = [];

  UserGroup(this.groupName);

  void add(TaxManager member) {
    _members.add(member);
  }

  void remove(TaxManager member) {
    _members.remove(member);
  }

  @override
  num getTaxAmount() {
    return _members.fold(0, (total, member) => total + member.getTaxAmount());
  }

  @override
  num getTaxDiscount() {
    return _members.fold(0, (total, member) => total + member.getTaxDiscount());
  }

  @override
  num getTotalTaxYTD() {
    return _members.fold(0, (total, member) => total + member.getTotalTaxYTD());
  }
}

UserGroup is the Composite. It holds a list of TaxManager members. Each method delegates to every member and folds the results.

Notice that _members is typed as List<TaxManager>, not List<SingleUser>. This means a UserGroup can contain individual SingleUser leaves or other UserGroup composites. A family group can contain individual members. A corporate group can contain family groups. The hierarchy can grow as needed and the interface never changes.

Using It

void main() {
  
  final seyisTax = SingleUser(100000, List.generate(12, (_) => 20000));
  final ronkesTax = SingleUser(5000, List.generate(12, (_) => 50000));
  final inisTax = SingleUser(20000, List.generate(12, (_) => 20000));
  final tiwasTax = SingleUser(10000, List.generate(12, (_) => 10000));

 
  print('Seyi tax amount: ${seyisTax.getTaxAmount()}');       
  print('Ronke tax amount: ${ronkesTax.getTaxAmount()}');     
  print('Seyi discount: ${seyisTax.getTaxDiscount()}');        
  print('Seyi YTD: ${seyisTax.getTotalTaxYTD()}');            

  // build a family group
  final fatunmoles = UserGroup('Fatunmoles');
  fatunmoles
    ..add(seyisTax)
    ..add(ronkesTax)
    ..add(inisTax)
    ..add(tiwasTax);

 
  
  print('Total tax: ${fatunmoles.getTaxAmount()}');      
  print('Total discount: ${fatunmoles.getTaxDiscount()}'); 
  print('Total YTD: ${fatunmoles.getTotalTaxYTD()}');    

  // a second family group
  final child1 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child2 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child3 = SingleUser(100000, List.generate(12, (_) => 20000));

  final unknownFamily = UserGroup('UnknownFamily');
  unknownFamily
    ..add(child1)
    ..add(child2)
    ..add(child3);


  print('Tax: ${unknownFamily.getTaxAmount()}');
  print('Discount: ${unknownFamily.getTaxDiscount()}');
  print('YTD: ${unknownFamily.getTotalTaxYTD()}');
}

The same three method calls work on seyisTax (one person), fatunmoles (four people), and unknownFamily (three people). The calling code is identical. The results are correct for each level of the hierarchy.

The Power of Nested Composites

The most powerful aspect of the Composite pattern is that a Composite can contain other Composites. A UserGroup can contain other UserGroup objects. This enables deep hierarchies while maintaining the same uniform interface at every level.

void demonstrateNesting() {
  
  final seyi = SingleUser(100000, List.generate(12, (_) => 20000));
  final ronke = SingleUser(5000, List.generate(12, (_) => 50000));
  final ini = SingleUser(20000, List.generate(12, (_) => 20000));
  final tiwa = SingleUser(10000, List.generate(12, (_) => 10000));

  final child1 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child2 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child3 = SingleUser(100000, List.generate(12, (_) => 20000));

  // family groups
  final fatunmoles = UserGroup('Fatunmoles');
  fatunmoles
    ..add(seyi)
    ..add(ronke)
    ..add(ini)
    ..add(tiwa);

  final unknownFamily = UserGroup('UnknownFamily');
  unknownFamily
    ..add(child1)
    ..add(child2)
    ..add(child3);

  // a composite that contains other composites
  // both families treated as one unit
  final allFamilies = UserGroup('AllFamilies');
  allFamilies
    ..add(fatunmoles)    
    ..add(unknownFamily); 

  // same interface, now covers all 7 people across both families
  print('All families combined:');
  print('Total tax: ${allFamilies.getTaxAmount()}');
  print('Total discount: ${allFamilies.getTaxDiscount()}');
  print('Total YTD: ${allFamilies.getTotalTaxYTD()}');
}

allFamilies.getTaxAmount() traverses the entire tree: it asks fatunmoles for its total, which asks each of its four members, and asks unknownFamily for its total, which asks each of its three members. Seven people, one method call. The caller doesn't know the depth of the tree or how many members exist at any level.

This is where the pattern demonstrates its full value. You can build an organization with divisions, departments, teams, and individuals, all implementing the same TaxManager interface, and call getTaxAmount() on the organization to get the total for every single person in it. Or call it on a single department. Or call it on a single person. The interface is always the same.

The Composite Pattern in C#

The same pattern in C# shows that this is a universal structural principle. Here is the tax management system replicated in C# for a corporate payroll context.

The Component

public interface ITaxManager
{
    decimal GetTaxAmount();
    decimal GetTaxDiscount();
    decimal GetTotalTaxYTD();
}

The Leaf

public class Employee : ITaxManager
{
    private readonly string _name;
    private readonly decimal _taxAmount;
    private readonly List<decimal> _yearlyTaxes;

    public Employee(string name, decimal taxAmount, List<decimal> yearlyTaxes)
    {
        _name = name;
        _taxAmount = taxAmount;
        _yearlyTaxes = yearlyTaxes;
    }

    public decimal GetTaxAmount() => _taxAmount;

    public decimal GetTaxDiscount()
    {
        return _taxAmount % 2 == 0 ? _taxAmount : _taxAmount / 2;
    }

    public decimal GetTotalTaxYTD()
    {
        return _yearlyTaxes.Sum();
    }
}

The Composite

public class Department : ITaxManager
{
    private readonly string _name;
    private readonly List<ITaxManager> _members = new();

    public Department(string name)
    {
        _name = name;
    }

    public void Add(ITaxManager member) => _members.Add(member);
    public void Remove(ITaxManager member) => _members.Remove(member);

    public decimal GetTaxAmount()
    {
        return _members.Sum(m => m.GetTaxAmount());
    }

    public decimal GetTaxDiscount()
    {
        return _members.Sum(m => m.GetTaxDiscount());
    }

    public decimal GetTotalTaxYTD()
    {
        return _members.Sum(m => m.GetTotalTaxYTD());
    }
}

Using It in C#

var alice = new Employee("Alice", 150000, Enumerable.Repeat(25000m, 12).ToList());

var bob = new Employee("Bob", 80000, Enumerable.Repeat(15000m, 12).ToList());

var carol = new Employee("Carol", 120000, Enumerable.Repeat(20000m, 12).ToList());

var dave = new Employee("Dave", 95000, Enumerable.Repeat(18000m, 12).ToList());


var engineering = new Department("Engineering");
engineering.Add(alice);
engineering.Add(bob);


var design = new Department("Design");
design.Add(carol);
design.Add(dave);


var company = new Department("TechCorp");
company.Add(engineering);
company.Add(design);


Console.WriteLine($"Alice tax: {alice.GetTaxAmount()}");
Console.WriteLine($"Engineering total: {engineering.GetTaxAmount()}");

// entire company — traverses all departments and all employees
Console.WriteLine($"Company total tax: {company.GetTaxAmount()}");
Console.WriteLine($"Company total discount: {company.GetTaxDiscount()}");
Console.WriteLine($"Company YTD: {company.GetTotalTaxYTD()}");

The structure is identical to the Dart implementation. ITaxManager is the Component, Employee is the Leaf, and Department is the Composite. The hierarchy nests: a Department of Departments forms the company. The calling code calls the same three methods on any node in the tree and gets the correct aggregated result.

This is the same pattern solving the same problem in a different language. The structural principle is universal.

When to Use the Composite Pattern

Use the Composite pattern when you have a part-whole hierarchy where both parts and wholes need to be treated uniformly.

It's also a good choice when the calling code shouldn't need to distinguish between individual objects and groups. If you find yourself writing writing conditional statements to check if an object is a group or single frequently, that's a signal that Composite would eliminate those branches.

It's helpful when the hierarchy needs to be flexible and deeply nestable. File systems, organizational charts, UI component trees, category hierarchies, tax systems, or shopping carts with bundles: any domain where containers can hold other containers benefits from Composite.

And it's useful when new types of leaves or composites might be added in the future. Because everything implements the same Component interface, adding a new type of leaf (a CorporateTaxpayer alongside SingleUser) or a new type of composite (a TaxBracketGroup) means creating one new class. The calling code and all existing classes remain unchanged.

When Not to Use It

Avoid Composite when the hierarchy is simple and unlikely to nest. If you have individual items and exactly one level of grouping with no nesting, the pattern adds abstraction that a simpler approach would not require.

It's also not a good choice when individual objects and groups genuinely need different interfaces. If groups need many additional methods that individuals never need, forcing them into the same interface creates an interface that's too broad and violates the Interface Segregation Principle.

Avoid it when performance is critical and the overhead of recursive traversal matters. Deep hierarchies with millions of nodes traversed frequently might benefit from a different approach that caches aggregated results.

Conclusion

The Composite Design Pattern solves a fundamental problem in hierarchical systems: how do you perform the same operation on both individual objects and groups of objects without writing two separate implementations or littering your code with type checks?

The answer is a common interface. Every object in the hierarchy implements the same contract. Individual objects implement it with their own data. Groups implement it by delegating to their children and aggregating the results. The calling code calls the same method and gets the correct answer regardless of whether it's talking to a leaf or a composite containing a hundred nested levels.

The shopping cart example shows this for pricing: one getPrice() method, called identically on a single item or a bundle containing other bundles. The tax management example shows this for a domain with multiple operations: getTaxAmount(), getTaxDiscount(), and getTotalTaxYTD() called identically on a single taxpayer, a family group, or a composite of family groups.

The nested composite demonstration shows the full power: a UserGroup containing other UserGroups, each containing SingleUsers, all responding to the same interface and producing correct aggregated results at every level. Seven people, one method call. The tree is traversed automatically.

C# shows the same principle in a corporate payroll context: employees as leaves, departments as composites, and the company as a composite of departments. One interface, any level of the hierarchy. Correct result every time.

The Composite pattern doesn't eliminate complexity. It contains it. The complexity of aggregating results across a deep hierarchy lives inside the Composite's fold calls, not scattered across the calling code. The calling code stays clean. The hierarchy stays flexible. New types can be added without changing anything that already exists.

That's the structural discipline the Composite pattern provides.

Happy Coding!

Other objects aren't simple at all, like a carousel widget that needs an item count, an item builder function, a controller, a height, a viewport fraction, autoplay settings, page change callbacks, and infinite scroll configuration. Or like an HTTP request that needs a URL, headers, authentication tokens, a body, a timeout, and retry logic. Or a notification that needs a title, body, icon, channel, priority, sound, vibration, and action buttons.

When you need to construct objects like these, the naïve approach is a constructor with many parameters. It works, but it creates problems that compound as the object grows more complex. Parameters become hard to tell apart. Optional parameters require null checks everywhere. The order of arguments matters and is easy to get wrong. The constructor call becomes a wall of values that nobody wants to read or maintain.

The Builder Design Pattern solves this. It separates the construction of a complex object from its representation, allowing the same construction process to create different configurations through a readable, step-by-step interface.

Table of Contents

• Prerequisites

• What is the Builder Pattern?

• The Problem It Solves

• Core Components

• Method Chaining: The Fluent Interface

• Real World Example One: Flutter Carousel Builder

• Real World Example Two: HTTP Request Builder

• The Builder Pattern in C#

• Builder vs Constructor vs Factory

• When to Use the Builder Pattern

• When Not to Use It

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Object-oriented programming: classes, constructors, and methods

• What a design pattern is at a conceptual level

• Basic Dart or C# syntax

You don't need prior experience with design patterns. This article introduces the Builder pattern from first principles.

What is the Builder Pattern?

The Builder Pattern is a creational design pattern. Creational patterns deal with how objects are created. The Builder pattern specifically deals with the construction of complex objects that require many configuration steps.

The pattern separates two concerns that are often tangled together in simpler code: what an object is, and how it's built. The object holds its own data and behavior. The Builder holds the construction logic and accumulates the configuration step by step before producing the final object.

The result is a construction process that reads like a description of what you're building rather than a list of values to pass to a constructor.

The Problem It Solves

Here's what constructing a complex widget looks like without the Builder pattern:

// constructing a carousel directly — hard to read, easy to get wrong
CarouselSlider.builder(
  options: CarouselOptions(
    height: 200,
    viewportFraction: 0.97,
    enableInfiniteScroll: false,
    autoPlayCurve: Curves.easeIn,
    enlargeCenterPage: true,
    pauseAutoPlayOnManualNavigate: true,
    onPageChanged: onPageChanged,
    autoPlay: false,
  ),
  itemBuilder: (context, index, realIndex) => AdCard(ad: ads[index]),
  itemCount: ads.length,
)

This works. But look at what happens when you need to create two different carousels in the same screen: one for ads and one for account balances. Both need different heights, viewport fractions, item builders, and item counts. You copy the entire construction block, modify the values, and now you have two walls of configuration that are visually similar but subtly different.

When a new requirement comes in to add autoplay to the ads carousel but not the balance carousel, you have to find the right block, modify it carefully, and hope you're modifying the right one.

The deeper problem is that the construction logic is scattered across the codebase. Every place a carousel is created knows all the details of carousel construction. There's no single place where that knowledge lives.

The Builder pattern collects construction knowledge into one place and exposes it through a clean interface.

Core Components

The Builder pattern has three components.

The Product

The complex object being built. It doesn't know about the Builder. It holds its configuration and has behavior based on that configuration. The Product is often constructed with a private constructor so it can only be created by its Builder.

The Builder

The class responsible for accumulating configuration and producing the Product. Each method on the Builder configures one aspect of the Product and returns the Builder itself. This return is what enables method chaining. The final method on the Builder produces the completed Product.

The Director (optional)

A class that knows how to use a Builder to produce specific pre-configured Products. The Director encodes the knowledge of how to build common configurations so callers don't need to know the details. In practice, a Factory method often serves this role.

Method Chaining: The Fluent Interface

Method chaining is the technique that makes Builder code read naturally. Each Builder method returns this (the Builder itself) so the next method call can follow immediately on the same line or the next line.

// without method chaining
final builder = RequestBuilder();
builder.setUrl('https://api.example.com/users');
builder.setMethod('POST');
builder.addHeader('Authorization', 'Bearer $token');
builder.setBody({'name': 'John'});
final request = builder.build();

// with method chaining
final request = RequestBuilder()
    .setUrl('https://api.example.com/users')
    .setMethod('POST')
    .addHeader('Authorization', 'Bearer $token')
    .setBody({'name': 'John'})
    .build();

Both produce exactly the same result. The chained version reads like a sentence describing the request. The unchained version is a sequence of imperative statements.

Method chaining is sometimes called a Fluent Interface. The name comes from how the code reads: fluently, like natural language, from left to right or top to bottom.

Real World Example One: Flutter Carousel Builder

This is a real production implementation from a Flutter fintech application. The app needs to show two different carousels on the dashboard: one for promotional ads and one for account balances. Each carousel has a different configuration but shares the same underlying construction mechanism.

The Configuration Objects

import 'package:flutter/widgets.dart';
import 'package:equatable/equatable.dart';
import 'package:carousel_slider/carousel_slider.dart';

class CarouselArgs extends Equatable {
  final CarouselSliderController? carouselController;
  final int itemCount;
  final Widget Function(BuildContext, int, int) itemBuilder;
  final CarouselOptions options;

  const CarouselArgs({
    this.carouselController,
    required this.itemCount,
    required this.itemBuilder,
    required this.options,
  });

  @override
  List<Object?> get props => [
        carouselController,
        itemCount,
        itemBuilder,
        options,
      ];
}

class CarouselOptions extends Equatable {
  final double? height;
  final double? viewPortFraction;
  final bool? enableInfiniteScroll;
  final bool? enlargeCenterPage;
  final bool? pauseAutoPlayOnManualNavigate;
  final bool? autoplay;
  final Curve? autoplayCurve;
  final void Function(int, CarouselPageChangedReason)? onPageChanged;

  const CarouselOptions({
    this.height,
    this.viewPortFraction,
    this.enableInfiniteScroll,
    this.enlargeCenterPage,
    this.pauseAutoPlayOnManualNavigate,
    this.autoplay,
    this.autoplayCurve,
    this.onPageChanged,
  });

  @override
  List<Object?> get props => [
        height,
        viewPortFraction,
        enableInfiniteScroll,
        enlargeCenterPage,
        pauseAutoPlayOnManualNavigate,
        autoplay,
        autoplayCurve,
        onPageChanged,
      ];
}

CarouselArgs and CarouselOptions are the configuration objects. They hold all the data needed to construct a carousel. They're simple data containers with no construction logic of their own.

The Product

import 'package:flutter/material.dart';
import 'package:carousel_slider/carousel_slider.dart' as n;

class CustomCarousel extends StatelessWidget {
  final CarouselArgs dto;

  // private constructor only the Builder can create this widget
  CustomCarousel._builder(CustomCarouselBuilder builder)
      : dto = builder._dto!;

  @override
  Widget build(BuildContext context) {
    return n.CarouselSlider.builder(
      options: n.CarouselOptions(
        height: dto.options.height,
        viewportFraction: dto.options.viewPortFraction!,
        enableInfiniteScroll: dto.options.enableInfiniteScroll!,
        enlargeCenterPage: dto.options.enlargeCenterPage,
        onPageChanged: dto.options.onPageChanged,
        autoPlayCurve: dto.options.autoplayCurve!,
        autoPlay: dto.options.autoplay!,
      ),
      itemBuilder: dto.itemBuilder,
      itemCount: dto.itemCount,
    );
  }
}

CustomCarousel is the Product. Its constructor is private: CustomCarousel._builder. The underscore prefix and the named constructor ensure that nobody outside this class can instantiate a CustomCarousel directly. The only way to create one is through the Builder.

This is intentional. It enforces that all carousel construction goes through the Builder, where the configuration is validated and assembled consistently.

The Builder

class CustomCarouselBuilder {
  BuildContext? _context;
  CarouselArgs? _dto;

  CustomCarouselBuilder setArgs(BuildContext context, CarouselArgs value) {
    _context = context;
    _dto = value;
    return this;
  }

  Widget get buildCarousel =>
      CustomCarousel._builder(this).build(_context!);
}

CustomCarouselBuilder is the Builder. It accumulates the BuildContext and the CarouselArgs through setArgs. The setArgs method returns this, enabling the call to be chained.

buildCarousel is the terminal step. It calls the private constructor of CustomCarousel, passing itself as the argument, and then calls build to produce the final widget. The carousel can't be built until both the context and the args have been provided.

The Director: A Factory That Uses the Builder

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:carousel_slider/carousel_slider.dart' as n;

class CarouselWidgetFactory {
  static CustomCarouselBuilder showCarouselAds(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read<DashboardLogic>().dashboardAds.length,
          itemBuilder: (context, index, realIndex) => DashboardAdsList(
            dto: context.read<DashboardLogic>().dashboardAds[index],
          ),
          options: CarouselOptions(
            height: 200,
            viewPortFraction: 0.97,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.easeIn,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );

  static CustomCarouselBuilder showCarouselAccountBalance(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read<DashboardLogic>().allBalances.length,
          itemBuilder: (context, index, realIndex) => BalanceList(
            dto: context.read<DashboardLogic>().allBalances[index],
          ),
          options: CarouselOptions(
            height: 230,
            viewPortFraction: 1,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.decelerate,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );
}

CarouselWidgetFactory is the Director. It knows exactly how to configure the Builder for each specific carousel type. The knowledge of what a dashboard ads carousel looks like (height 200, viewport 0.97, easeIn curve) lives in one place. The knowledge of what an account balance carousel looks like (height 230, viewport 1, decelerate curve) lives in one place.

A developer who needs to add a new carousel type adds one static method to CarouselWidgetFactory. They don't need to understand the internals of CustomCarouselBuilder or CustomCarousel. They describe what they want using the Factory.

Using It

class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // the factory creates the right builder configuration
        // buildCarousel produces the final widget
        CarouselWidgetFactory.showCarouselAds(context).buildCarousel,
        const SizedBox(height: 16),
        CarouselWidgetFactory.showCarouselAccountBalance(context).buildCarousel,
      ],
    );
  }
}

Two carousels, two lines. The calling code has zero knowledge of carousel configuration. It doesn't know about viewport fractions, autoplay curves, or item builders. It calls the Factory, which uses the Builder, which produces the Product. Each layer knows only what it needs to know.

Real World Example Two: HTTP Request Builder

The carousel example shows Builder for widget construction. This second example shows it for non-UI object construction: building HTTP requests. This is a common pattern in data layers and API clients.

The Product

class ApiRequest {
  final String url;
  final String method;
  final Map<String, String> headers;
  final Map<String, dynamic>? body;
  final Duration timeout;
  final int maxRetries;

  // private constructor — only the Builder can create ApiRequest
  ApiRequest._({
    required this.url,
    required this.method,
    required this.headers,
    this.body,
    required this.timeout,
    required this.maxRetries,
  });
}

ApiRequest holds everything needed to make an HTTP request. Its private constructor ensures it's always created through the Builder, where defaults are applied and validation happens.

The Builder

class ApiRequestBuilder {
  String? _url;
  String _method = 'GET';
  final Map<String, String> _headers = {};
  Map<String, dynamic>? _body;
  Duration _timeout = const Duration(seconds: 30);
  int _maxRetries = 0;

  ApiRequestBuilder url(String url) {
    _url = url;
    return this;
  }

  ApiRequestBuilder method(String method) {
    _method = method;
    return this;
  }

  ApiRequestBuilder header(String key, String value) {
    _headers[key] = value;
    return this;
  }

  ApiRequestBuilder bearerToken(String token) {
    _headers['Authorization'] = 'Bearer $token';
    return this;
  }

  ApiRequestBuilder contentType(String type) {
    _headers['Content-Type'] = type;
    return this;
  }

  ApiRequestBuilder body(Map<String, dynamic> body) {
    _body = body;
    return this;
  }

  ApiRequestBuilder timeout(Duration timeout) {
    _timeout = timeout;
    return this;
  }

  ApiRequestBuilder withRetries(int maxRetries) {
    _maxRetries = maxRetries;
    return this;
  }

  ApiRequest build() {
    if (_url == null || _url!.isEmpty) {
      throw ArgumentError('URL is required to build an ApiRequest');
    }

    return ApiRequest._(
      url: _url!,
      method: _method,
      headers: Map.unmodifiable(_headers),
      body: _body,
      timeout: _timeout,
      maxRetries: _maxRetries,
    );
  }
}

Each method on ApiRequestBuilder sets one configuration value and returns this. The build() method is the terminal step. It validates that required fields are present and constructs the immutable ApiRequest.

Notice that _method, _timeout, and _maxRetries all have sensible defaults. A caller doesn't need to specify these unless they want to override the defaults. This is one of the key advantages of the Builder over a constructor: optional configuration is genuinely optional, with no null checks or default parameter workarounds.

Using It

// a standard authenticated POST request
final createUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users')
    .method('POST')
    .bearerToken(authToken)
    .contentType('application/json')
    .body({'name': 'Oluwaseyi', 'email': 'seyi@example.com'})
    .timeout(const Duration(seconds: 15))
    .build();

// a GET request with retry logic
final getUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users/$userId')
    .bearerToken(authToken)
    .withRetries(3)
    .build();

// a request with custom headers for a third-party service
final webhookRequest = ApiRequestBuilder()
    .url('https://webhook.example.com/events')
    .method('POST')
    .header('X-API-Key', apiKey)
    .header('X-Webhook-Secret', webhookSecret)
    .contentType('application/json')
    .body(eventPayload)
    .timeout(const Duration(seconds: 5))
    .build();

Each request reads like a description of itself. The URL, the method, the authentication, the body, and the timeout. You can read any of these and understand immediately what kind of request it is and what it contains.

Compare this to calling a constructor directly:

// without Builder — hard to read, parameter order matters
final request = ApiRequest._(
  url: 'https://api.example.com/users',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $authToken',
    'Content-Type': 'application/json',
  },
  body: {'name': 'Oluwaseyi', 'email': 'seyi@example.com'},
  timeout: const Duration(seconds: 15),
  maxRetries: 0,
);

The constructor version requires you to know every field and its order. The Builder version lets you specify only what you need and reads like documentation.

The Builder Pattern in C#

The same pattern in C# demonstrates that this is a universal design principle, not a Dart-specific technique. C# is particularly expressive for Builder implementations because of its method chaining conventions.

HTTP Request Builder in C#

public class ApiRequest
{
    public string Url { get; }
    public string Method { get; }
    public Dictionary<string, string> Headers { get; }
    public object? Body { get; }
    public TimeSpan Timeout { get; }
    public int MaxRetries { get; }

    // private constructor
    private ApiRequest(
        string url,
        string method,
        Dictionary<string, string> headers,
        object? body,
        TimeSpan timeout,
        int maxRetries)
    {
        Url = url;
        Method = method;
        Headers = headers;
        Body = body;
        Timeout = timeout;
        MaxRetries = maxRetries;
    }

    public static ApiRequestBuilder Create() => new ApiRequestBuilder();
}

public class ApiRequestBuilder
{
    private string? _url;
    private string _method = "GET";
    private readonly Dictionary<string, string> _headers = new();
    private object? _body;
    private TimeSpan _timeout = TimeSpan.FromSeconds(30);
    private int _maxRetries = 0;

    public ApiRequestBuilder Url(string url)
    {
        _url = url;
        return this;
    }

    public ApiRequestBuilder Method(string method)
    {
        _method = method;
        return this;
    }

    public ApiRequestBuilder Header(string key, string value)
    {
        _headers[key] = value;
        return this;
    }

    public ApiRequestBuilder BearerToken(string token)
    {
        _headers["Authorization"] = $"Bearer {token}";
        return this;
    }

    public ApiRequestBuilder ContentType(string contentType)
    {
        _headers["Content-Type"] = contentType;
        return this;
    }

    public ApiRequestBuilder Body(object body)
    {
        _body = body;
        return this;
    }

    public ApiRequestBuilder Timeout(TimeSpan timeout)
    {
        _timeout = timeout;
        return this;
    }

    public ApiRequestBuilder WithRetries(int maxRetries)
    {
        _maxRetries = maxRetries;
        return this;
    }

    public ApiRequest Build()
    {
        if (string.IsNullOrEmpty(_url))
            throw new ArgumentException("URL is required");

        return new ApiRequest(
            _url!,
            _method,
            new Dictionary<string, string>(_headers),
            _body,
            _timeout,
            _maxRetries
        );
    }
}

Using It in C#

// authenticated POST request
var createUserRequest = ApiRequest.Create()
    .Url("https://api.example.com/users")
    .Method("POST")
    .BearerToken(authToken)
    .ContentType("application/json")
    .Body(new { name = "Oluwaseyi", email = "seyi@example.com" })
    .Timeout(TimeSpan.FromSeconds(15))
    .Build();

// GET with retry logic
var getUserRequest = ApiRequest.Create()
    .Url($"https://api.example.com/users/{userId}")
    .BearerToken(authToken)
    .WithRetries(3)
    .Build();

The pattern is identical. The method names are capitalized following C# conventions. The Build() method is the terminal step. The private constructor is enforced. The result reads exactly like its Dart equivalent.

A UI Builder in C# (ASP.NET)

The Builder pattern also appears naturally in .NET for constructing complex objects in backend systems. Here's a notification builder:

public class Notification
{
    public string Title { get; }
    public string Body { get; }
    public string? ImageUrl { get; }
    public NotificationPriority Priority { get; }
    public Dictionary<string, string> Data { get; }
    public bool Silent { get; }

    private Notification(
        string title,
        string body,
        string? imageUrl,
        NotificationPriority priority,
        Dictionary<string, string> data,
        bool silent)
    {
        Title = title;
        Body = body;
        ImageUrl = imageUrl;
        Priority = priority;
        Data = data;
        Silent = silent;
    }

    public static NotificationBuilder Builder(string title, string body)
        => new NotificationBuilder(title, body);
}

public class NotificationBuilder
{
    private readonly string _title;
    private readonly string _body;
    private string? _imageUrl;
    private NotificationPriority _priority = NotificationPriority.Default;
    private readonly Dictionary<string, string> _data = new();
    private bool _silent = false;

    internal NotificationBuilder(string title, string body)
    {
        _title = title;
        _body = body;
    }

    public NotificationBuilder WithImage(string imageUrl)
    {
        _imageUrl = imageUrl;
        return this;
    }

    public NotificationBuilder WithPriority(NotificationPriority priority)
    {
        _priority = priority;
        return this;
    }

    public NotificationBuilder WithData(string key, string value)
    {
        _data[key] = value;
        return this;
    }

    public NotificationBuilder AsSilent()
    {
        _silent = true;
        return this;
    }

    public Notification Build() => new Notification(
        _title,
        _body,
        _imageUrl,
        _priority,
        new Dictionary<string, string>(_data),
        _silent
    );
}

// usage
var notification = Notification
    .Builder("New Transaction", "You received NGN 50,000")
    .WithPriority(NotificationPriority.High)
    .WithData("transaction_id", "txn_001")
    .WithData("type", "credit")
    .Build();

var silentNotification = Notification
    .Builder("Background Sync", "")
    .AsSilent()
    .WithData("sync_type", "full")
    .Build();

Builder vs Constructor vs Factory

Understanding when to reach for a Builder versus a constructor or a Factory method requires understanding what problem each one solves.

A constructor is the right choice when the object is simple enough that all its parameters can be understood at a glance and there are few optional configurations. A User with an id, name, and email doesn't need a Builder.

A Factory method is the right choice when you need to control which type of object is created, or when creation requires logic that determines which concrete type to instantiate. A Repository.create() that returns either a SqlRepository or a HiveRepository based on the environment is a Factory.

A Builder is the right choice when the object has many optional or complex configuration parameters, when the construction requires multiple steps, when you want to prevent the creation of invalid objects by deferring construction until all required parameters are present, or when you want construction code to read clearly and be self-documenting.

The carousel example uses both Builder and Factory together deliberately. The Factory provides named, pre-configured entry points (showCarouselAds, showCarouselAccountBalance). The Builder handles the step-by-step construction of the complex configuration. Each pattern does its job.

When to Use the Builder Pattern

There are various solid use cases for the Builder pattern.

Use it when the object being constructed has many parameters, especially many optional ones. Named constructors with ten optional parameters are hard to read and easy to misconfigure.

It's also a good choice when the construction requires multiple steps that should be validated before the object is created. A Builder can enforce that required fields are present before calling build().

Choose it when you want the construction code to be self-documenting. Method chaining with descriptive names reads like documentation. A reader can understand what is being built without knowing the internals.

It's helpful when you need different representations of the same object. The same Builder can be used to create a test request, a staging request, and a production request by changing which methods are called, without modifying the Request class itself.

And it works well when you want to prevent the creation of invalid objects. By making the Product's constructor private and putting validation in the Builder's build() method, you ensure that invalid objects simply can't be created.

When Not to Use It

Avoid the Builder pattern when the object is simple and its constructor is already clear. Adding a Builder to a class with two required parameters is over-engineering that adds complexity without adding value.

It's also not a great choice when immutability isn't a concern and the object can be configured after creation through property setters. Some objects benefit from simple post-construction configuration rather than Builder-pattern construction.

And it's best to avoid it when the construction steps have strict ordering that a linear Builder can't represent. If step B absolutely must know the result of step A before it can run, a different pattern may be more appropriate.

Conclusion

The Builder Design Pattern addresses a problem that every developer encounters as their objects grow more complex. Constructors with many parameters become walls of values that are hard to read, hard to maintain, and easy to misconfigure. Optional parameters require null checks and default value workarounds that obscure the intent of the code.

The Builder separates the construction of a complex object from the object itself. Configuration accumulates step by step through descriptive method calls. Construction happens in one terminal step that validates and produces the final object. The Product's private constructor ensures that bypassing the Builder isn't possible.

The carousel example from a real Flutter fintech application shows this in a UI context: a Builder that accumulates widget configuration, a Factory that provides pre-configured Builder calls for specific carousel types, and a Product that can only be constructed through its Builder. Adding a new carousel type means one new Factory method. Changing carousel configuration means changing the relevant Factory method. The calling code never touches carousel internals.

The HTTP Request Builder shows the same pattern in a data layer context: step by step configuration through method chaining, sensible defaults for optional values, validation before construction, and an immutable Product that can't be created in an invalid state.

Method chaining is what makes Builder code readable. Each method call returns the Builder, enabling the next call to follow immediately. The chain reads from left to right or top to bottom like a description of what's being built. This isn't just aesthetics. It's what makes Builder code self-documenting and maintainable over time.

Complex object construction is a problem every codebase will encounter. The Builder pattern is how experienced engineers solve it.

You'll also need to be quite intentional in selecting your folder structure, architecture, and the patterns you use in your projects.

Most Flutter apps start the same way. In the beginning, you have a lib folder, a few screens, maybe a models directory, and a services file that handles everything. It works, the app ships, and everyone is happy.

Then the app grows. New features come in. The team expands. What was once a manageable codebase becomes a maze. Changing one thing breaks another. Nobody is sure where business logic actually lives. The models folder has three hundred files. The services file is six thousand lines long. New engineers take weeks to understand where to add anything.

This isn't a discipline problem. It's a structure problem. The app was never organized in a way that could absorb growth without collapsing.

Feature Modularization is the organizational strategy that prevents this collapse. It's not a new framework, and it's not a replacement for Clean Architecture or Domain-Driven Design. It takes the principles of both and applies them feature by feature, so that every piece of your application is self-contained, independently testable, and scalable without interference.

In this article, we'll cover the current issues you might encounter using the layer first pattern, how Domain-Driven Design actually works, some business rules with value objects, what Clean Architecture means, and how they all come together in feature modularization.

Table of Contents

• Prerequisites

• What Feature Modularization Actually Is

• The Problem With Layer-First Organization

• The Building Blocks: Clean Architecture Meets DDD

• Entities, Value Objects, and DTOs in a Modular Feature

• Business Rules and Where They Live

• Exception Handling and Safe State Propagation

• The Folder Structure

• Real World Example One: The Employee Feature

• Real World Example Two: The Payment Feature

• Cross-Feature Communication

• Patterns That Enhance Modularization

• Scaling to Large Teams

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Building Flutter applications in Dart

• What object-oriented programming is: classes, inheritance, interfaces

• What layers mean in software architecture: separating UI from business logic from data access

• Async programming in Dart: Futures and async/await

You don't need prior experience with Clean Architecture or Domain-Driven Design. This article introduces the relevant concepts from both as they come up.

What Feature Modularization Actually Is

Feature Modularization is the practice of organizing your application around features, not around technical layers.

Every feature in your application contains everything it needs to function: its domain model, business rules, data access, and UI. The feature is a vertical slice through the entire application stack. It doesn't depend on other features to function. It doesn't expose its internals to other features. It stands alone.

This is fundamentally different from how most apps are initially organized, where all the domain code lives in one folder, all the data access lives in another folder, and all the UI lives in a third folder, regardless of which feature that code belongs to.

Feature Modularization isn't Clean Architecture. Clean Architecture defines what the layers are and the rules that govern how they interact. It tells you that the domain layer can't depend on the infrastructure layer, that business rules can't know about the UI, and that data flows inward through defined boundaries.

Feature Modularization isn't Domain-Driven Design either. DDD gives you the vocabulary for modeling complex business domains. It introduces entities, value objects, aggregates, domain services, and bounded contexts as tools for capturing business complexity in code.

Feature Modularization takes both of these and combines them. It uses Clean Architecture's layering rules and DDD's modeling vocabulary, and it applies them at the feature level. Each feature gets its own domain layer, its own application layer, its own infrastructure layer, and its own presentation layer. The rules from Clean Architecture govern how those layers interact within the feature. The concepts from DDD govern how the domain model is structured inside the domain layer.

The result is a codebase that can grow indefinitely without any single part of it becoming too large to understand or modify safely.

The Problem With Layer-First Organization

To understand why Feature Modularization matters, you need to see what the alternative looks like at scale.

In a layer-first organization, the folder structure groups code by technical role:

lib/
  domain/
    employee.dart
    payment.dart
    product.dart
    notification.dart
    user.dart
    ... 47 more files

  application/
    get_employee_usecase.dart
    process_payment_usecase.dart
    get_products_usecase.dart
    send_notification_usecase.dart
    ... 83 more use cases

  infrastructure/
    employee_repository_impl.dart
    payment_repository_impl.dart
    product_datasource.dart
    notification_service_impl.dart
    ... 91 more implementations

  presentation/
    employee_page.dart
    payment_page.dart
    product_list_page.dart
    ... 200 more screens and widgets

This works fine at small scale. At medium scale it starts to show cracks. At large scale it becomes genuinely painful.

When a developer needs to modify the Employee feature, they touch files in four separate top-level folders. A change to the Employee entity in the domain folder requires navigating to the application folder for the use case, then the infrastructure folder for the repository implementation, and then the presentation folder for the UI. These folders aren't next to each other. They're separated by all the other features sharing those folders.

Understanding any single feature requires mentally assembling it from pieces scattered across the entire codebase. Onboarding a new engineer to the Employee feature means showing them four different locations before they can see the complete picture.

Testing the Employee feature in isolation is difficult because its pieces aren't isolated. They share folders and sometimes share dependencies with other features in ways that make it hard to draw a clean boundary.

Feature Modularization solves this by keeping everything that belongs to a feature together.

The Building Blocks: Clean Architecture Meets DDD

Before looking at the folder structure and code, you need to understand what Clean Architecture and DDD each contribute to Feature Modularization and why both are necessary.

What Clean Architecture Contributes

Clean Architecture organizes code into layers with a strict dependency rule: inner layers never depend on outer layers. The domain is the innermost layer. The application layer wraps the domain. The infrastructure layer is outermost.

In a Flutter application, this means a few things:

The domain layer contains entities, value objects, and repository interfaces. It has zero dependencies on Flutter, on HTTP libraries, on local databases, or on any external package. It's pure Dart, and it's the business logic of the feature, completely isolated from how the app is built or deployed.

The application layer contains use cases. A use case orchestrates domain objects to accomplish a specific business task. It depends only on the domain layer. It knows about entities and repositories but doesn't know about HTTP or SQLite or Riverpod.

The infrastructure layer contains the concrete implementations of repository interfaces defined in the domain. It knows about HTTP clients, local databases, and external services. It depends on the domain layer interfaces but the domain layer never depends on it.

The presentation layer contains the UI: widgets, notifiers, and state. It depends on the application layer through use cases. It reacts to state and has no business logic.

This dependency direction ensures that business rules are never corrupted by infrastructure details. Changing your HTTP client from Dio to http doesn't require touching a single domain entity. Changing your state management from Riverpod to BLoC doesn't require touching a single use case.

What Domain-Driven Design Contributes

DDD provides the vocabulary for modeling the domain layer properly.

An Entity is a domain object with identity. It has an ID that distinguishes it from other entities of the same type. An Employee entity is identified by its employee ID. Two employees with the same name are still different entities because they have different IDs. Entities can have state that changes over time, and they enforce rules about how that state can change.

A Value Object wraps a single piece of data and enforces its intrinsic validity. An EmployeeId is a Value Object, as is an email address or monetary amount. Value Objects are immutable. If the data is invalid, the Value Object throws an exception at construction time, before invalid data can enter the domain.

A Domain Service handles business logic that doesn't naturally belong to a single entity. If a rule spans multiple entities or requires coordination between entities in ways that don't fit on any single entity, that logic belongs in a Domain Service.

A Repository is an interface defined in the domain layer that describes how to persist and retrieve domain objects. The domain knows what operations it needs. The infrastructure layer provides the concrete implementation. The domain never knows which database or API is behind the repository.

Entities, Value Objects, and DTOs in a Modular Feature

Understanding the distinction between these three types is fundamental to feature modularization. Getting this wrong leads to business rules leaking into the wrong layers.

Value Objects

A Value Object wraps a single piece of data and enforces that the data is always valid. It throws immediately when invalid data is provided. This means invalid data can never exist inside your domain.

class EmployeeId {
  final String value;

  EmployeeId(this.value) {
    if (value.isEmpty) {
      throw DomainException('Employee ID cannot be empty');
    }
    if (value.length < 4) {
      throw DomainException('Employee ID must be at least 4 characters');
    }
  }

  @override
  bool operator ==(Object other) =>
      other is EmployeeId && other.value == value;

  @override
  int get hashCode => value.hashCode;

  @override
  String toString() => value;
}

class Money {
  final double amount;
  final String currency;

  Money({required this.amount, required this.currency}) {
    if (amount < 0) {
      throw DomainException('Amount cannot be negative');
    }
    if (currency.isEmpty) {
      throw DomainException('Currency cannot be empty');
    }
  }

  Money add(Money other) {
    if (currency != other.currency) {
      throw DomainException('Cannot add different currencies');
    }
    return Money(amount: amount + other.amount, currency: currency);
  }

  @override
  String toString() => '$currency ${amount.toStringAsFixed(2)}';
}

Value Objects are immutable. You never modify a Value Object. Instead, you create a new one. EmployeeId and Money above both validate at construction. No invalid EmployeeId can ever exist anywhere in your domain. No negative Money can ever exist. The guard is built into the type itself.

Entities

An Entity is a domain object with an identity and rules about how its state can change.

class Employee {
  final EmployeeId id;
  final String name;
  DateTime? clockInTime;
  DateTime? clockOutTime;

  Employee({
    required this.id,
    required this.name,
  });

  void clockIn(DateTime time) {
    if (clockInTime != null && clockOutTime == null) {
      throw DomainException('Cannot clock in: already clocked in');
    }
    clockInTime = time;
    clockOutTime = null;
  }

  void clockOut(DateTime time) {
    if (clockInTime == null) {
      throw DomainException('Cannot clock out: not clocked in');
    }
    if (time.isBefore(clockInTime!)) {
      throw DomainException('Clock out time cannot be before clock in time');
    }
    clockOutTime = time;
  }

  bool get isClockedIn => clockInTime != null && clockOutTime == null;

  Duration? get hoursWorked {
    if (clockInTime == null || clockOutTime == null) return null;
    return clockOutTime!.difference(clockInTime!);
  }
}

The Entity owns its state transitions. clockIn and clockOut aren't just setters. They enforce business rules. An employee can't clock in twice without clocking out, just like they can't clock out before they've clocked in. These rules live on the Entity where they belong, not in a use case, widget, or repository.

DTOs

A Data Transfer Object carries raw data from an external source: an API response, database row, or JSON payload. DTOs have no business rules or behavior. They exist only to transport data across a boundary.

class EmployeeDTO {
  final String id;
  final String name;
  final String? clockInTime;
  final String? clockOutTime;

  const EmployeeDTO({
    required this.id,
    required this.name,
    this.clockInTime,
    this.clockOutTime,
  });

  factory EmployeeDTO.fromJson(Map<String, dynamic> json) {
    return EmployeeDTO(
      id: json['id'] as String,
      name: json['name'] as String,
      clockInTime: json['clock_in_time'] as String?,
      clockOutTime: json['clock_out_time'] as String?,
    );
  }

  Employee toDomain() {
    final employee = Employee(
      id: EmployeeId(id),
      name: name,
    );

    if (clockInTime != null) {
      employee.clockIn(DateTime.parse(clockInTime!));
    }
    if (clockOutTime != null) {
      employee.clockOut(DateTime.parse(clockOutTime!));
    }

    return employee;
  }
}

The DTO lives in the infrastructure layer. It knows about JSON, while the domain entity knows nothing about JSON. The toDomain() method converts raw data into a properly constructed domain object, firing the business rules along the way.

Business Rules and Where They Live

Every business rule in a modular feature lives in the domain layer. This isn't a preference. It's the architectural contract that makes the entire approach work.

Value Objects enforce atomic, intrinsic rules. An email address must contain an @ symbol. A monetary amount can't be negative. An employee ID can't be empty. These rules are about the data itself, and they belong on the Value Object.

Entities enforce stateful rules. An employee can't clock in twice. A payment can't be processed if it has already been refunded. A task can't be completed if its dependencies aren't complete. These rules involve the state of the entity changing over time. They belong on the Entity.

Domain Services enforce rules that span multiple entities or require coordination. An employee can't approve their own leave request. A payment requires verification from both the payer and a fraud detection check. These rules involve multiple entities and don't naturally belong on any single one. They belong in a Domain Service.

The rule is simple and absolute: if something is a business rule, it lives in the domain layer. The application layer calls the domain. The infrastructure layer implements the domain's interfaces. The presentation layer reacts to the results. None of them define or modify business rules.

This boundary is what makes the system trustworthy. Business rules can't be bypassed by going directly to the database. They can't be skipped by calling a repository method directly from a widget. They're always enforced because the only way to change domain state is through the domain objects themselves.

Exception Handling and Safe State Propagation

When a business rule is violated in the domain layer, the domain throws a DomainException. This exception travels up through the application layer to the presentation layer where it's converted into UI state.

The key insight is that the exception doesn't crash the app. It's caught at a defined boundary and converted into a safe state that the UI can render.

Here's the complete flow:

// domain layer — throws when rules are violated
class Employee {
  void clockIn(DateTime time) {
    if (clockInTime != null && clockOutTime == null) {
      throw DomainException('Cannot clock in: already clocked in');
    }
    clockInTime = time;
  }
}

// application layer — catches domain exceptions and returns Result
class ClockInUseCase {
  final EmployeeRepository _repository;

  ClockInUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(
    String employeeId,
    DateTime time,
  ) async {
    try {
      final employee = await _repository.findById(EmployeeId(employeeId));

      if (employee == null) {
        return Result.failure(AppException.notFound('Employee not found'));
      }

      employee.clockIn(time);
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

// presentation layer — converts result into UI state
@riverpod
class EmployeeNotifier extends _$EmployeeNotifier {
  @override
  AsyncValue<Employee?> build() => const AsyncData(null);

  Future<void> clockIn(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockInUseCaseProvider)
        .execute(employeeId, DateTime.now());

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

// widget — renders state, owns nothing
class EmployeeClockInWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(employeeNotifierProvider);

    return state.when(
      data: (employee) => employee != null
          ? ClockInSuccess(employee: employee)
          : const ClockInForm(),
      loading: () => const LoadingIndicator(),
      error: (error, _) => ErrorMessage(message: error.toString()),
    );
  }
}

The flow is linear and predictable:

1. User input triggers a use case.

2. The use case calls the domain.

3. The domain enforces rules.

4. If a rule is violated, a DomainException is thrown.

5. The use case catches it and returns a failure Result.

6. The notifier converts the Result into AsyncError state.

7. The widget renders the error.

At no point does the exception escape unhandled. And at no point does the widget touch business logic.

The Folder Structure

With these concepts in place, the folder structure follows naturally:

lib/
  shared/
    core/
      errors/
        domain_exception.dart
        app_exception.dart
      result/
        result.dart
      di/
        injection.dart
      utils/
        date_utils.dart

  features/
    employee/
      domain/
        entities/
          employee.dart
        value_objects/
          employee_id.dart
        repositories/
          employee_repository.dart
        services/
          attendance_domain_service.dart
        exceptions/
          employee_exceptions.dart

      application/
        use_cases/
          clock_in_usecase.dart
          clock_out_usecase.dart
          get_employee_usecase.dart

      infrastructure/
        datasources/
          employee_remote_datasource.dart
          employee_local_datasource.dart
        repositories/
          employee_repository_impl.dart
        dtos/
          employee_dto.dart

      presentation/
        notifier/
          employee_notifier.dart
          employee_notifier.g.dart
        state/
          employee_state.dart
        pages/
          employee_dashboard_page.dart
          clock_in_page.dart
        widgets/
          employee_card.dart
          clock_in_button.dart

    payment/
      domain/
        entities/
          payment.dart
        value_objects/
          money.dart
          payment_reference.dart
        repositories/
          payment_repository.dart
        services/
          payment_verification_service.dart

      application/
        use_cases/
          initiate_payment_usecase.dart
          verify_payment_usecase.dart
          refund_payment_usecase.dart

      infrastructure/
        datasources/
          payment_remote_datasource.dart
        repositories/
          payment_repository_impl.dart
        dtos/
          payment_dto.dart

      presentation/
        notifier/
          payment_notifier.dart
          payment_notifier.g.dart
        pages/
          payment_page.dart
          payment_confirmation_page.dart
        widgets/
          payment_summary_card.dart

  main.dart

The shared/core folder holds only what's genuinely shared across all features: base error types, the Result type, dependency injection configuration, and utilities that have no business logic. Everything else belongs inside a feature.

Each feature is a complete vertical slice. Every layer a feature needs lives inside that feature's folder. A developer working on the Employee feature never needs to navigate outside the features/employee directory to understand or modify the feature.

Real World Example One: The Employee Feature

The Employee feature manages the complete lifecycle of employee attendance in a workforce management application. Clock-in, clock-out, shift management, and attendance records.

The Domain

// value objects
class EmployeeId {
  final String value;

  EmployeeId(this.value) {
    if (value.isEmpty) throw DomainException('Employee ID cannot be empty');
  }
}

class ShiftDuration {
  final Duration duration;

  ShiftDuration(this.duration) {
    if (duration.isNegative) {
      throw DomainException('Shift duration cannot be negative');
    }
    if (duration.inHours > 16) {
      throw DomainException('Shift duration cannot exceed 16 hours');
    }
  }
}

// entity
class Employee {
  final EmployeeId id;
  final String name;
  final String teamId;
  DateTime? clockInTime;
  DateTime? clockOutTime;

  Employee({
    required this.id,
    required this.name,
    required this.teamId,
  });

  void clockIn(DateTime time) {
    if (isClockedIn) {
      throw DomainException('Employee is already clocked in');
    }
    clockInTime = time;
    clockOutTime = null;
  }

  void clockOut(DateTime time) {
    if (!isClockedIn) {
      throw DomainException('Employee is not clocked in');
    }
    if (time.isBefore(clockInTime!)) {
      throw DomainException('Clock out time cannot be before clock in time');
    }

    final shift = ShiftDuration(time.difference(clockInTime!));
    clockOutTime = time;
  }

  bool get isClockedIn => clockInTime != null && clockOutTime == null;

  Duration? get currentShiftDuration {
    if (!isClockedIn) return null;
    return DateTime.now().difference(clockInTime!);
  }
}

// repository interface — in the domain layer
abstract class EmployeeRepository {
  Future<Employee?> findById(EmployeeId id);
  Future<List<Employee>> findByTeam(String teamId);
  Future<void> save(Employee employee);
}

The Application Layer

class ClockInUseCase {
  final EmployeeRepository _repository;

  ClockInUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(String employeeId) async {
    try {
      final id = EmployeeId(employeeId);
      final employee = await _repository.findById(id);

      if (employee == null) {
        return Result.failure(
          AppException.notFound('Employee $employeeId not found'),
        );
      }

      employee.clockIn(DateTime.now());
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

class ClockOutUseCase {
  final EmployeeRepository _repository;

  ClockOutUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(String employeeId) async {
    try {
      final id = EmployeeId(employeeId);
      final employee = await _repository.findById(id);

      if (employee == null) {
        return Result.failure(
          AppException.notFound('Employee $employeeId not found'),
        );
      }

      employee.clockOut(DateTime.now());
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

The Infrastructure Layer

class EmployeeDTO {
  final String id;
  final String name;
  final String teamId;
  final String? clockInTime;
  final String? clockOutTime;

  const EmployeeDTO({
    required this.id,
    required this.name,
    required this.teamId,
    this.clockInTime,
    this.clockOutTime,
  });

  factory EmployeeDTO.fromJson(Map<String, dynamic> json) {
    return EmployeeDTO(
      id: json['id'] as String,
      name: json['name'] as String,
      teamId: json['team_id'] as String,
      clockInTime: json['clock_in_time'] as String?,
      clockOutTime: json['clock_out_time'] as String?,
    );
  }

  Employee toDomain() {
    final employee = Employee(
      id: EmployeeId(id),
      name: name,
      teamId: teamId,
    );

    if (clockInTime != null) {
      employee.clockIn(DateTime.parse(clockInTime!));
    }
    if (clockOutTime != null) {
      employee.clockOut(DateTime.parse(clockOutTime!));
    }

    return employee;
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'team_id': teamId,
      'clock_in_time': clockInTime,
      'clock_out_time': clockOutTime,
    };
  }
}

class EmployeeRepositoryImpl implements EmployeeRepository {
  final EmployeeRemoteDataSource _remote;

  EmployeeRepositoryImpl(this._remote);

  @override
  Future<Employee?> findById(EmployeeId id) async {
    final dto = await _remote.fetchEmployee(id.value);
    return dto?.toDomain();
  }

  @override
  Future<List<Employee>> findByTeam(String teamId) async {
    final dtos = await _remote.fetchTeamEmployees(teamId);
    return dtos.map((dto) => dto.toDomain()).toList();
  }

  @override
  Future<void> save(Employee employee) async {
    final dto = EmployeeDTO(
      id: employee.id.value,
      name: employee.name,
      teamId: employee.teamId,
      clockInTime: employee.clockInTime?.toIso8601String(),
      clockOutTime: employee.clockOutTime?.toIso8601String(),
    );
    await _remote.updateEmployee(dto);
  }
}

The Presentation Layer

@riverpod
class EmployeeNotifier extends _$EmployeeNotifier {
  @override
  AsyncValue<Employee?> build() => const AsyncData(null);

  Future<void> clockIn(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockInUseCaseProvider)
        .execute(employeeId);

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }

  Future<void> clockOut(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockOutUseCaseProvider)
        .execute(employeeId);

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

class EmployeeDashboardPage extends ConsumerWidget {
  final String employeeId;

  const EmployeeDashboardPage({required this.employeeId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(employeeNotifierProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Employee Dashboard')),
      body: state.when(
        data: (employee) => employee != null
            ? EmployeeDashboardContent(
                employee: employee,
                onClockIn: () => ref
                    .read(employeeNotifierProvider.notifier)
                    .clockIn(employeeId),
                onClockOut: () => ref
                    .read(employeeNotifierProvider.notifier)
                    .clockOut(employeeId),
              )
            : const EmptyDashboard(),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => ErrorView(message: error.toString()),
      ),
    );
  }
}

The widget knows nothing about clocking in, the EmployeeId Value Object, or the DomainException. It renders state and delegates actions to the notifier. Everything else happens in the layers below.

Real World Example Two: The Payment Feature

The Payment feature handles the complete payment lifecycle: initiation, processing, verification, and failure handling. This is a domain with complex business rules that benefit enormously from being modeled explicitly.

The Domain

enum PaymentStatus {
  pending,
  processing,
  completed,
  failed,
  refunded,
}

class PaymentReference {
  final String value;

  PaymentReference(this.value) {
    if (value.isEmpty) {
      throw DomainException('Payment reference cannot be empty');
    }
    if (!RegExp(r'^[A-Z0-9]{8,16}$').hasMatch(value)) {
      throw DomainException('Invalid payment reference format');
    }
  }
}

class Payment {
  final PaymentReference reference;
  final Money amount;
  final String payerId;
  final String recipientId;
  PaymentStatus status;
  String? failureReason;
  DateTime? processedAt;

  Payment({
    required this.reference,
    required this.amount,
    required this.payerId,
    required this.recipientId,
    this.status = PaymentStatus.pending,
  });

  void startProcessing() {
    if (status != PaymentStatus.pending) {
      throw DomainException(
        'Cannot process payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.processing;
  }

  void complete() {
    if (status != PaymentStatus.processing) {
      throw DomainException(
        'Cannot complete payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.completed;
    processedAt = DateTime.now();
  }

  void fail(String reason) {
    if (status != PaymentStatus.processing) {
      throw DomainException(
        'Cannot fail payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.failed;
    failureReason = reason;
  }

  void refund() {
    if (status != PaymentStatus.completed) {
      throw DomainException(
        'Cannot refund payment: only completed payments can be refunded',
      );
    }
    status = PaymentStatus.refunded;
  }

  bool get canBeRefunded => status == PaymentStatus.completed;
  bool get isTerminal =>
      status == PaymentStatus.completed ||
      status == PaymentStatus.failed ||
      status == PaymentStatus.refunded;
}

The Payment entity enforces every valid status transition. A payment that's already processing can't start processing again. A payment that hasn't completed can't be refunded. And a payment that has failed can't be completed.

These rules are encoded into the entity and enforced at every state change.

The Application Layer

class InitiatePaymentUseCase {
  final PaymentRepository _repository;

  InitiatePaymentUseCase(this._repository);

  Future<Result<Payment, AppException>> execute({
    required String reference,
    required double amount,
    required String currency,
    required String payerId,
    required String recipientId,
  }) async {
    try {
      final payment = Payment(
        reference: PaymentReference(reference),
        amount: Money(amount: amount, currency: currency),
        payerId: payerId,
        recipientId: recipientId,
      );

      payment.startProcessing();
      await _repository.save(payment);

      return Result.success(payment);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

class VerifyPaymentUseCase {
  final PaymentRepository _repository;
  final PaymentVerificationService _verificationService;

  VerifyPaymentUseCase(this._repository, this._verificationService);

  Future<Result<Payment, AppException>> execute(String reference) async {
    try {
      final ref = PaymentReference(reference);
      final payment = await _repository.findByReference(ref);

      if (payment == null) {
        return Result.failure(
          AppException.notFound('Payment $reference not found'),
        );
      }

      final isVerified = await _verificationService.verify(payment);

      if (isVerified) {
        payment.complete();
      } else {
        payment.fail('Verification failed');
      }

      await _repository.save(payment);
      return Result.success(payment);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

The Presentation Layer

@riverpod
class PaymentNotifier extends _$PaymentNotifier {
  @override
  AsyncValue<Payment?> build() => const AsyncData(null);

  Future<void> initiatePayment({
    required String reference,
    required double amount,
    required String currency,
    required String payerId,
    required String recipientId,
  }) async {
    state = const AsyncLoading();

    final result = await ref.read(initiatePaymentUseCaseProvider).execute(
          reference: reference,
          amount: amount,
          currency: currency,
          payerId: payerId,
          recipientId: recipientId,
        );

    result.fold(
      onSuccess: (payment) => state = AsyncData(payment),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }

  Future<void> verifyPayment(String reference) async {
    state = const AsyncLoading();

    final result = await ref
        .read(verifyPaymentUseCaseProvider)
        .execute(reference);

    result.fold(
      onSuccess: (payment) => state = AsyncData(payment),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

class PaymentPage extends ConsumerWidget {
  const PaymentPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(paymentNotifierProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Payment')),
      body: state.when(
        data: (payment) {
          if (payment == null) return const PaymentForm();
          return PaymentStatusView(payment: payment);
        },
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => PaymentErrorView(message: error.toString()),
      ),
    );
  }
}

Cross-Feature Communication

Self-contained features inevitably need to communicate. The Employee feature might need to check if a user is authenticated. The Payment feature might need to notify the Employee feature about a salary disbursement.

The rules for cross-feature communication preserve the self-containment of each feature:

1. Features never import directly from each other's internal layers.

The Employee feature should never import from features/payment/domain/entities/payment.dart. Direct imports between features create tight coupling that defeats the purpose of modularization.

2. Shared domain concepts live in shared/core.

If both the Employee feature and the Payment feature need a concept like a UserId or a Money value object, that concept lives in shared/core/domain and both features import from there.

3. Cross-feature communication happens through defined interfaces.

If the Payment feature needs to know about an employee to process a salary, it depends on an EmployeeService interface defined in shared/core. The Employee feature provides the implementation. The Payment feature never knows which feature provided it.

4. Events and domain notifications use a shared event bus.

When a payment completes, the Payment feature publishes a PaymentCompleted domain event. Any feature that needs to react to payment completion subscribes to that event. The Payment feature doesn't know who's listening. The listening features don't import from the Payment feature directly.

Patterns That Enhance Modularization

Certain design patterns work particularly well within a modularized feature structure.

The Prototype Pattern is useful for creating employee templates in the Employee feature. An organization might have standard employee profiles for different roles. Cloning a template employee creates a new instance with the same configuration, allowing business rules to fire during the clone's state transitions rather than being bypassed.

class Employee {
  Employee clone() {
    return Employee(
      id: EmployeeId('${id.value}_copy_${DateTime.now().millisecondsSinceEpoch}'),
      name: name,
      teamId: teamId,
    );
  }
}

The Singleton Pattern applies to genuinely unique domain objects. The currently authenticated user is a Singleton. The current session is a Singleton. These live in shared/core because they are cross-feature concerns.

The Repository Pattern is the backbone of infrastructure abstraction in every feature. Domain layers define the interface. Infrastructure layers provide the implementation. Application layers use the interface without knowing which implementation is behind it.

The Observer Pattern, through domain events, enables cross-feature communication without tight coupling. Each feature publishes events when significant domain state changes. Other features subscribe to those events through a shared event bus.

Scaling to Large Teams

Feature Modularization becomes even more valuable as teams grow. At ten engineers working on different features simultaneously, the self-contained nature of each feature prevents constant merge conflicts. Engineers working on the Employee feature and engineers working on the Payment feature are almost never touching the same files.

At thirty engineers, features can become separate Dart packages. The Employee feature becomes packages/employee. The Payment feature becomes packages/payment. They depend on a shared packages/core package. Each package has its own pubspec.yaml, its own tests, and can be independently versioned. This is the next level of modularization and it follows naturally from the feature-first structure.

At fifty engineers, teams can own entire features. The Employee team owns packages/employee. The Payment team owns packages/payment. The contracts between features, defined through interfaces in packages/core, become the API boundaries between teams. A team can release a new version of their feature package independently, and other teams update to that version when they're ready.

The folder structure you start with today is the same structure that scales to a package-based monorepo at fifty engineers. The concepts don't change. The boundaries just become more explicit.

Conclusion

Feature Modularization isn't a folder structure trick. It's a strategic decision about how to organize software so that it can grow without degrading.

It takes Clean Architecture's layering rules and DDD's domain modeling vocabulary and applies them at the feature level. Each feature owns its domain, business rules, data access, and UI. Nothing leaks out or bleeds in. Each feature can be understood, modified, and tested without understanding the entire application.

The Employee feature enforces attendance rules in its entity. The Payment feature enforces transaction state transitions in its entity. Both features use Value Objects to prevent invalid data from ever entering the domain. Both features use the same Result pattern to propagate failures safely from the domain through the application layer to the presentation layer.

When a new requirement arrives for the Employee feature, you open the employee folder and make the change. The Payment feature is untouched. When a new payment method is added to the Payment feature, you open the payment folder and make the change. The Employee feature is untouched.

This is what self-contained actually means. Not just a folder with a name. A complete vertical slice of your application that owns everything it needs and shares nothing it should not.

That is Feature Modularization. And that's how Flutter apps scale from one engineer to fifty without the codebase becoming a liability.

Happy Coding!!

Two years later, Seth Gilbert and Nancy Lynch formally proved it. It became known as the CAP Theorem.

Every distributed database, cloud service, and system that stores data across multiple machines makes a choice about these three properties. Understanding what those properties actually mean, why you can't have all three at the same time, and what the choice looks like in practice is fundamental knowledge for any engineer who builds or operates systems at scale.

Table of Contents

• Prerequisites

• The Three Properties

• Why You Can't Have All Three

• The Real Choice: CP or AP

• CA Systems: The Special Case

• Real Systems and Their Choices

• The Nuance CAP Doesn't Capture

• How to Think About This When Designing Systems

• Conclusion

Prerequisites

Before reading this article you should be comfortable with:

• What a database is and the basic concept of reading and writing data

• What it means for data to be stored on multiple machines (replication at a conceptual level)

• Basic networking concepts: what a network request is and what it means for two machines to communicate

You don't need experience with distributed systems. This article builds the concepts from first principles.

The Three Properties

Consistency

In the context of CAP, Consistency has a specific technical meaning that's different from how the word is used in everyday conversation.

Consistency in CAP means that every read receives the most recent write or an error. Not an old value. Not a stale value. Either the latest data or an explicit failure.

If you write a value to a consistent distributed system and then immediately read it from any node in that system, you get the value you just wrote. Every node in the cluster reflects the same state at any given moment.

This is called strong consistency or linearizability. It's a strict guarantee. If node A has data that node B doesn't yet have, a consistent system will either wait until node B is updated before responding to reads, or refuse to respond until consistency is restored.

The word consistent in CAP doesn't mean the same thing as the C in ACID (Atomicity, Consistency, Isolation, Durability). ACID consistency refers to data integrity constraints. CAP consistency refers to all nodes seeing the same data at the same time.

Availability

Availability means that every request receives a response. Not necessarily the latest data, but a response. The system never refuses a request. It never returns an error saying it can't handle the query right now.

An available system keeps responding even when some of its nodes are failing or unreachable. It prioritizes uptime over data currency. If node A can't reach node B to get the latest write, an available system will respond with whatever data it has, even if that data is slightly out of date.

From the user's perspective, the system is always on. Requests always get answers.

Partition Tolerance

A network partition occurs when the communication link between nodes in a distributed system breaks. Node A can't reach node B. They're both running and healthy, but they can't talk to each other.

Partition Tolerance means the system continues to operate despite network partitions. If two nodes can't communicate, the system keeps working rather than shutting down entirely.

This is the property that makes CAP interesting. Network partitions aren't theoretical. They happen in production systems regularly. Network cables fail. Routers drop packets. Data centers lose connectivity. Cloud providers have outages that isolate regions from each other. Any system running across multiple machines must deal with the reality that those machines will sometimes lose the ability to communicate.

Why You Can't Have All Three

Here's the scenario that proves the theorem.

You have a distributed database with two nodes: Node A and Node B. They replicate data between each other. A network partition occurs. Node A and Node B can no longer communicate.

A write comes in to Node A. Node A processes the write and stores the new value. Node B still has the old value. They're now out of sync and they can't communicate to fix it.

A read comes in to Node B.

If you choose Consistency: Node B knows it can't reach Node A. It knows its data might be stale. To guarantee that every read returns the most recent write, Node B must refuse to respond until it can sync with Node A. It returns an error. The system is consistent but not available during the partition.

If you choose Availability: Node B responds with the data it has, even though that data might be stale. The system keeps responding but the data might not reflect the latest write to Node A. The system is available but not consistent during the partition.

There is no third option. During a network partition, a distributed system must choose between returning potentially stale data (available, not consistent) or refusing to respond (consistent, not available).

Partition Tolerance isn't really a choice in this sense. If your system runs across multiple machines connected by a network, partitions will happen. You can either handle them (be partition tolerant) or not handle them, which means your system simply stops working when a partition occurs.

Most real systems can't afford to simply stop working. Partition Tolerance is therefore effectively mandatory for any distributed system that needs to remain operational.

This is why the real choice in distributed systems is between Consistency and Availability during a partition, not a free choice among all three.

The Real Choice: CP or AP

CP Systems: Consistency over Availability

A CP system chooses to be consistent during a partition at the cost of availability. When nodes can't communicate, the system refuses to respond rather than risk returning stale data.

This is the right choice when correctness is more important than uptime. This is key for financial systems, inventory management, or any domain where serving wrong data is worse than serving no data.

Imagine a payment system. A customer initiates a transfer. The network partitions. The destination node can't reach the source node to confirm the transfer completed. A CP system refuses to show the updated balance until it can confirm the state across all nodes. The user might see a timeout or an error. But they won't see a balance that doesn't reflect reality.

The trade-off is real. During the partition, some requests fail. Users experience errors. But the data they eventually see is correct.

AP Systems: Availability over Consistency

An AP system chooses to remain available during a partition at the cost of consistency. When nodes can't communicate, the system keeps responding with whatever data it has, even if that data is stale.

This is the right choice when uptime is more important than having the absolute latest data. This is important for social media feeds, product catalogues, user profile reads, or any domain where a slightly stale response is acceptable.

Imagine a social media platform. During a network partition, you view your feed. The AP system serves you content from the nearest available node even if that node hasn't received the last few minutes of posts from across the network. You might miss three posts temporarily. When the partition heals and nodes resynchronize, your feed catches up. No data is lost. You just saw slightly stale data for a short window.

The trade-off is also real. Different users might see different states of the data at the same time. Data written during a partition might create conflicts that need to be resolved when the partition heals. The system must have a strategy for handling these conflicts.

Systems that lean AP:

Cassandra, CouchDB, and DynamoDB are examples of systems that lean toward availability. They prioritize uptime and use eventual consistency: a guarantee that if no new writes occur, all nodes will eventually converge to the same value. Eventually is the key word. Not immediately. Not during the partition. But eventually.

Amazon DynamoDB's design philosophy explicitly acknowledges this trade-off. Amazon's shopping cart is a famous example: it's better to let a user add items to their cart (even if the cart state is slightly inconsistent across nodes) than to refuse the add operation because nodes can't reach each other.

CA Systems: The Special Case

You might wonder about a system that chooses Consistency and Availability but not Partition Tolerance. Such a system would need to guarantee that it never experiences a network partition.

The only way to guarantee no network partitions is to run on a single machine. A single machine can't partition from itself. Traditional relational databases running on a single server, like a standalone PostgreSQL instance, are effectively CA. They're consistent (all reads return the latest data) and available (they keep responding) because there are no network partitions to worry about.

But a single-machine database isn't a distributed system. It can't scale horizontally. It has a single point of failure. The moment you replicate that database across multiple machines, you have a distributed system and network partitions become a reality you must handle.

This is why the CAP Theorem is specifically about distributed systems. The CA category is largely theoretical for systems that need to scale beyond a single machine.

Real Systems and Their Choices

Real distributed systems don't simply label themselves CP or AP and call it done. The reality is more nuanced. Most systems make different choices for different operations, configure their behavior through tunable consistency levels, and optimize for specific use cases.

Apache Cassandra

Cassandra is fundamentally AP. It prioritizes availability and uses eventual consistency as its default model. But Cassandra gives developers control through consistency levels on every read and write operation.

A write with consistency level ALL requires all replicas to acknowledge the write before it succeeds. This is strong consistency at the cost of availability. A write fails if any replica is unreachable.

A write with consistency level ONE requires only one replica to acknowledge. Highly available, eventually consistent.

A write with consistency level QUORUM requires a majority of replicas to acknowledge. This is the most common production choice: a balance between consistency and availability.

Cassandra's design acknowledges that different operations in the same system may have different consistency requirements. A financial transaction might use QUORUM. An analytics event write might use ONE.

Amazon DynamoDB

DynamoDB offers both eventually consistent reads (AP) and strongly consistent reads (CP) on every read operation. The developer chooses per request.

Eventually consistent reads are cheaper and faster. Strongly consistent reads cost more and take longer but guarantee the latest data.

Google Spanner

Spanner is an interesting case. Google built it to provide strong consistency across a globally distributed system. It achieves this through a combination of atomic clocks, GPS receivers, and a carefully designed protocol called TrueTime.

Spanner essentially narrows the window of uncertainty about the ordering of events across data centers to the point where strong consistency becomes practical even across continents.

Spanner challenges the conventional wisdom that CP systems must sacrifice significant availability. But it does so through extraordinary infrastructure investment rather than by violating the CAP theorem.

ZooKeeper

ZooKeeper is explicitly CP. It's designed for coordination: distributed locks, leader election, and configuration management. In these use cases, returning stale data would be actively harmful. If two nodes both believe they hold a distributed lock because they read stale state, you have a serious problem. ZooKeeper accepts reduced availability to guarantee that every read reflects the latest committed write.

The Nuance CAP Doesn't Capture

The CAP Theorem is a useful mental model, but it has known limitations that the distributed systems community has spent years articulating.

Partitions are Rare. Latency is Constant.

Network partitions happen, but they're relatively infrequent in well-operated systems. What happens all the time, in every request, in every system, is latency: the time it takes for data to replicate from one node to another. The time it takes for a consensus protocol to complete. The time it takes to confirm that all replicas have received a write.

CAP treats the choice between consistency and availability as a binary decision made only during a partition. But in practice, engineers are making trade-offs between consistency and latency on every operation, partition or not.

Not All Inconsistency is the Same.

CAP treats consistency as binary: either every read returns the most recent write or it doesn't. But there's a spectrum between strong consistency and complete chaos. Eventual consistency, monotonic read consistency, read-your-writes consistency, and causal consistency: these are all weaker than strong consistency but stronger than no consistency guarantee at all. The CAP model doesn't distinguish between them.

How to Think About This When Designing Systems

When you're making architectural decisions about data storage in a distributed system, the CAP Theorem gives you a framework for asking the right questions rather than a formula that gives you the right answer.

1. Start with the failure mode that matters.

What happens if two nodes in your system disagree about the state of the data? Is it worse to show the user wrong data or to show them an error?

For a bank account balance, showing wrong data is far worse than showing an error. For a social media like count, being off by a few for a few seconds is completely acceptable.

2. Think about what "stale" means for your data.

How quickly does your data change? If you're storing product descriptions that change once a month, serving data that's five seconds old during a partition is completely harmless. If you're storing stock prices that change hundreds of times per second, five seconds of staleness is a significant problem.

3. Consider the frequency and duration of partitions in your environment.

If your system runs in a single data center on a reliable network, partitions are rare and brief. If your system spans multiple geographic regions, partitions are more frequent and potentially longer. The less reliable your network, the more important your partition strategy becomes.

4. Recognize that most systems need both, just for different operations.

A well-designed system often uses strong consistency for writes that must be correct (financial transactions, inventory deductions, or user authentication) and eventual consistency for reads where slight staleness is acceptable (feed generation, analytics, or non-critical reads). The choice isn't always system-wide. It can be operation-specific.

5. Accept that the trade-off is real and can't be engineered away.

There's no architectural trick that gives you strong consistency, perfect availability, and partition tolerance simultaneously. Engineers who believe they have found one have usually either not thought through the failure scenarios carefully or are operating in an environment where the constraints are gentler than they appear. The CAP Theorem is a mathematical proof. The constraints it describes are fundamental, not implementation details to be optimized away.

Conclusion

The CAP Theorem states that a distributed system can guarantee at most two of three properties: Consistency, Availability, and Partition Tolerance. Because network partitions are an unavoidable reality in any system running across multiple machines, the practical choice is between Consistency and Availability during a partition.

CP systems choose correctness over uptime. During a partition, they refuse to respond rather than risk returning stale data. They're the right choice when serving wrong data causes serious harm.

AP systems choose uptime over correctness. During a partition, they keep responding with whatever data they have, accepting that some responses may be stale. They're the right choice when availability matters more than having the absolute latest data, and when temporary inconsistency can be resolved after the partition heals.

Most real distributed systems don't make a single system-wide choice. They offer tunable consistency levels, make different choices for different operations, and optimize for their specific use cases. Cassandra, DynamoDB, and Spanner all sit on different points of the spectrum and all made deliberate engineering decisions about where to be.

The value of understanding CAP isn't that it gives you the answer. It's that it gives you the right questions. What does consistency mean for this data? What happens if nodes disagree? What's the cost of an error versus the cost of stale data? What does my system need to do during a partition?

Answering those questions honestly, for your specific use case, is how you make the right architectural decision for the system you're actually building.

The naïve answer is a database query. Pull the users table, search for the username, return whether it exists. This works fine at small scale. But at 500 million records, queried millions of times every day, it becomes a serious bottleneck. Even with indexing, the database is doing expensive work for every single registration attempt.

Luckily, there's a smarter approach. Before the database is ever touched, you ask a different system a much faster question. That system gives you one of two answers:

Definitely not here: This is guaranteed. Zero exceptions. The username is available and you can skip the database entirely.

Probably here: This is not guaranteed. The username might be taken, or this might be a false alarm. You need to confirm with the database.

That system is a Bloom Filter. It can't tell you with certainty that something exists. But it can tell you with absolute certainty that something does not exist. And in systems at scale, that one-sided guarantee eliminates the vast majority of expensive database queries.

Table of Contents

• Prerequisites

• What is a Bloom Filter?

• The Two Components of a Bloom Filter

• How Adding an Item Works

• How Checking an Item Works

• False Positives Explained

• Why You Can't Delete From a Bloom Filter

• The False Positive Rate

• Implementation in Dart

• Implementation in C#

• Where Bloom Filters Are Used in Real Systems

• When to Use a Bloom Filter

• When Not to Use It

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Basic data structures: arrays and how indexing works

• What a hash function is at a conceptual level: a function that takes an input and produces a fixed-size output

• Basic programming concepts in either Dart or C#

You don't need to understand database internals or distributed systems deeply. Where these appear in this article, they serve only to illustrate why Bloom Filters matter in real engineering.

What is a Bloom Filter?

A Bloom Filter is a probabilistic data structure that represents a set without storing the actual values in that set.

The word probabilistic is the important one. Unlike a regular set or a database, a Bloom Filter doesn't give you definitive answers about membership. It gives you probabilistic answers. And the probability is deliberately asymmetric:

It will never tell you something is absent when it's actually present. This is called having no false negatives.

It might occasionally tell you something is present when it is actually absent. This is called a false positive. The rate at which this happens is small, controlled, and mathematically predictable.

This asymmetry is what makes Bloom Filters useful. The "definitely not here" answer is trustworthy. The "probably here" answer is a signal to go confirm elsewhere.

The Two Components of a Bloom Filter

A Bloom Filter is built from two things.

1. A bit array

A fixed-size array of bits, all initialized to zero. This is the entire storage of the filter. Not strings or objects, just bits. Zeros and ones.

Position: 0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15
Value:     0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0

The size of this array is chosen based on how many items you expect to store and what false positive rate you can tolerate. A larger array means fewer false positives but more memory.

2. Multiple hash functions

There are typically three to seven hash functions. Each one takes an input and produces a number that maps to a position in the bit array. Different hash functions produce different positions for the same input.

The hash functions must be fast, independent of each other, and distribute their outputs uniformly across the bit array. The quality of the hash functions directly affects the false positive rate.

How Adding an Item Works

To add the username "seyi_codes" to the filter, you run it through all three hash functions:

hash1("seyi_codes") = 3
hash2("seyi_codes") = 7
hash3("seyi_codes") = 11

You set those three positions in the bit array to 1:

Position: 0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15
Value:     0  0  0  1  0  0  0  1  0  0  0  1  0  0  0  0
                    ^           ^              ^
                  hash1       hash2          hash3

The username "seyi_codes" is now represented in the filter. But the string itself is stored nowhere. Only the fact that positions 3, 7, and 11 were set by something.

Now add a second username "aderonke":

hash1("aderonke") = 1
hash2("aderonke") = 7
hash3("aderonke") = 13

Position: 0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15
Value:     0  1  0  1  0  0  0  1  0  0  0  1  0  1  0  0
              ^     ^           ^              ^     ^

Position 7 was already set by "seyi_codes" and gets set again by "aderonke". This is normal. Bits can be shared across multiple items. This sharing is also the source of false positives. We'll talk a bit more about this below.

How Checking an Item Works

To check whether a username exists in the filter, you run it through the same hash functions and check whether all the resulting positions are set to 1.

Checking "seyi_codes" which was added:

hash1("seyi_codes") = 3  → bit[3] = 1  ✓
hash2("seyi_codes") = 7  → bit[7] = 1  ✓
hash3("seyi_codes") = 11 → bit[11] = 1 ✓

All three positions are 1. The filter says "probably here." We confirm with the database, and see that the username is taken.

Checking "john_doe" which was never added:

hash1("john_doe") = 2  → bit[2] = 0  ✗

The very first hash returned a position that is still 0. We stop immediately. The filter says "definitely not here." We don't check the remaining hash functions. We don't touch the database. The username is available.

This early exit is critical to understanding why Bloom Filters are fast. The moment any hash function returns a 0 bit, the check is over. An item that was actually added would have set all its positions to 1. A 0 anywhere proves the item was never added.

False Positives Explained

Here's where the probabilistic part becomes concrete.

Check the username "tiwa_codes" which was never added:

hash1("tiwa_codes") = 3  → bit[3] = 1  ✓  (set by seyi_codes)
hash2("tiwa_codes") = 7  → bit[7] = 1  ✓  (set by seyi_codes and aderonke)
hash3("tiwa_codes") = 13 → bit[13] = 1 ✓  (set by aderonke)

All three positions are 1. The filter says "probably here." But "tiwa_codes" was never added. The bits at positions 3, 7, and 13 were set by other usernames. "tiwa_codes" happened to hash to positions that were already occupied.

This is a false positive. The filter is wrong. But it's wrong in the acceptable direction. It said "probably here" when the answer is actually "not here." We go to the database, confirm the username is actually available, and proceed.

The filter never makes the opposite mistake. It will never say "definitely not here" for something that was actually added, because adding an item sets all its positions to 1, and the check verifies all positions are 1.

Why You Can't Delete From a Bloom Filter

Deletion isn't possible in a standard Bloom Filter.

If you tried to delete "seyi_codes" by flipping its bits back to 0, you would flip position 7 back to 0. But position 7 is also used by "aderonke." Now "aderonke" would appear to be absent from the filter even though it was never removed.

This is a fundamental limitation. The filter doesn't track which item set which bit. Bits are shared. Removing one item's bits would corrupt the representation of other items.

Variations like the Counting Bloom Filter solve this by storing a count at each position instead of a single bit (and incrementing the count on add and decrementing on delete). But counting filters use significantly more memory.

The False Positive Rate

The false positive rate isn't random. It's determined mathematically by three parameters:

m is the size of the bit array. A larger array means more positions available, fewer collisions, lower false positive rate, and more memory consumed.

n is the number of items added to the filter. As more items are added, more bits are set to 1. More bits set to 1 means more positions are already occupied by other items, which means higher probability of false positives.

k is the number of hash functions. More hash functions means each item leaves a more specific fingerprint. Initially this reduces false positives. But as the array fills up, more hash functions means more positions to check, each of which has a higher probability of already being set.

For a filter with a 1% false positive rate representing 100 million items, you need approximately 958 million bits (about 120 megabytes). The actual usernames stored as strings would require several gigabytes. The filter achieves a 95% reduction in memory by storing fingerprints instead of values.

For most production systems, a false positive rate between 0.1% and 1% strikes the right balance. At 1%, 99% of "username available" queries never touch the database. The 1% that are false positives go to the database for confirmation and get resolved correctly there.

Implementation in Dart

This is an educational implementation showing the mechanics of how a Bloom Filter works. In production systems, Bloom Filters are built into the infrastructure layers (databases, caches, or CDNs) rather than implemented at the application level.

import 'dart:typed_data';

class BloomFilter {
  final Uint8List _bitArray;
  final int _size;
  final int _hashCount;

  BloomFilter({required int size, required int hashCount})
      : _size = size,
        _hashCount = hashCount,
        _bitArray = Uint8List((size / 8).ceil());

  // set a bit at the given position
  void _setBit(int position) {
    final byteIndex = position ~/ 8;
    final bitIndex = position % 8;
    _bitArray[byteIndex] |= (1 << bitIndex);
  }

  // check if a bit is set at the given position
  bool _getBit(int position) {
    final byteIndex = position ~/ 8;
    final bitIndex = position % 8;
    return (_bitArray[byteIndex] & (1 << bitIndex)) != 0;
  }

  // generate k hash positions for a given value
  List<int> _getHashPositions(String value) {
    final positions = <int>[];

    for (int i = 0; i < _hashCount; i++) {
      int hash = 0;
      final input = '$i:$value'; 

      for (final char in input.codeUnits) {
        hash = (hash * 31 + char) & 0x7FFFFFFF;
      }

      positions.add(hash % _size);
    }

    return positions;
  }

  // add an item to the filter
  void add(String value) {
    for (final position in _getHashPositions(value)) {
      _setBit(position);
    }
  }

  // check if an item might be in the filter
  // returns false: definitely NOT in the set
  // returns true: PROBABLY in the set (may be a false positive)
  bool mightContain(String value) {
    for (final position in _getHashPositions(value)) {
      if (!_getBit(position)) {
        return false; 
      }
    }
    return true; 
  }
}

Let's walk through the key decisions in this implementation.

First, Uint8List is used for the bit array instead of a List<bool>. A List<bool> in Dart allocates a full object per element. A Uint8List packs 8 bits per byte, which is how Bloom Filters achieve their memory efficiency. The _setBit and _getBit methods handle the byte and bit index arithmetic.

_getHashPositions generates k different positions for a given value by seeding each hash function differently using the index i. Prepending '$i:$value' ensures each of the k hash functions produces a different result for the same input. The result is taken modulo _size to map the hash to a valid bit position in the filter.

mightContain returns false the moment any position is not set. This is the early exit that makes checking fast. If all positions are set, it returns true, which means the item is probably in the set but might be a false positive.

Using the Bloom Filter:

void main() {
  // filter sized for roughly 1000 items with low false positive rate
  final filter = BloomFilter(size: 10000, hashCount: 3);

  // add usernames to the filter
  final registeredUsernames = [
    'seyi_codes',
    'aderonke_dev',
    'inioluwa_tech',
    'tiwaloluwa',
    'flutter_ninja',
  ];

  for (final username in registeredUsernames) {
    filter.add(username);
    print('Added: $username');
  }

  print('');

  // check some usernames
  final usernamesToCheck = [
    'seyi_codes',      // was added — should return true
    'aderonke_dev',    // was added — should return true
    'john_doe',        // was not added — should return false
    'new_user_123',    // was not added — should return false
    'random_handle',   // was not added — should return false
  ];

  for (final username in usernamesToCheck) {
    final result = filter.mightContain(username);
    if (result) {
      print('$username: PROBABLY taken — confirm with database');
    } else {
      print('$username: DEFINITELY available — skip the database');
    }
  }
}

Output:

Added: seyi_codes
Added: aderonke_dev
Added: inioluwa_tech
Added: tiwaloluwa
Added: flutter_ninja

seyi_codes: PROBABLY taken — confirm with database
aderonke_dev: PROBABLY taken — confirm with database
john_doe: DEFINITELY available — skip the database
new_user_123: DEFINITELY available — skip the database
random_handle: DEFINITELY available — skip the database

The items that were added return "probably taken" and would trigger a database confirmation. The items that were never added return "definitely available" and skip the database entirely.

Simulating the false positive rate:

void measureFalsePositiveRate() {
  final filter = BloomFilter(size: 1000, hashCount: 3);
  final random = Random();

  // add 100 items
  final addedItems = <String>{};
  for (int i = 0; i < 100; i++) {
    final item = 'user_$i';
    filter.add(item);
    addedItems.add(item);
  }

  // check 1000 items that were never added
  int falsePositives = 0;
  int totalChecks = 1000;

  for (int i = 100; i < 100 + totalChecks; i++) {
    final item = 'user_$i'; 
    if (filter.mightContain(item)) {
      falsePositives++;
    }
  }

  final rate = (falsePositives / totalChecks * 100).toStringAsFixed(2);
  print('False positive rate: $rate% ($falsePositives out of $totalChecks)');
}

Running this demonstrates that false positives are real but controlled. Change the filter size and hash count and you can observe the false positive rate change accordingly.

Implementation in C#

using System;
using System.Collections;
using System.Text;

public class BloomFilter
{
    private readonly BitArray _bitArray;
    private readonly int _size;
    private readonly int _hashCount;

    public BloomFilter(int size, int hashCount)
    {
        _size = size;
        _hashCount = hashCount;
        _bitArray = new BitArray(size);
    }

    private int[] GetHashPositions(string value)
    {
        var positions = new int[_hashCount];

        for (int i = 0; i < _hashCount; i++)
        {
            var input = $"{i}:{value}";
            var bytes = Encoding.UTF8.GetBytes(input);

            int hash = 0;
            foreach (var b in bytes)
            {
                hash = (hash * 31 + b) & 0x7FFFFFFF;
            }

            positions[i] = hash % _size;
        }

        return positions;
    }

    public void Add(string value)
    {
        foreach (var position in GetHashPositions(value))
        {
            _bitArray[position] = true;
        }
    }

    // false  = definitely NOT in the set
    // true   = PROBABLY in the set
    public bool MightContain(string value)
    {
        foreach (var position in GetHashPositions(value))
        {
            if (!_bitArray[position])
                return false;
        }
        return true;
    }
}

C# provides BitArray from System.Collections which handles the bit-level storage natively. The logic is identical to the Dart implementation: the same hashing approach, the same early exit on a zero bit, and the same probabilistic return value.

Using it in a realistic C# API scenario:

public class UsernameService
{
    private readonly BloomFilter _bloomFilter;
    private readonly IUserRepository _userRepository;

    public UsernameService(IUserRepository userRepository)
    {
        _userRepository = userRepository;

        // sized for 10 million usernames, ~1% false positive rate
        _bloomFilter = new BloomFilter(size: 95_850_584, hashCount: 7);

        // populate the filter from existing usernames on startup
        LoadExistingUsernames();
    }

    private void LoadExistingUsernames()
    {
        // stream usernames from database to avoid loading all into memory
        foreach (var username in _userRepository.StreamAllUsernames())
        {
            _bloomFilter.Add(username);
        }
    }

    public async Task<bool> IsUsernameAvailableAsync(string username)
    {
        // check the filter first — O(k) where k is the number of hash functions
        if (!_bloomFilter.MightContain(username))
        {
            // definitely not taken — no database query needed
            return true;
        }

        // probably taken — confirm with the database
        // this handles both true positives and false positives
        var existingUser = await _userRepository.FindByUsernameAsync(username);
        return existingUser == null;
    }

    public async Task RegisterUsernameAsync(string username)
    {
        // add to the filter when a new username is registered
        _bloomFilter.Add(username);
        await _userRepository.CreateUserAsync(username);
    }
}

This is the pattern used in production systems. The Bloom Filter sits in front of the database. Most username availability checks never reach the database. The ones that do are either true positives (username is actually taken) or false positives (the filter was wrong, but the database confirms that the username is actually available).

The service adds new usernames to both the filter and the database on registration. On startup, it populates the filter from existing database records by streaming them rather than loading all into memory at once.

Where Bloom Filters Are Used in Real Systems

Instagram and Twitter: Username Availability

The filter is checked before any database query. A "definitely not here" result skips the database entirely. A "probably here" result triggers a database confirmation. The vast majority of registration attempts get resolved without touching the database.

Google Chrome: Safe Browsing

Chrome ships with a Bloom Filter of known malicious URLs embedded directly in the browser. When you visit any URL, Chrome checks the local filter first. If the filter says "definitely not malicious," no network request is made. If it says "probably malicious," Chrome contacts Google's servers to confirm. Billions of URL checks happen locally with zero network latency.

Apache Cassandra

Each SSTable (storage file on disk) has an associated Bloom Filter in memory. When querying for a key, Cassandra checks the filter for each SSTable first. A "definitely not here" result means Cassandra skips that SSTable entirely, avoiding an expensive disk read. This is one of the primary reasons Cassandra can sustain high read throughput on large datasets.

Medium: Recommendation Engine

Medium tracks which articles each user has already read using Bloom Filters. Before recommending an article, the filter is checked. A "definitely not read" result means the article is a candidate for recommendation. The filter prevents the same article from being recommended to a user who has already seen it, without storing the entire read history in a queryable database for every recommendation request.

Akamai CDN: Cache Management

Akamai uses Bloom Filters to identify one-hit wonders: content that's requested only once and isn't worth caching. When content is requested for the first time, it's added to the filter. If it appears in the filter on a subsequent request, it might be worth caching. Content that never appears twice in the filter isn't cached, saving expensive cache storage for content that actually benefits from it.

When to Use a Bloom Filter

Use a Bloom Filter when you need to check membership in a very large set and the cost of false positives is low.

The ideal scenario is one where a "definitely not here" answer lets you skip an expensive operation entirely, like a database query, network request, disk read, or cache miss. If the cost of that operation is significant and most checks return "not here," a Bloom Filter can eliminate the majority of those expensive operations.

You can also use it when memory efficiency matters. When the set is so large that storing the actual values would be prohibitively expensive in memory, a Bloom Filter represents that set in a fraction of the space.

And it's a good fit when false positives are acceptable and recoverable. If a false positive means one extra database query, that's acceptable. If a false positive means data loss or incorrect behavior, a Bloom Filter isn't the right tool.

When Not to Use It

Don't use a Bloom Filter when you need exact membership testing with no false positives. A hash set or a database index gives you exact answers. If the cost of a false positive isn't acceptable, use an exact data structure.

Don't use it when you need to retrieve the actual stored values. A Bloom Filter stores no values. You can't get anything back from it except a yes or no answer.

It's also not a good idea when items need to be deletable. Standard Bloom Filters don't support deletion. If your use case requires removing items from the set, use a Counting Bloom Filter or a different data structure entirely.

Finally, don't use it for small sets. If the set is small enough that a hash set fits comfortably in memory, use a hash set. The complexity of a Bloom Filter isn't justified when an exact solution is available at the same memory cost.

Conclusion

A Bloom Filter solves a specific problem with unusual elegance. When the set is enormous and checking membership against it directly is expensive, the filter acts as a fast, memory-efficient pre-check.

It tells you with absolute certainty when something is not in the set. That certainty is what makes it valuable. Every "definitely not here" answer is a database query avoided, a network request saved, and a disk read skipped.

The false positives are the price of that efficiency. A small, controlled, mathematically predictable rate of wrong answers in the "probably here" direction. Wrong in the direction that costs you one extra confirmation. Never wrong in the direction that causes you to miss something that was actually there.

Instagram uses this to protect a database with 500 million rows. Google uses this to check malicious URLs without a network request. Cassandra uses this to skip disk reads on terabytes of data. The pattern is the same in every case: an expensive operation sits behind a fast, probabilistic gate. The gate lets through only what needs to go through.

That's what a Bloom Filter does. And that's why it's one of the most quietly powerful data structures in modern systems engineering.

Understanding this definitely equips your architectural decision for large systems query and data set.

Happy Coding!!

But the moment they press the home button, everything stops. A sync that should have completed in the background never ran. A notification that should have fired didn't. A file upload that started while the user was in the app failed silently the moment they switched away.

Background execution on mobile is one of the most misunderstood topics in the entire mobile engineering space. Most developers treat it like a simple problem: just keep the code running in the background. The platforms treat it like a resource management problem that directly affects battery life, performance, and the overall health of the device.

Understanding how iOS and Android actually think about background work, and then understanding how Flutter sits on top of both, is what separates engineers who fight the platform from engineers who work with it.

This article covers exactly that. You'll understand the native mechanisms on both platforms, the Flutter packages that bridge them, and when to reach for each approach.

Table of Contents

• Why Background Execution is Hard

• How Flutter Runs in the Background

• iOS Background Execution

• Android Background Execution

• Flutter Implementation

• The Decision Framework

• Conclusion

Prerequisites

This article is written for mobile engineers building or maintaining production applications on iOS, Android, or Flutter. Before reading, you should be comfortable with:

• The basic lifecycle of a mobile app: what happens when the app moves between foreground, background, and suspended states

• General mobile development concepts: you have shipped or maintained at least one mobile application on any platform or framework

• Writing mobile applications in any framework: native iOS, native Android, Flutter, React Native, or any other mobile development stack

• Multithreading and concurrency in your programming language of choice: understanding how your language handles work that runs outside the main thread is the foundation of everything this article covers

If you're completely new to mobile development or have never had to think about threads and concurrent execution, start with those fundamentals first and return to this article when you are ready to think about production-grade background work.

Why Background Execution is Hard

When your app is in the foreground, the platform gives it essentially full access to CPU, network, and memory. The user is actively looking at the app. Battery drain is expected. Resource usage is justified.

The moment the app goes to the background, the calculus changes completely. There are potentially dozens of apps installed on the device. If every one of them ran freely in the background, the battery would drain in hours. The CPU would be constantly active. Memory would fill up. The device would become hot and slow.

Both iOS and Android made a decision early on that background execution is a privilege, not a right. Apps must earn the right to run in the background by declaring what they need and why. The platform then decides how, when, and for how long to grant that access.

iOS and Android approached this problem differently but have been converging toward the same model over time: declared, categorized, and constrained background work that the platform controls.

How Flutter Runs in the Background

Before looking at iOS and Android separately, you need to understand something fundamental about how Flutter works.

Flutter runs your Dart code in a single main isolate. This isolate is attached to the platform's main thread. It handles your UI, your business logic, everything. When the app goes to the background, this main isolate can be suspended at any time.

When background work needs to happen in Flutter, the platform doesn't wake your main isolate. It wakes a separate, independent Dart isolate specifically for background execution. This background isolate runs in complete isolation from the main isolate.

What This Means Practically:

The background isolate has no access to the widget tree. You can't call setState, update any UI, or use any widget or BuildContext. It's pure Dart execution with no UI layer.

The background isolate doesn't share memory with the main isolate. Any data you need in the background must be persisted to disk (shared preferences, local database, files) and read by the background isolate independently.

The background isolate must be a top-level function or a static method. It can't be an anonymous function or a method on a class instance. The platform needs to be able to call this function by name when waking the app.

Understanding this changes how you think about background work in Flutter. You aren't keeping your app running. You're registering a separate piece of Dart code that the platform can invoke on its own schedule, in its own isolated environment.

iOS Background Execution

What iOS Does to Your App

iOS manages your app through a set of clearly defined states.

When the user presses the home button, your app moves from foreground to background. iOS gives you a very brief window, typically five to ten seconds, to finish whatever you were doing. After that, your app is suspended. Suspended means completely frozen in memory. No Dart code runs. No network requests go out. The app exists in RAM but is essentially paused.

iOS can kill suspended apps at any time if it needs memory. When the user returns to your app, iOS either resumes it from suspension (fast) or relaunches it from scratch (slow). If your app was killed while suspended, the user won't know. The app just relaunches normally.

To do anything meaningful in the background on iOS, you must declare your intentions. iOS has a specific list of background capabilities, and your app must request exactly the ones it needs. Apple reviews these declarations during App Store submission.

BGTaskScheduler

BGTaskScheduler is the modern iOS API for scheduling background work. Introduced in iOS 13, it replaced older and less reliable approaches. It gives you two types of tasks.

BGAppRefreshTask is for short, periodic background work. Think of it as iOS giving your app a brief wake-up to check for new content and update its state. You get approximately 30 seconds. iOS decides when to run the task based on the user's usage patterns. If the user opens your app every morning at 8am, iOS learns this and tries to run your refresh task just before 8am so content is ready when they arrive.

BGProcessingTask is for longer, heavier work. Database migrations, large file processing, or ML model updates. You get several minutes. These tasks only run when the device is plugged in and ideally on WiFi. You get more time but no guarantees on when the task actually runs.

The rules iOS enforces are strict.

You must declare your task identifiers in Info.plist under BGTaskSchedulerPermittedIdentifiers before the app ships. If the identifier isn't declared there, the task will never run regardless of what your code does.

You must register your task handler before applicationDidFinishLaunching completes. This happens before Flutter even initializes. The workmanager package handles this automatically, but it's important to understand why.

Every task must call setTaskCompleted when it finishes. If you don't call this, iOS marks the task as failed and becomes increasingly reluctant to schedule future tasks.

You should always set an expiration handler. If iOS decides to kill your task early, it calls the expiration handler first, giving you a brief moment to clean up, save state, and mark the task as incomplete so it gets rescheduled.

iOS Background Modes

Beyond BGTaskScheduler, iOS has specific background modes for certain categories of apps. These are declared in Info.plist and enable continuous background execution for very specific purposes.

Audio and AirPlay keeps your app running as long as it's playing audio. The user sees now-playing controls on the lock screen. Podcast apps, music apps, and navigation apps with voice guidance use this. iOS is generous with this mode because the user clearly intends the audio to continue.

Location Updates allows continuous GPS access even when backgrounded. There are two levels. Significant location changes uses cell tower data and is battery-friendly. It fires when the device moves significantly, roughly 500 meters. Continuous location updates give precise GPS but drain battery. Apple scrutinizes location background mode during review. You need a genuine, user-facing reason.

Background Fetch is a legacy mechanism where iOS periodically wakes your app for a short window to fetch content. Unlike BGAppRefreshTask, this uses the older API. Most new apps should prefer BGTaskScheduler.

Remote Notifications with the content-available flag allows your server to trigger a brief background wake. When your server sends a silent push notification, iOS wakes your app to process it. This is how many apps stay current without constant polling.

The iOS Reality

iOS background execution is fundamentally about trust. Apple trusts your app with background time if you declare what you need, use it for the declared purpose, and respect the time limits.

Exceed your time limit and iOS terminates your app. Request background modes you don't actually need and App Store review will flag it. Use location in the background for purposes not evident to the user and you will face rejection.

The watchdog timer is real. iOS monitors background tasks actively. Tasks that run too long, use too much CPU, or behave unexpectedly get terminated. Build your background tasks to be fast, focused, and respectful of system resources.

Android Background Execution

What Android Does to Your App

Android manages process priority through a hierarchy. Foreground apps get the highest priority. Apps with running services get elevated priority. Background apps have lower priority. Empty processes and apps with no active components have the lowest priority.

When the system needs memory, it kills processes in order of priority, starting from the lowest. Your background app can be killed at any time. An app with a foreground service is much harder to kill. An active foreground app is essentially never killed by the system.

Android was historically more permissive than iOS. Early Android allowed apps to run services indefinitely in the background. This freedom was abused. Apps ran constantly even when the user hadn't interacted with them in weeks. Battery life suffered, and Android had to respond.

Starting with Android 8.0 Oreo, Google began restricting background services. Apps can no longer start background services when the app itself isn't in the foreground. Each subsequent Android version has tightened these restrictions further. Android is converging toward iOS's model of declared, constrained background work.

Foreground Services

A foreground service is the most reliable form of background execution on Android. It runs continuously and must display a persistent notification. The notification is mandatory. It's how Android communicates to the user that something is actively happening. The user can see it, expand it for details, and stop it if they choose.

Music players show the currently playing track with playback controls. Navigation apps show the current route with estimated arrival time. File upload apps show a progress bar. Fitness apps show elapsed time and current stats.

Android 14 introduced foreground service types. You must now declare what kind of foreground service you're running. The types are: mediaPlayback, location, dataSync, camera, microphone, phoneCall, remoteMessaging, shortService, health, and systemExempted. This is Android deliberately moving toward the iOS model of declared categories.

Foreground services are the right choice when the user expects something to be actively happening. Playing music. Navigating. Uploading a file. Anything where there is an ongoing activity that the user initiated and expects to continue.

WorkManager

WorkManager is Google's recommended solution for deferrable, guaranteed background work. The key characteristics that define it are important to understand.

Guaranteed means your work will eventually run. Even if the app exits, the user restarts the device, or the system kills your process, WorkManager persists the task to a local database and retries it when conditions allow. This is fundamentally different from a background service that disappears if the app is killed.

Deferrable means you don't control exactly when the work runs. You define constraints and WorkManager waits until those constraints are satisfied. Constraints can include requiring network connectivity, requiring the device to be charging, or requiring the battery to not be low. WorkManager picks the optimal time within those constraints.

Periodic tasks have a minimum interval of 15 minutes. This is enforced by the platform, not WorkManager. Android doesn't allow apps to schedule work more frequently than this to prevent battery abuse.

Under the hood, WorkManager uses JobScheduler on modern Android. It manages the complexity of backward compatibility and constraint handling for you.

WorkManager is the right choice for: syncing data with a server, uploading logs or analytics, processing downloaded files, cleaning up old cache entries, generating thumbnails, or sending queued messages.

WorkManager is the wrong choice for anything that needs to run immediately, at an exact time, or continuously.

Doze Mode and App Standby

Doze Mode activates when the device is unplugged, stationary, and the screen has been off for an extended period. In Doze, Android suspends network access, defers WorkManager tasks, ignores wake locks, and defers alarms. The system enters this state to conserve battery when the device is clearly not being used.

The system exits Doze periodically for maintenance windows during which deferred work can run. These windows become less frequent the longer the device stays in Doze.

Only high-priority Firebase Cloud Messaging notifications can break through Doze. This is why server-triggered background refresh is so powerful: your server sends a high-priority FCM message, Android wakes the app even in Doze to process it.

App Standby Buckets categorize your app based on how recently and frequently the user has interacted with it. The buckets are Active, Working Set, Frequent, Rare, and Restricted. The bucket your app is in directly affects how much background work it is allowed to do.

Active means the user used your app very recently. Full background execution allowed.

Working Set means the user uses your app regularly. Slight restrictions on how frequently background work can run.

Frequent means the user uses your app often but not daily. More restrictions.

Rare means the user barely uses your app. Significant restrictions. WorkManager tasks get delayed substantially.

Restricted means the app has been flagged for bad behavior or is almost never used. Background work is heavily throttled. The user or the system has effectively put your app on notice.

If your app ends up in the Rare or Restricted bucket, background sync becomes unreliable. The way to avoid this is straightforward: build an app people actually use regularly.

Flutter Implementation

Now let's look at how Flutter engineers implement background work using the native mechanisms above.

Setup: Project Structure

Background work in Flutter requires coordination between your Dart code and the native platform. The packages handle most of this, but there are configuration steps on both the iOS and Android sides that you must complete for the work to actually run.

workmanager

The workmanager package is the most widely used solution for deferrable background tasks in Flutter. It wraps Android WorkManager and iOS BGTaskScheduler.

Add the dependency:

dependencies:
  workmanager: ^0.5.2

On Android, no additional configuration is needed beyond the dependency. WorkManager is part of AndroidX and is available on all modern Android devices.

On iOS, add your task identifiers to Info.plist:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.yourapp.syncTask</string>
  <string>com.yourapp.cleanupTask</string>
</array>

Also add Background Modes capability in Xcode and enable Background fetch and Background processing.

The background callback must be a top-level function. It can't be inside a class:

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((taskName, inputData) async {
    switch (taskName) {
      case 'syncUserData':
        await syncUserData(inputData);
        break;
      case 'cleanupOldFiles':
        await cleanupOldFiles();
        break;
      default:
        print('Unknown task: $taskName');
    }
    return Future.value(true);
  });
}

The @pragma('vm:entry-point') annotation is critical. Without it, the Dart tree shaker may remove this function during release builds because it appears to be uncalled from Dart code. The platform calls it by name, not through Dart, so the tree shaker can't detect the reference.

Returning true from the task tells WorkManager the task succeeded. Returning false tells it the task failed and should be retried.

Initialize workmanager in your main function:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Workmanager().initialize(
    callbackDispatcher,
    isInDebugMode: kDebugMode,
  );

  runApp(const MyApp());
}

isInDebugMode: true logs detailed information about task scheduling and execution. Turn this off in production.

Registering a one-time task:

Future<void> scheduleDataSync() async {
  await Workmanager().registerOneOffTask(
    'syncUserData',
    'syncUserData',
    initialDelay: const Duration(minutes: 5),
    constraints: Constraints(
      networkType: NetworkType.connected,
      requiresBatteryNotLow: true,
    ),
    inputData: {
      'userId': currentUser.id,
      'syncType': 'full',
    },
  );
}

The task will run once, after a minimum 5-minute delay, only when the device has network connectivity and the battery isn't low. The inputData map is passed to the callback and available as the inputData parameter in executeTask.

Registering a periodic task:

Future<void> schedulePeriodicSync() async {
  await Workmanager().registerPeriodicTask(
    'periodicSync',
    'syncUserData',
    frequency: const Duration(hours: 1),
    constraints: Constraints(
      networkType: NetworkType.connected,
    ),
  );
}

The minimum frequency is 15 minutes enforced by the platform. If you set a shorter interval, it gets rounded up to 15 minutes. On iOS, BGTaskScheduler controls the actual timing and may run the task less frequently based on device conditions.

Cancelling tasks:

// cancel one specific task
await Workmanager().cancelByUniqueName('periodicSync');

// cancel all registered tasks
await Workmanager().cancelAll();

flutter_background_service

The workmanager package is great for deferrable work, but sometimes you need something that runs continuously, like a health monitor, a real-time data collector, or a persistent connection.

For that, flutter_background_service creates a long-running service. On Android, this becomes a Foreground Service with a persistent notification. On iOS, it uses a combination of background modes.

Add the dependency:

dependencies:
  flutter_background_service: ^5.0.5
  flutter_local_notifications: ^17.0.0

The background service entry point, again, must be a top-level function:

@pragma('vm:entry-point')
void onStart(ServiceInstance service) async {
  DartPluginRegistrant.ensureInitialized();

  if (service is AndroidServiceInstance) {
    service.on('setAsForeground').listen((event) {
      service.setAsForegroundService();
    });

    service.on('setAsBackground').listen((event) {
      service.setAsBackgroundService();
    });
  }

  service.on('stopService').listen((event) {
    service.stopSelf();
  });

  // your actual background work runs here
  Timer.periodic(const Duration(seconds: 30), (timer) async {
    if (service is AndroidServiceInstance) {
      if (await service.isForegroundService()) {
        service.setForegroundNotificationInfo(
          title: 'App is running',
          content: 'Last sync: ${DateTime.now()}',
        );
      }
    }

    // do the actual work
    await performBackgroundSync();

    // send data to the main isolate if needed
    service.invoke('update', {
      'lastSync': DateTime.now().toIso8601String(),
    });
  });
}

Initialize the service:

Future<void> initializeBackgroundService() async {
  final service = FlutterBackgroundService();

  const AndroidNotificationChannel channel = AndroidNotificationChannel(
    'background_service',
    'Background Service',
    description: 'This channel is used for the background service notification',
    importance: Importance.low,
  );

  final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
      FlutterLocalNotificationsPlugin();

  await flutterLocalNotificationsPlugin
      .resolvePlatformSpecificImplementation<
          AndroidFlutterLocalNotificationsPlugin>()
      ?.createNotificationChannel(channel);

  await service.configure(
    androidConfiguration: AndroidConfiguration(
      onStart: onStart,
      autoStart: true,
      isForegroundMode: true,
      notificationChannelId: 'background_service',
      initialNotificationTitle: 'App Running',
      initialNotificationContent: 'Background sync active',
      foregroundServiceNotificationId: 888,
    ),
    iosConfiguration: IosConfiguration(
      autoStart: true,
      onForeground: onStart,
      onBackground: onIosBackground,
    ),
  );

  await service.startService();
}

Communicating between the background service and your UI:

// in your widget, listen for updates from the background service
class HomeScreen extends StatefulWidget {
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  String lastSync = 'Never';

  @override
  void initState() {
    super.initState();
    FlutterBackgroundService().on('update').listen((event) {
      setState(() {
        lastSync = event?['lastSync'] ?? 'Unknown';
      });
    });
  }

  void stopService() {
    FlutterBackgroundService().invoke('stopService');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          Text('Last sync: $lastSync'),
          ElevatedButton(
            onPressed: stopService,
            child: const Text('Stop Background Service'),
          ),
        ],
      ),
    );
  }
}

The invoke and on methods create a two-way communication channel between the background isolate and the main isolate. The background service invokes events with data. The UI listens for those events and updates accordingly.

background_fetch

For simpler periodic background work where workmanager's full constraint system is more than you need, background_fetch provides a cleaner API.

dependencies:
  background_fetch: ^1.2.1

void main() {
  runApp(const MyApp());
  BackgroundFetch.registerHeadlessTask(backgroundFetchHeadlessTask);
}

@pragma('vm:entry-point')
void backgroundFetchHeadlessTask(HeadlessTask task) async {
  String taskId = task.taskId;
  bool isTimeout = task.timeout;

  if (isTimeout) {
    BackgroundFetch.finish(taskId);
    return;
  }

  await performQuickSync();
  BackgroundFetch.finish(taskId);
}

Configure and start:

Future<void> configureBackgroundFetch() async {
  await BackgroundFetch.configure(
    BackgroundFetchConfig(
      minimumFetchInterval: 15,
      stopOnTerminate: false,
      enableHeadless: true,
      requiresBatteryNotLow: false,
      requiresCharging: false,
      requiresStorageNotLow: false,
      requiresDeviceIdle: false,
      requiredNetworkType: NetworkType.ANY,
    ),
    (taskId) async {
      await performQuickSync();
      BackgroundFetch.finish(taskId);
    },
    (taskId) async {
      // timeout handler
      BackgroundFetch.finish(taskId);
    },
  );
}

Calling BackgroundFetch.finish(taskId) is mandatory. On iOS, failing to call finish tells the platform your task did not complete correctly, which affects future scheduling. On Android, it signals WorkManager that the task is done.

Persisting Data Between Isolates

Since the background isolate and the main isolate don't share memory, data must be persisted to disk.

The most common approaches are shared_preferences for simple key-value data and a local database like sqflite or isar for structured data.

// writing from background isolate
@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((taskName, inputData) async {
    final prefs = await SharedPreferences.getInstance();

    // fetch new data
    final newData = await fetchFromServer();

    // persist for main isolate to read
    await prefs.setString('lastSyncData', jsonEncode(newData));
    await prefs.setString('lastSyncTime', DateTime.now().toIso8601String());

    return Future.value(true);
  });
}

// reading in main isolate when app comes to foreground
class HomeScreen extends StatefulWidget {
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  @override
  void initState() {
    super.initState();
    loadLastSyncedData();
  }

  Future<void> loadLastSyncedData() async {
    final prefs = await SharedPreferences.getInstance();
    final data = prefs.getString('lastSyncData');
    final syncTime = prefs.getString('lastSyncTime');

    if (data != null) {
      setState(() {
        // update your state with the synced data
      });
    }
  }
}

The Decision Framework

Given a background task requirement, here is how to decide which approach to reach for:

Does the user expect something to actively be running, like music playing, navigation running, or a file uploading? Use a Foreground Service via flutter_background_service. The persistent notification isn't just a requirement, it's straightforward communication to the user about what the app is doing.

Does the work need to happen eventually but not necessarily right now? Something like syncing data, uploading logs, processing files, or cleaning the cache. If so, use workmanager. It guarantees the work runs, respects constraints, and survives app restarts and device reboots.

Does the work need to happen on a server-triggered signal? Use Firebase Cloud Messaging with a high-priority silent notification. Your server sends the signal, iOS and Android wake your app, your background isolate handles the work. This breaks through Doze Mode on Android and works with iOS's silent push mechanism.

Does the work need to happen on a simple periodic schedule with minimal constraints? Use background_fetch for a simpler API when workmanager's full constraint system is more than you need.

Does the work need precise timing? Rethink whether it truly needs to happen in the background. If a user sets a reminder for 3pm, a local notification is the right approach. The notification fires at the exact time regardless of whether the app is in the background.

One note about iOS specifically: no Flutter package can work around Apple's restrictions. If you register a BGAppRefreshTask, iOS decides when it runs. If you set constraints on WorkManager, Android decides when they're satisfied. The platform is in control. Your job is to declare what you need clearly, handle it correctly when the platform gives you the window, and build your app to be resilient when the background work runs later than expected.

Conclusion

Background execution on mobile isn't a Flutter problem or a Dart problem. It's a platform problem that Flutter sits on top of.

iOS is restrictive by design. You declare the specific category of background work you need. Apple evaluates whether that use case is legitimate. When granted, the platform gives you controlled, time-limited windows. Exceed those windows and the system terminates your task.

Android started permissive and has been getting stricter with every major version. Foreground Services give reliable continuous execution with a visible notification. WorkManager gives guaranteed deferred execution with constraints. Doze Mode and App Standby Buckets restrict everything else based on device state and user behavior.

Flutter bridges both through packages that map to the native APIs. workmanager covers deferrable work on both platforms. flutter_background_service covers continuous work with a foreground notification. background_fetch covers simple periodic work with a cleaner API.

The engineers who succeed with mobile background work are the ones who understand what the platform is actually doing and design with those constraints in mind. They don't fight the platform. They declare what they need, handle the windows they're given, persist state properly across isolate boundaries, and build their systems to be resilient when background work is delayed or deferred.

That's how background work actually gets done on mobile.

Understanding the core of background processes and app lifecycle in native and hybrid mobile engineering helps you make an informed architectural decision when selecting the task handler needed to run a specific task.

Happy Coding!!

It starts small: a simple validation check, an if statement here, another there. Then requirements grow and more conditions get added. The function gets longer. Someone adds a comment that says "don't modify without reading the full thing first." The function becomes a rite of passage. New developers are warned about it during onboarding.

This is what happens when complex business rules pile up in one place without a deliberate structure to contain them.

The Chain of Responsibility pattern exists to prevent exactly this. Instead of one method that knows everything and does everything, you build a chain of focused handlers. Each handler knows one rule and checks whether the request passes its rule. If it does, the request moves forward to the next handler. If it doesn't, the chain stops right there.

No handler knows how long the chain is. No handler knows what comes before or after it. Each one just does its job and decides: stop here, or pass it forward.

Table of Contents

• What is the Chain of Responsibility Pattern?

• The Problem It Solves

• Core Components

• Real World Example One: Transaction Approval Flow

• Real World Example Two: User Onboarding Validation

• What Makes These Two Examples Interesting Together

• When to Use the Chain of Responsibility Pattern

• When Not to Use It

• Conclusion

What is the Chain of Responsibility Pattern?

The Chain of Responsibility is a behavioral design pattern that lets you pass a request along a chain of handlers. Each handler in the chain decides either to process the request and stop the chain, or to pass the request to the next handler.

The pattern gives you three things that matter in production systems.

First, it decouples the sender of a request from its receivers. The code that initiates a transaction validation doesn't know which handler will ultimately process it or stop it. It just starts the chain.

Second, it gives you a single responsibility per handler. Each handler owns exactly one business rule. When that rule changes, you modify one class. Nothing else changes.

Third, it makes the chain configurable. You can add, remove, or reorder handlers without touching existing handler code. A new compliance requirement becomes a new handler plugged into the chain, not a new branch inside an existing method.

The Problem It Solves

Here's what transaction validation looks like without the pattern:

void handleTransaction(Transaction transaction) {
  if (transaction.isFraud) {
    // block transaction
    return;
  }

  if (!transaction.isKycVerified) {
    // reject transaction
    return;
  }

  if (!transaction.isAccountActive) {
    // reject transaction
    return;
  }

  if (transaction.amount < 50000) {
    // junior officer approval
    return;
  }

  if (transaction.amount <= 200000) {
    // mid level approval
    return;
  }

  if (transaction.amount <= 1000000) {
    // manager approval
    return;
  }

  // executive approval
}

This works today. Tomorrow your compliance team adds a credit score check. Your fraud team adds a velocity check. Your legal team adds a sanctions screening step. Your product manager adds a daily limit check.

Every new rule goes into this same method. The method grows to fifty lines. Then a hundred. The conditions interact in ways that are hard to reason about. Testing it requires setting up every possible combination of flags. A bug in one condition can affect every other condition below it.

The Chain of Responsibility pattern says: each rule gets its own handler. Chain the handlers together. The method that starts the chain doesn't need to know any of the rules. It just starts the chain and gets out of the way.

Core Components

The pattern has three building blocks.

1. The Handler Interface

This is the contract every handler in the chain must implement. It declares the method for handling a request and provides the mechanism for linking handlers together. Every concrete handler extends or implements this.

2. The Concrete Handlers

These are the actual implementations. Each one owns exactly one business rule. It checks whether the request satisfies its rule. If the rule fails, it stops the chain and handles the failure. If the rule passes, it calls the next handler and passes the request forward.

3. The Chain

This isn't a class. It's the act of connecting handlers together using the setNext method. You build the chain in your composition root or your dependency injection setup. The order you connect them is the order they execute.

Real World Example One: Transaction Approval Flow

A fintech platform processes thousands of transactions daily. Before any transaction is approved, it must pass through several validation and approval gates. Each gate is independent. Each one has a single responsibility.

The gates in order:

1. Fraud check: is this transaction flagged as fraudulent?

2. KYC verification: has the user completed identity verification?

3. Account status: is the account active and in good standing?

4. Approval level: which officer tier has the authority to approve this amount?

The Transaction Model

class Transaction {
  final num amount;
  final bool isFraud;
  final bool isKycVerified;
  final bool isAccountActive;

  const Transaction({
    required this.amount,
    required this.isFraud,
    required this.isKycVerified,
    required this.isAccountActive,
  });
}

The transaction model carries all the data each handler needs to make its decision. It owns the data and nothing else. No validation logic lives here.

The Handler Interface

abstract class TransactionHandler {
  TransactionHandler? _next;

  void setNext(TransactionHandler handler) {
    _next = handler;
  }

  void handle(Transaction transaction);

  void passToNext(Transaction transaction) {
    if (_next != null) {
      _next!.handle(transaction);
    } else {
      print('End of chain reached with no handler stopping the transaction');
    }
  }
}

TransactionHandler is the contract every handler implements.

_next is nullable because the last handler in the chain has no next handler. Making it nullable and checking before calling prevents a null pointer crash at the end of the chain.

setNext connects one handler to the next. You call this when building the chain.

passToNext is a helper method that every concrete handler calls when its rule passes. It checks whether a next handler exists before calling it. If we reach the end of the chain without any handler stopping the transaction, we log it. In a real system, this would trigger an alert because it means the chain wasn't configured correctly.

The Concrete Handlers

class FraudHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (transaction.isFraud) {
      print('Transaction blocked: fraud detected');
      return;
    }
    print('Fraud check passed');
    passToNext(transaction);
  }
}

FraudHandler is the first gate. If the transaction is flagged as fraudulent, it prints a rejection message and returns. The chain stops here. No other handler sees this transaction. If the fraud check passes, it calls passToNext and the transaction moves to the next handler.

class KycHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (!transaction.isKycVerified) {
      print('Transaction blocked: KYC verification incomplete');
      return;
    }
    print('KYC check passed');
    passToNext(transaction);
  }
}

KycHandler checks whether the user has completed identity verification. If they haven't, the chain stops. If they have, the transaction moves forward. This handler knows nothing about fraud checks. It knows nothing about account status. It owns one rule.

class AccountHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (!transaction.isAccountActive) {
      print('Transaction blocked: account is not active');
      return;
    }
    print('Account status check passed');
    passToNext(transaction);
  }
}

AccountHandler checks account status. Same pattern, one rule: stop or pass.

class ApprovalHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (transaction.amount < 50000) {
      print('Approved by Junior Officer — amount: ${transaction.amount}');
      return;
    }

    if (transaction.amount <= 200000) {
      print('Approved by Mid-Level Officer — amount: ${transaction.amount}');
      return;
    }

    if (transaction.amount <= 1000000) {
      print('Approved by Manager — amount: ${transaction.amount}');
      return;
    }

    print('Escalated to Executive Approval — amount: ${transaction.amount}');
    passToNext(transaction);
  }
}

ApprovalHandler is the final gate. It routes the transaction to the appropriate approval tier based on amount. Transactions below 50,000 are approved by a junior officer. Up to 200,000 go to a mid-level officer. Up to 1,000,000 go to a manager. Above that, the transaction is escalated further.

Note that this handler can still call passToNext if the amount exceeds the manager threshold, allowing you to add an executive handler to the chain later without touching ApprovalHandler.

Building and Running the Chain

void main() {
  // create the handlers
  final fraud = FraudHandler();
  final kyc = KycHandler();
  final account = AccountHandler();
  final approval = ApprovalHandler();

  // build the chain
  fraud.setNext(kyc);
  kyc.setNext(account);
  account.setNext(approval);

  // test with a fraudulent transaction
  print('Test 1: Fraudulent Transaction');
  final fraudulentTransaction = Transaction(
    amount: 100000,
    isFraud: true,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(fraudulentTransaction);

  // test with unverified KYC
  print('Test 2: KYC Not Verified');
  final unverifiedTransaction = Transaction(
    amount: 50000,
    isFraud: false,
    isKycVerified: false,
    isAccountActive: true,
  );
  fraud.handle(unverifiedTransaction);

  // test with a valid transaction
  print('Test 3: Valid Transaction');
  final validTransaction = Transaction(
    amount: 150000,
    isFraud: false,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(validTransaction);

  // test with a high value transaction
  print('Test 4: Executive Level Transaction');
  final executiveTransaction = Transaction(
    amount: 2000000,
    isFraud: false,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(executiveTransaction);
}

Output:

Test 1: Fraudulent Transaction
Transaction blocked: fraud detected

Test 2: KYC Not Verified
Fraud check passed
Transaction blocked: KYC verification incomplete

Test 3: Valid Transaction
Fraud check passed
KYC check passed
Account status check passed
Approved by Mid-Level Officer — amount: 150000

Test 4: Executive Level Transaction
Fraud check passed
KYC check passed
Account status check passed
Escalated to Executive Approval — amount: 2000000
End of chain reached with no handler stopping the transaction

Test 1 stops at the first handler. Test 2 passes fraud but stops at KYC. Test 3 passes all validation handlers and gets routed to the correct approval tier. Test 4 exceeds the manager threshold and gets escalated.

Notice that the calling code always starts from fraud.handle(transaction). It doesn't know how many handlers exist. It doesn't know which handler will stop the chain. And it doesn't know what the approval tiers are. It just hands the transaction to the first handler and the chain takes over.

When your compliance team adds a User Indemnity check next month, you create a UserIdemnityCheck, add it to the chain, and nothing else changes:

final indemnity = UserIndemnityStatus();

fraud.setNext(indemnity);
indemnity.setNext(kyc);
kyc.setNext(account);
account.setNext(approval);

One new class and one updated chain setup. Every existing handler untouched.

Real World Example Two: User Onboarding Validation

A user fills in a registration form and submits it. Before the account is created, the request must pass through several validation steps. If any step fails, the user gets a specific error explaining exactly what went wrong.

The steps in order:

1. Email validation: is the email format valid?

2. Password strength: does the password meet security requirements?

3. Age verification: is the user old enough to register?

4. Duplicate account check: does an account already exist with this email?

5. Account creation: all checks passed, create the account

The Registration Request Model

class RegistrationRequest {
  final String email;
  final String password;
  final int age;

  const RegistrationRequest({
    required this.email,
    required this.password,
    required this.age,
  });
}

The Handler Interface

abstract class RegistrationHandler {
  RegistrationHandler? _next;

  void setNext(RegistrationHandler handler) {
    _next = handler;
  }

  void handle(RegistrationRequest request);

  void passToNext(RegistrationRequest request) {
    if (_next != null) {
      _next!.handle(request);
    }
  }
}

This is the same structure as before. Nullable next, SetNext to build the chain, and PassToNext to move the request forward.

The Concrete Handlers

class EmailValidationHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    final emailRegex = RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$');

    if (!emailRegex.hasMatch(request.email)) {
      print('Registration failed: invalid email format — ${request.email}');
      return;
    }

    print('Email validation passed');
    passToNext(request);
  }
}

EmailValidationHandler checks the email format using a regex. If the format is invalid, it stops the chain immediately with a specific message. If it's valid, the request moves forward.

class PasswordStrengthHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    final password = request.password;
    final hasMinLength = password.length >= 8;
    final hasUppercase = password.contains(RegExp(r'[A-Z]'));
    final hasNumber = password.contains(RegExp(r'[0-9]'));
    final hasSpecialChar = password.contains(RegExp(r'[!@#\$%^&*]'));

    if (!hasMinLength || !hasUppercase || !hasNumber || !hasSpecialChar) {
      print('Registration failed: password does not meet security requirements');
      print('Requirements: 8+ characters, uppercase, number, special character');
      return;
    }

    print('Password strength check passed');
    passToNext(request);
  }
}

PasswordStrengthHandler enforces four password rules in one place. Minimum length, at least one uppercase letter, at least one number, and at least one special character. If any of these fail, the user gets a clear message explaining all the requirements. If all pass, the request moves forward.

class AgeVerificationHandler extends RegistrationHandler {
  final int minimumAge;

  AgeVerificationHandler({this.minimumAge = 18});

  @override
  void handle(RegistrationRequest request) {
    if (request.age < minimumAge) {
      print('Registration failed: user must be at least $minimumAge years old');
      return;
    }

    print('Age verification passed');
    passToNext(request);
  }
}

AgeVerificationHandler checks the user's age against a minimum threshold. Notice that this handler accepts the minimum age as a constructor parameter. This makes it configurable without modifying the class. If the minimum age requirement changes from 18 to 16 for a specific product, you just pass a different value when building the chain.

class DuplicateAccountHandler extends RegistrationHandler {
  final Set<String> existingEmails;

  DuplicateAccountHandler({required this.existingEmails});

  @override
  void handle(RegistrationRequest request) {
    if (existingEmails.contains(request.email)) {
      print('Registration failed: an account already exists with ${request.email}');
      return;
    }

    print('Duplicate account check passed');
    passToNext(request);
  }
}

DuplicateAccountHandler checks whether an account already exists with the provided email. In a real system, this would call a repository or database. Here we use a Set of existing emails to keep the example focused on the pattern.

class AccountCreationHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    print('All validation passed');
    print('Creating account for: ${request.email}');
    // call account creation service
    print('Account created successfully');
  }
}

AccountCreationHandler is the final handler. It only runs if every previous handler passed the request forward. By the time execution reaches here, the request has been validated on every dimension. This handler simply creates the account.

Building and Running the Chain

void main() {
  final existingEmails = {'existing@seyi.com', 'taken@seyi.com'};

  // create the handlers
  final emailValidation = EmailValidationHandler();
  final passwordStrength = PasswordStrengthHandler();
  final ageVerification = AgeVerificationHandler(minimumAge: 18);
  final duplicateCheck = DuplicateAccountHandler(existingEmails: existingEmails);
  final accountCreation = AccountCreationHandler();

  // build the chain
  emailValidation.setNext(passwordStrength);
  passwordStrength.setNext(ageVerification);
  ageVerification.setNext(duplicateCheck);
  duplicateCheck.setNext(accountCreation);

  // test with invalid email
  print('Test 1: Invalid Email');
  emailValidation.handle(RegistrationRequest(
    email: 'notanemail',
    password: 'SecureP@ss1',
    age: 25,
  ));

  // test with weak password
  print('Test 2: Weak Password');
  emailValidation.handle(RegistrationRequest(
    email: 'user@example.com',
    password: 'weak',
    age: 25,
  ));

  // test with underage user
  print('Test 3: Underage User');
  emailValidation.handle(RegistrationRequest(
    email: 'young@example.com',
    password: 'SecureP@ss1',
    age: 16,
  ));

  // test with duplicate account
  print('Test 4: Duplicate Account');
  emailValidation.handle(RegistrationRequest(
    email: 'existing@example.com',
    password: 'SecureP@ss1',
    age: 25,
  ));

  // test with valid registration
  print('Test 5: Valid Registration');
  emailValidation.handle(RegistrationRequest(
    email: 'newuser@example.com',
    password: 'SecureP@ss1',
    age: 25,
  ));
}

Output:

Test 1: Invalid Email
Registration failed: invalid email format — notanemail

Test 2: Weak Password
Email validation passed
Registration failed: password does not meet security requirements
Requirements: 8+ characters, uppercase, number, special character

Test 3: Underage User
Email validation passed
Password strength check passed
Age verification passed
Registration failed: user must be at least 18 years old

Test 4: Duplicate Account
Email validation passed
Password strength check passed
Age verification passed
Duplicate account check passed
Registration failed: an account already exists with existing@example.com

Test 5: Valid Registration
Email validation passed
Password strength check passed
Age verification passed
Duplicate account check passed
All validation passed
Creating account for: newuser@example.com
Account created successfully

Each test stops at exactly the right handler. Each failure message is specific. The valid registration flows through all five handlers and creates the account.

When a new requirement arrives, say a phone number verification step before account creation, you create a PhoneVerificationHandler and plug it into the chain between duplicate check and account creation. Five existing handlers remain completely untouched.

What Makes These Two Examples Interesting Together

The transaction flow and the onboarding flow look similar on the surface, but they represent two different ways the pattern gets used in production.

The transaction flow combines validation handlers and routing handlers in one chain. Fraud, KYC, and account handlers are gates. The approval handler is a router. The chain validates first, then routes. This is common in payment and compliance systems where every transaction must pass multiple independent checks before being directed to the appropriate authority.

The onboarding flow is a pure validation chain. Every handler is a gate. The final handler is the action that runs only if all gates pass. This is common in form processing, API request validation, and any multi-step verification flow.

Both use the same pattern and are configured the same way. The difference is just in what the handlers do when they let the request through.

When to Use the Chain of Responsibility Pattern

Use it when you have a request that must pass through multiple independent checks or processing steps.

It's also a good fit when the number of checks or their order might change over time. Adding a new step or reordering existing steps should not require modifying existing handler code.

It works well when each check or processing step has genuinely independent logic. If the steps are deeply interdependent and need to share a lot of state, a single class might be cleaner.

It does well when you want each step to be independently testable. With the chain pattern, testing FraudHandler means creating one handler, calling handle with a transaction, and checking the output. No other handler is involved.

And it's great when different configurations of the chain might be needed in different contexts. A junior officer's system might have a shorter chain than an executive's system. The same handlers, configured differently.

When Not to Use It

Avoid the pattern when you only have one or two checks. The overhead of defining an abstract class and multiple concrete classes is not worth it for simple validation.

It's also not the best when the order of processing steps is fixed and will never change. If the chain will always be the same, a simpler sequential function call might be clearer.

Don't use it when handlers need to communicate results back to each other. The pattern works best when each handler makes an independent decision. If Handler B needs to know what Handler A found, consider a different approach.

And it's not a good choice when you need guaranteed execution of all handlers regardless of earlier results. The Chain of Responsibility stops when a handler handles the request. If you need all steps to always run, a middleware pipeline or decorator pattern might suit you better.

Conclusion

The Chain of Responsibility pattern solves the problem that every growing system eventually faces. Business rules accumulate and validation logic expands. A method that started as ten lines becomes a hundred. The conditions interact in ways nobody fully understands anymore. Nobody wants to touch it.

The pattern gives you a way out. Each business rule gets its own handler. Each handler owns one responsibility and makes one decision: stop here, or pass it forward. The chain is built once in the configuration layer. The handlers never need to know about each other.

In the transaction approval flow, adding a new compliance rule means one new handler class. In the onboarding flow, adding a new verification step means one new handler class. In both cases, nothing else changes.

That's the promise of the pattern. Complexity that grows by addition, not by modification. Business rules that are isolated, testable, and replaceable. A system that can absorb new requirements without accumulating more debt every time.

Applying this behavioral pattern helps to bring some level of organization and scalability to your codes and makes it easy to manage based on further business rules to come in the nearest future.

Happy Coding!!

You have a set of objects: different types, shapes, and data. And at some point, someone asks you to perform an operation on all of them, like exporting them them to PDF, sending them a notification, generating a report, or calculating their fees.

Your first instinct might be to write a function that checks the type and branches accordingly, like an if-else block or switch statement. Something that says: if this is a NewUser, do this. If this is a JointAccountUser, do that. It works, you ship it, and everyone is happy.

Then another operation comes in. And another. Every single time, you go back to the same place and add another branch. The function grows. The class grows. The test surface grows. What started as a clean model is now a god object that knows how to do everything for everyone.

The Visitor Design Pattern exists to break this cycle completely.

Table of Contents

• What is the Visitor Design Pattern?

• The Problem the Visitor Pattern Solves

• Core Components

• Real World Example One: Document Export

• Real World Example Two: Notification System

• Real World Example Three: Fee Calculation

• The Power of Combining All Three Operations

• When to Use the Visitor Pattern

• When Not to Use It

• Conclusion

What is the Visitor Design Pattern?

The Visitor pattern is a behavioral design pattern that lets you define a new operation on a family of objects without changing the objects themselves.

The key word there is behavioral. Behavioral patterns are about how objects communicate and distribute responsibility. Where creational patterns deal with how objects are created and structural patterns deal with how they are composed, behavioral patterns deal with how they interact and who is responsible for what.

The Visitor pattern specifically deals with the question of who should own an operation when that operation needs to work differently across multiple object types.

The classic answer is: put the operation on each object. Give each class a method that handles the operation for its own type. But this breaks down the moment you have multiple operations, because now every new operation means touching every class. You're spreading one concern across your entire object hierarchy.

The Visitor pattern flips this. Instead of spreading the operation across the objects, you collect it into one place called a Visitor. The objects simply accept the visitor and let it do its work. Adding a new operation means creating a new Visitor. The existing objects don't change at all.

This is the Open/Closed Principle working exactly as intended: open for extension, closed for modification.

The Problem the Visitor Pattern Solves

Let me show you exactly what this looks like without the Visitor pattern.

Say you have a fintech platform with four types of users: existing customers, new customers, minor account holders, and joint account holders. Your product manager comes in and asks you to add document export. Every user type should be exportable to PDF, Excel, and CSV.

Without Visitor, the natural approach looks something like this:

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  String exportToPdf() {
    return '$firstName\n$lastName\n$lastPaymentDate\n$accountBalance';
  }

  String exportToExcel() {
    return '$firstName,$lastName,$lastPaymentDate,$accountBalance';
  }

  String exportToCsv() {
    return '"$firstName","$lastName","$lastPaymentDate","$accountBalance"';
  }
}

And you repeat this for NewUser, MinorAccountUser, and JointAccountUser. Twelve methods spread across four classes just for document export.

Now the product manager comes back. They want notifications: email, SMS, and Push. Back you go to all four classes, adding three more methods each. Twelve more methods spread across the same four classes.

Then they want fee calculation. Then they want KYC status checks. Every new operation multiplies across every user type. The classes grow, the reasons to change multiply, and testing becomes painful.

This is the exact problem the Visitor pattern was built to solve.

Core Components

The Visitor pattern has four core components. Understanding each one before looking at code makes the implementation much easier to follow.

The Visitor Interface

This is the contract that every visitor must implement. It declares one method per object type it needs to visit. A visitor that handles four user types declares four visit methods, one for each type.

The Concrete Visitors

These are the real implementations of the Visitor interface. Each one represents a single operation and knows how to handle every object type. A PdfHandler is a concrete visitor. An ExcelHandler is a concrete visitor. A SmsNotificationHandler is a concrete visitor. Each one has one job and knows how to do that job for every user type.

The Consumer Interface (also called Element or Acceptor)

This is the contract that every object in the hierarchy must implement. It declares a single accept method that takes a Visitor and calls the right visit method on it. This is the double dispatch mechanism that makes the pattern work.

The Concrete Consumers

These are the real objects in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each one implements accept by calling the specific visit method that corresponds to its own type.

Think of it this way. The Visitor interface is implemented by every operation you want to perform: PdfHandler, ExcelHandler, and CsvHandler. Each of these knows how to handle all four user types.

The Consumer interface is implemented by every object in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each of these knows how to receive a visitor and route it to the correct method.

When you call existingCustomer.accept(pdfHandler), ExistingCustomers calls pdfHandler.visitExistingCustomer(this) and passes itself as the argument. The right method fires automatically. There's no type checking, if-else, or switch. The object tells the visitor who it is, and the visitor knows exactly what to do with that information.

Real World Example One: Document Export

This is a real scenario from a fintech platform. There are four user types with different data structures, all needing to export their information to three document formats: PDF, Excel, and CSV.

Step 1: Define the User Models

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  const ExistingUser({
    required this.id,
    required this.firstName,
    required this.lastName,
    required this.lastPaymentDate,
    required this.accountBalance,
  });
}

class NewUser {
  final String firstName;
  final String lastName;

  const NewUser({
    required this.firstName,
    required this.lastName,
  });
}

class MinorAccountUser {
  final int age;
  final int guardianId;
  final String firstName;
  final String lastName;
  final String guardianName;

  const MinorAccountUser({
    required this.age,
    required this.guardianId,
    required this.firstName,
    required this.lastName,
    required this.guardianName,
  });
}

class JointAccountUser {
  final int jointAccountId;
  final List<String> accountHoldersInfo;
  final num accountBalance;

  const JointAccountUser({
    required this.jointAccountId,
    required this.accountHoldersInfo,
    required this.accountBalance,
  });
}

We have four models. Each one owns its own data and nothing else. There's no export logic or notification logic. And no business operations of any kind. Just clean data structures.

This is exactly how it should be. The model's job is to hold data. The visitor's job is to operate on it.

Step 2: Define the Visitor and Consumer Interfaces

abstract class UserVisitor<T> {
  T visitExistingCustomer(ExistingUser user);
  T visitNewCustomer(NewUser user);
  T visitMinorCustomer(MinorAccountUser user);
  T visitJointCustomer(JointAccountUser user);
}

abstract class UserConsumer {
  T accept<T>(UserVisitor<T> visitor);
}

UserVisitor<T> is generic. The type parameter T represents what the visitor returns. A document export visitor returns a String. A fee calculation visitor might return a double. A validation visitor might return a bool. The same pattern works for any return type.

UserConsumer declares the accept method. Every object in the hierarchy must implement this. The accept method is what makes the double dispatch work. The object receives the visitor and immediately calls the right visit method on it, passing itself as the argument.

Step 3: Implement the Concrete Consumers

class ExistingCustomers implements UserConsumer {
  final ExistingUser user;
  ExistingCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitExistingCustomer(user);
  }
}

class NewCustomers implements UserConsumer {
  final NewUser user;
  NewCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitNewCustomer(user);
  }
}

class MinorCustomer implements UserConsumer {
  final MinorAccountUser user;
  MinorCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitMinorCustomer(user);
  }
}

class JointCustomer implements UserConsumer {
  final JointAccountUser user;
  JointCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitJointCustomer(user);
  }
}

Each consumer wraps one user model and implements accept by forwarding to the correct visit method. This is the entire job of a concrete consumer. It knows who it is, and it tells the visitor by calling the right method.

Notice that none of these classes know anything about PDF, Excel, CSV, email, SMS, or any operation. They're completely decoupled from every operation that will ever be performed on them.

Step 4: Implement the Concrete Visitors

class PdfHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nBalance: ${user.accountBalance}'
        '\nLast Payment: ${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName} ${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nAge: ${user.age}'
        '\nGuardian: ${user.guardianName} (ID: ${user.guardianId})';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join(', ');
    return 'Joint Account ID: ${user.jointAccountId}'
        '\nHolders: $holders'
        '\nBalance: ${user.accountBalance}';
  }
}

class ExcelHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.accountBalance}\t${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName}\t${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.age}\t${user.guardianName}\t${user.guardianId}';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join('\t');
    return '${user.jointAccountId}\t$holders\t${user.accountBalance}';
  }
}

class CsvHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.accountBalance}","${user.lastPaymentDate}"';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '"${user.firstName}","${user.lastName}"';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.age}","${user.guardianName}","${user.guardianId}"';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.map((h) => '"$h"').join(',');
    return '"${user.jointAccountId}",$holders,"${user.accountBalance}"';
  }
}

Each handler implements the visitor interface and knows exactly how to format each user type for its specific document format. PdfHandler uses newlines and labels. ExcelHandler uses tabs. CsvHandler wraps values in quotes and separates with commas.

The formatting logic for each document type lives in exactly one class. If the PDF format changes, you touch only PdfHandler. If the CSV format changes, you touch only CsvHandler. The user models never change.

Step 5: Use It

void existingUserLogic() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final pdf = customer.accept(PdfHandler());
  final excel = customer.accept(ExcelHandler());
  final csv = customer.accept(CsvHandler());

  print('PDF:\n$pdf\n');
  print('Excel:\n$excel\n');
  print('CSV:\n$csv\n');
}

void newUserLogic() {
  final customer = NewCustomers(
    user: NewUser(
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void minorUserLogic() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void jointUserLogic() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

The same customer object accepts any visitor with the same call. The type dispatch happens automatically through the accept method. There's no type checking anywhere in the calling code, and no if-else or switch. Just customer.accept(handler) and the right method fires.

Now think about what happens when you need to add an XML export. You create one new class, XmlHandler, implement the four visit methods, and that's it. You don't touch ExistingUser, NewUser, MinorAccountUser, JointAccountUser, or any of the existing handlers. The system is genuinely open for extension and closed for modification.

Real World Example Two: Notification System

Here we have the same four user types and the same pattern. But it's a different operation entirely.

Your platform needs to notify users about account events. But not every user type should be notified the same way.

Existing users get email and push notifications. New users only get email because they haven't fully set up their profile yet. Minor account users get SMS to their guardian's number. Joint account users get notified on all channels because multiple people share the account.

Without the Visitor pattern, this logic would spread across all four user models or collapse into one enormous function full of type checks. With Visitor, it lives in three focused classes.

The Notification Visitor Interface

abstract class NotificationVisitor {
  void visitExistingCustomer(ExistingUser user);
  void visitNewCustomer(NewUser user);
  void visitMinorCustomer(MinorAccountUser user);
  void visitJointCustomer(JointAccountUser user);
}

This visitor returns void because notifications are side effects. They send messages, they don't return values.

The Concrete Notification Visitors

class EmailNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending email to existing customer: ${user.firstName}');
    // email service call with full account details
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Sending welcome email to new customer: ${user.firstName}');
    // welcome email with onboarding steps
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending email to guardian: ${user.guardianName}');
    // email goes to guardian, not the minor
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending email to joint holder: $holder');
      // all account holders get notified
    }
  }
}

class SmsNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending SMS to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    // new users are not SMS-verified yet, skip
    print('New customer ${user.firstName} not SMS-eligible yet');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending SMS to guardian ${user.guardianName} for minor ${user.firstName}');
    // SMS goes to guardian's registered number
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending SMS to joint holder: $holder');
    }
  }
}

class PushNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Push notification to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Push notification to new customer: ${user.firstName}');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    // minors do not have the app installed yet, guardian gets push
    print('Push notification to guardian: ${user.guardianName}');
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Push notification to joint holder: $holder');
    }
  }
}

Each handler knows the specific rules for each user type. SmsNotificationHandler knows that new users aren't SMS-verified yet. PushNotificationHandler knows that minor account notifications go to the guardian. EmailNotificationHandler knows that joint account holders all need to be notified individually.

This business logic lives in exactly one place per notification channel. When the rules change (and they always change), you update one class.

Using the Notification Visitors

void notifyExistingUser() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyMinorUser() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  // all three channels fire, each with minor-specific rules
  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyJointUser() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

The calling code is identical regardless of the user type or the notification channel. The dispatch is automatic. The rules live inside the visitors.

When WhatsApp notifications become a requirement (and they will), you create one WhatsAppNotificationHandler class with four visit methods. Nothing else changes.

Real World Example Three: Fee Calculation

Again, we have the same four user types and the same pattern. And once again, we have a completely different operation.

Your platform needs to calculate monthly maintenance fees. But each user type has different rules.

Existing customers pay a flat monthly fee based on their account balance. New customers are fee-exempt for their first three months. Minor account holders pay a reduced fee because their accounts have restricted features. Joint account holders have their fee split equally across all account holders.

Without Visitor, this logic ends up as a giant method somewhere with four branches, or worse, it leaks into the user models themselves. With Visitor, it lives in one focused class.

The Fee Visitor Interface

abstract class FeeVisitor {
  double visitExistingCustomer(ExistingUser user);
  double visitNewCustomer(NewUser user);
  double visitMinorCustomer(MinorAccountUser user);
  double visitJointCustomer(JointAccountUser user);
}

This visitor returns a double because fee calculation produces a numeric value.

The Concrete Fee Visitor

class MonthlyFeeCalculator implements FeeVisitor {
  @override
  double visitExistingCustomer(ExistingUser user) {
    // 0.5% of account balance, minimum 500, maximum 5000
    final fee = user.accountBalance * 0.005;
    return fee.clamp(500, 5000).toDouble();
  }

  @override
  double visitNewCustomer(NewUser user) {
    // new customers are fee-exempt for the first 3 months
    return 0.0;
  }

  @override
  double visitMinorCustomer(MinorAccountUser user) {
    // flat reduced fee for minor accounts
    return 150.0;
  }

  @override
  double visitJointCustomer(JointAccountUser user) {
    // standard fee split equally across all holders
    const standardFee = 2000.0;
    return standardFee / user.accountHoldersInfo.length;
  }
}

Every fee rule for every user type lives in this one class. When the fee structure changes for existing customers, you touch one method in one class. When minor account fees are updated, same thing. None of the user models change, and no other visitor changes.

Using the Fee Visitor

void calculateFees() {
  final existingCustomer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final newCustomer = NewCustomers(
    user: NewUser(
      firstName: 'Aderonke',
      lastName: 'Fatunmole',
    ),
  );

  final minorCustomer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Inioluwa',
      lastName: 'Fatunmole',
      guardianName: 'Oluwaseyi',
    ),
  );

  final jointCustomer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  final calculator = MonthlyFeeCalculator();

  final existingFee = existingCustomer.accept(calculator);
  final newFee = newCustomer.accept(calculator);
  final minorFee = minorCustomer.accept(calculator);
  final jointFee = jointCustomer.accept(calculator);

  print('Existing customer fee: NGN $existingFee');
  print('New customer fee: NGN $newFee');
  print('Minor account fee: NGN $minorFee');
  print('Joint account fee per holder: NGN $jointFee');
}

The output:

Existing customer fee: NGN 5000.0
New customer fee: NGN 0.0
Minor account fee: NGN 150.0
Joint account fee per holder: NGN 500.0

When a PremiumFeeCalculator is needed for a new tier of customers, you create one new class that implements FeeVisitor. The user models stay exactly as they are. The MonthlyFeeCalculator stays exactly as it is. The accept methods on all four consumers stay exactly as they are.

The Power of Combining All Three Operations

Here's what makes the Visitor pattern truly shine in a system like this. You have the same four user types, and you can run any combination of visitors on any of them in the same call chain.

void processUser(UserConsumer customer) {
  final pdf = customer.accept(PdfHandler());
  final csv = customer.accept(CsvHandler());

  customer.accept(EmailNotificationHandler());
  customer.accept(PushNotificationHandler());

  final fee = customer.accept(MonthlyFeeCalculator());

  print('Fee: NGN $fee');
  print('Documents generated and notifications sent');
}

One function, any user type, any combination of operations. The consumer doesn't care which visitors it receives. The visitors don't care which consumers call them. They speak to each other through the interface, and the interface guarantees everything works correctly.

We have three completely different operations (document export, notifications, and fee calculation) all applied to the same object with the same call pattern. None of these operations know about each other. None of them touch the user models. Each one lives in its own focused class with its own single reason to change.

When to Use the Visitor Pattern

Use Visitor when you have a stable set of object types and a growing set of operations on them.

The pattern shines when the object hierarchy is unlikely to change frequently. It's optimized for adding new operations, not new types. Adding a new user type means updating every existing visitor. If your object types change constantly, Visitor creates more work than it saves.

It's also very effective when you need to perform multiple unrelated operations on a family of objects without polluting their classes with that logic. Document export, notification handling, fee calculation, and KYC validation are all unrelated operations. Each belongs in its own visitor, not scattered across the user models.

Visitor also works well when you want clean separation between data and behavior. The models hold data and the visitors define behavior. This makes both easier to understand, easier to test, and easier to maintain independently.

When Not to Use It

Avoid Visitor when the object hierarchy changes frequently. Every time you add a new type, you must update every existing visitor. In a system where new user types appear regularly, this becomes painful quickly.

It's also not helpful when you only have one or two operations. For simple cases, the overhead of creating visitor interfaces, consumer interfaces, and multiple classes is not worth the benefit.

And avoid it when the operations are tightly coupled to the object's internal state in ways that make sense to keep together. Some behavior naturally belongs on the object itself.

Conclusion

The Visitor Design Pattern solves a problem that most developers only recognize after they've already made a mess of it. You have a family of objects with different types and different data. Operations come in one after another. Without a deliberate structure, those operations spread everywhere: into the models, utility classes, and massive switch statements that nobody wants to touch.

Visitor collects each operation into one focused class. The models stay clean and the operations stay isolated. Adding a new operation means creating one new class. The existing code doesn't change.

In the fintech examples above, we have three entirely different concerns: document export, notifications, and fee calculation. All are handled by handled by focused classes, none of which know anything about each other. The user models don't know about PDF or email or fees. The PdfHandler doesn't know about SMS. The MonthlyFeeCalculator doesn't know about push notifications. Each class has exactly one reason to exist and exactly one reason to change.

That s what a well-applied Visitor pattern looks like in practice. Clean, focused, and genuinely extensible.

Happy coding!

But do you know what actually happens when your application sends a request? What travels through the wire? Why does HTTP/2 make things faster? Why do WebSockets exist when HTTP already works? What makes Protocol Buffers different from JSON at a fundamental level?

And when you're designing a system, how do you decide which communication approach to use?

These are the questions this handbook answers.

This isn't a beginner's guide to APIs. This is a deep dive into how clients and servers actually communicate: the protocols, the trade-offs, the history of why each approach was built, and the engineering thinking behind choosing one over another.

By the end, you won't just know what these technologies are. You'll understand why they exist, how they work at a level that makes you a better engineer, and how to make deliberate architectural decisions about communication in your systems.

Table of Contents

• The Foundation: How Two Machines Talk to Each Other

• HTTP/1.1: The Protocol That Built the Web

• The Problems HTTP/1.1 Could Not Solve

• HTTP/2: Rebuilding the Foundation

• HTTP/3 and QUIC: The Next Evolution

• Data Formats: How Information Is Encoded

• REST: The Architecture That Took Over the World

• The Limits of REST

• GraphQL: Letting the Client Decide

• WebSockets: When HTTP Is Not Enough

• Server-Sent Events: The Simpler Real-Time Option

• Protocol Buffers: A New Language for Data

• gRPC: Remote Procedure Calls at Scale

• The Complete Comparison

• How to Choose: The Engineering Decision Framework

• Conclusion

The Foundation: How Two Machines Talk to Each Other

Before any protocol, data format, or architectural style enters the picture, two machines need to establish a connection. Understanding this foundation makes everything else click.

IP Addresses and Ports

Every device on a network has an IP address: a unique identifier that works like a postal address. When your application sends a request to api.example.com, the first thing that happens is a DNS lookup, which translates that human-readable name into an IP address like 93.184.216.34. That IP address is where the packet is going.

But an IP address alone isn't enough. A single server might be running dozens of different services simultaneously: a web server, a database, an email server, an SSH daemon.

Ports tell the operating system which service should handle the incoming connection. Port 80 is the conventional port for HTTP. Port 443 is for HTTPS. Port 5432 is for PostgreSQL. Port 22 is for SSH. When you call api.example.com/users, you are actually calling api.example.com:443/users. The browser fills in the port automatically.

TCP: The Reliable Foundation

Most web communication runs over TCP (Transmission Control Protocol). TCP is a connection-oriented protocol, which means before any data is exchanged, both parties go through a handshake to establish a connection.

The TCP handshake works in three steps, which is why it's called the three-way handshake:

Client                    Server
  |                          |
  |-------- SYN ----------->|   "I want to connect"
  |                          |
  |<------- SYN-ACK --------|   "Okay, I acknowledge. Ready?"
  |                          |
  |-------- ACK ----------->|   "Great, let's go"
  |                          |
  [Connection established]

SYN stands for synchronize. ACK stands for acknowledge. After these three packets, the connection exists and data can flow.

TCP guarantees three things that make it the foundation of reliable communication:

1. Delivery: if a packet is lost in transit, TCP detects this and retransmits it automatically. The application layer never has to worry about lost packets.

2. Order: packets arrive in the same order they were sent. If packets arrive out of order (which happens frequently on real networks), TCP reorders them before delivering them to the application.

3. Error detection: every TCP packet includes a checksum. If the data is corrupted in transit, TCP detects and discards the corrupted packet, then requests a retransmission.

This reliability comes at a cost: the overhead of the handshake, the acknowledgment packets, and the retransmission logic.

For many use cases, this cost is worth it. For some (live video streaming, online gaming, DNS lookups), UDP (User Datagram Protocol) is preferred because it sends packets without any of this overhead, accepting some loss in exchange for speed. HTTP/3, which we'll cover later, is built on a protocol that brings reliability to UDP.

TLS: Encrypting the Connection

On the modern web, most connections use HTTPS rather than plain HTTP. The S stands for Secure, and the security is provided by TLS (Transport Layer Security), the successor to SSL.

TLS adds an additional handshake on top of the TCP connection. During the TLS handshake:

1. The client and the server agree on which version of TLS to use and which encryption algorithms to support

2. The server presents its digital certificate (issued by a trusted Certificate Authority)

3. The client verifies the certificate is valid and belongs to the server it intended to reach

4. They exchange encryption keys using asymmetric cryptography

5. From that point forward, all communication is encrypted with symmetric encryption

The TLS handshake adds latency. In TLS 1.2, it takes two round trips before any application data can flow. TLS 1.3, released in 2018, reduced this to one round trip, and even supports zero round-trip resumption for returning connections.

Understanding TCP and TLS matters because every protocol we discuss runs on top of them (until HTTP/3, which changes the underlying transport). When people talk about the "overhead" of HTTPS or the "cost" of establishing a connection, they're talking about the time and packets spent on these handshakes before a single byte of your actual request travels.

HTTP/1.1: The Protocol That Built the Web

HTTP (HyperText Transfer Protocol) was invented by Tim Berners-Lee in 1991 to transfer HTML documents between computers. HTTP/1.0 was simple: one request per connection, then the connection closes.

HTTP/1.1, standardized in 1997, brought significant improvements and became the dominant version of HTTP for nearly two decades. It introduced persistent connections (keep connections open across multiple requests), chunked transfer encoding, and more sophisticated caching mechanisms.

How an HTTP/1.1 Request Works

An HTTP request is a text message with a specific structure:

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Accept: application/json
Content-Length: 45
User-Agent: MyApp/2.0

{"name": "John Smith", "email": "john@example.com"}

The first line is the request line: the HTTP method (POST), the path (/api/users), and the protocol version.

Below that are the headers: key-value pairs that provide metadata about the request. The host, the content type, the authorization token, what format the client accepts, and how large the body is.

After a blank line comes the body: the actual data being sent.

The server processes this and responds:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/usr_789
Date: Mon, 21 Jul 2026 09:15:00 GMT
Content-Length: 89

{"id": "usr_789", "name": "John Smith", "email": "john@example.com", "created_at": "..."}

The response has a status line (the protocol version, the status code, and a reason phrase), headers, and a body.

HTTP Methods and Their Semantics

HTTP/1.1 defines several methods, each with specific semantics:

• GET retrieves a resource. A GET request should have no side effects. It shouldn't create or modify anything. It's safe and idempotent, meaning calling it multiple times has the same effect as calling it once.

• POST submits data to create a new resource or trigger an action. It's neither safe nor idempotent: calling POST twice typically creates two resources.

• PUT replaces a resource entirely with the provided data. It's idempotent: calling PUT twice with the same data has the same effect as calling it once.

• PATCH partially updates a resource. Only the fields provided are changed.

• DELETE removes a resource. It's idempotent: deleting something that doesn't exist is still considered successful.

• HEAD is identical to GET but the server only returns headers, not the body. It's used to check if a resource exists or has been modified without downloading the full content.

• OPTIONS asks the server what methods are allowed for a resource. It's used in CORS preflight requests.

Status Codes

HTTP status codes are three-digit numbers grouped into five categories:

1xx Informational — the server has received the request and is continuing to process it. These are rarely seen in practice outside of specific use cases like HTTP upgrade (used to establish WebSocket connections).

2xx Success — the request was received, understood, and accepted.

• 200 OK: standard success response

• 201 Created: a new resource was created

• 204 No Content: success but nothing to return (common for DELETE)

3xx Redirection — further action is required to complete the request.

• 301 Moved Permanently: the resource has a new URL forever

• 302 Found: temporary redirect

• 304 Not Modified: the cached version is still valid (used with ETags)

4xx Client Error — the request contains bad syntax or can't be fulfilled.

• 400 Bad Request: the request is malformed

• 401 Unauthorized: authentication is required (despite the name, it means unauthenticated)

• 403 Forbidden: authenticated but not authorized to access this resource

• 404 Not Found: the resource doesn't exist

• 422 Unprocessable Entity: the request is syntactically valid but semantically wrong (common for validation errors)

• 429 Too Many Requests: rate limit exceeded

5xx Server Error — the server failed to fulfill a valid request.

• 500 Internal Server Error: something went wrong on the server

• 502 Bad Gateway: the server received an invalid response from an upstream server

• 503 Service Unavailable: the server is temporarily unavailable

• 504 Gateway Timeout: the upstream server did not respond in time

Caching in HTTP/1.1

One of HTTP/1.1's most powerful features is its built-in caching model. Responses can include headers that tell clients and intermediate caches how long to store a response and when to revalidate it.

• Cache-Control: max-age=3600 tells the client to cache this response for one hour.

• Cache-Control: no-cache tells the client to always revalidate with the server before using a cached response.

• Cache-Control: no-store tells the client never to cache this response.

ETag is a fingerprint of the response content. When the client makes a subsequent request, it sends the ETag back in an If-None-Match header. If the content hasn't changed, the server responds with 304 Not Modified and no body, saving bandwidth.

Last-Modified works similarly: the client sends If-Modified-Since and the server confirms whether the content has changed.

Caching is one of the key reasons REST over HTTP became dominant. GET requests to well-designed REST APIs can be cached at the CDN level, meaning the same response is served to thousands of users without the request ever reaching your origin server.

The Problems HTTP/1.1 Could Not Solve

HTTP/1.1 served the web well for two decades. But as the web grew more complex, applications more dynamic, and user expectations higher, its architectural limitations became significant performance bottlenecks.

Head-of-Line Blocking

HTTP/1.1 processes requests sequentially on a single connection. The server must finish responding to one request before the next one on the same connection begins.

Connection 1:
Request 1 (slow database query) -----> [3 seconds] -----> Response 1
Request 2 (fast in-memory read) -----> [waits 3 seconds] -----> Response 2
Request 3 (static file) -----------> [waits 3+ seconds] -----> Response 3

Request 2 and Request 3 are fast operations. But they're stuck waiting for Request 1 to complete. This is head-of-line blocking: the head of the queue blocks everything behind it.

Browsers worked around this by opening multiple parallel TCP connections to the same server, typically six. But each connection requires its own TCP handshake and TLS negotiation, consuming resources on both the client and server.

Verbose Headers on Every Request

Every HTTP/1.1 request sends its complete headers as plain text. Consider a mobile application making fifty requests during a session. On every single request, the following headers are sent in full:

Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMTIzIn0...
Content-Type: application/json
Accept: application/json
Accept-Language: en-US,en;q=0.9
Accept-Encoding: gzip, deflate, br
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...

The Authorization header alone, carrying a JWT, can be 400 to 600 bytes. Multiplied by fifty requests, that is 20 to 30 kilobytes of data carrying nothing but headers that haven't changed between requests.

On a 4G mobile connection with limited bandwidth, this is waste. On a 2G connection in a network-constrained environment, it's a significant performance penalty.

No Server Push

HTTP/1.1 is strictly request-response. The server can't send data until the client asks for it. This fundamental limitation means the server can never proactively inform the client of changes.

For applications requiring real-time updates, short polling became a common workaround: the client sends a request every few seconds asking "has anything changed?" This is inefficient because most polling requests receive a "no, nothing has changed" response, consuming bandwidth and server resources for no purpose.

Long polling was a refinement: the client sends a request and the server holds it open until something changes or a timeout occurs. This reduces unnecessary responses but keeps connections open indefinitely, consuming server resources.

Both are workarounds for a fundamental limitation of HTTP/1.1's request-response model.

Inefficient Use of Connections

Opening a new TCP connection requires the three-way handshake plus the TLS handshake: a process that can take 200 to 500 milliseconds on a mobile connection.

HTTP/1.1 introduced keep-alive connections to reuse connections across multiple requests, but head-of-line blocking made this only partially effective. Browsers opened multiple connections to compensate, but six parallel connections per domain is both a client limitation and a server resource concern at scale.

HTTP/2: Rebuilding the Foundation

Google published a protocol called SPDY (pronounced "speedy") in 2009, designed to address HTTP/1.1's performance limitations. SPDY demonstrated that significant improvements were possible without changing the fundamental HTTP semantics. HTTP/2, standardized by the IETF in 2015, was heavily based on SPDY and became the successor to HTTP/1.1.

HTTP/2 doesn't change what you send. From the application developer's perspective, requests still have methods, paths, headers, and bodies. Responses still have status codes, headers, and bodies. What HTTP/2 changes is how all of this is transmitted.

Binary Framing: The Core Change

HTTP/1.1 is a text protocol. Headers, status lines, and method names are all ASCII text. Machines must parse this text character by character to interpret it.

HTTP/2 is a binary protocol. Every piece of information is encoded as binary frames rather than text. Binary is more compact and significantly faster for machines to parse. Instead of tokenizing a string looking for colons and newlines to separate header names from values, a binary parser reads fixed-length fields directly from memory.

The binary framing layer is the foundation everything else in HTTP/2 is built upon.

Multiplexing: Many Streams, One Connection

HTTP/2 introduces the concept of streams. A stream is an independent, bidirectional sequence of frames within a single TCP connection. Multiple streams can exist simultaneously on the same connection.

Single TCP connection to api.example.com

Stream 1: GET /user/profile ---------> Response arrives
Stream 2: GET /user/balance ---------> Response arrives
Stream 3: POST /transactions --------> Response arrives
Stream 4: GET /notifications --------> Response arrives

All four streams active simultaneously
No stream waits for any other stream

This is multiplexing: many independent requests and responses interleaved on the same connection. Head-of-line blocking at the HTTP level is eliminated. A slow request on Stream 1 doesn't prevent Stream 2, 3, or 4 from receiving their responses.

One connection replaces six parallel connections. The TCP handshake and TLS negotiation happen once. Connection overhead drops dramatically.

Header Compression with HPACK

HTTP/2 compresses headers using an algorithm called HPACK specifically designed for HTTP headers.

HPACK works in two ways. First, it maintains a table of previously seen headers. Instead of retransmitting a header that was sent on the previous request, it sends a reference to the table entry: a single integer instead of hundreds of bytes of text.

Second, HPACK uses Huffman encoding for new header values, reducing the size of strings that can't be referenced from the table.

The result: a mobile application sending the same Authorization header on every request transmits it in full on the first request, then sends a one-byte or two-byte reference on every subsequent request. What was 500 bytes of overhead becomes 2 bytes.

Across fifty requests in a session, this eliminates thousands of bytes of redundant header transmission.

Stream Prioritization

HTTP/2 allows clients to assign priority to streams. A browser loading a web page can signal that the CSS file (needed to render anything) is higher priority than the analytics script (not needed for initial render). The server can use these priorities to decide the order in which it sends frames when multiple streams are active.

In practice, stream prioritization has been inconsistently implemented and is being redesigned in HTTP/3.

Server Push

HTTP/2 allows the server to proactively send resources to the client without waiting for a request. When a browser requests an HTML file, the server can immediately push the CSS and JavaScript files it knows the browser will need next, before the browser has even parsed the HTML to discover it needs them.

Client: GET /index.html
Server: Here is index.html
Server: (push) Here is styles.css — you will need this
Server: (push) Here is app.js — you will need this too

In practice, server push has had mixed adoption due to implementation complexity and the risk of pushing resources the client already has cached. HTTP/3 is reconsidering how push should work.

HTTP/2 and gRPC

HTTP/2's multiplexing and persistent connections make it the ideal transport for gRPC. A single HTTP/2 connection can carry many concurrent gRPC calls, including long-running streaming calls that push data continuously. This is why gRPC requires HTTP/2: the features that make gRPC efficient are provided by the transport layer.

HTTP/3 and QUIC: The Next Evolution

Even with HTTP/2's improvements, one fundamental problem remained: TCP head-of-line blocking.

HTTP/2 eliminated head-of-line blocking at the HTTP level. Multiple HTTP/2 streams can proceed independently. But all of those streams share a single TCP connection. TCP guarantees ordered delivery of all bytes in a connection. If a single TCP packet is lost, the entire connection stalls while TCP retransmits that packet, even for streams that have nothing to do with the lost packet.

HTTP/2 over TCP — packet loss scenario:

Stream 1: data in flight...
Stream 2: data in flight...
Stream 3: packet LOST — TCP retransmission required

Stream 1: STALLED (waiting for TCP retransmission)
Stream 2: STALLED (waiting for TCP retransmission)
Stream 3: retransmission in progress...

Both streams 1 and 2 are blocked by a packet loss that affected only stream 3. This is TCP head-of-line blocking, and HTTP/2 can't eliminate it because it operates above the TCP layer.

QUIC: A New Transport Protocol

Google developed QUIC (Quick UDP Internet Connections) to solve this problem. QUIC is a new transport protocol built on UDP instead of TCP, designed to provide some very helpful new features:

1. Multiplexing without head-of-line blocking: QUIC understands streams natively. A packet loss in one QUIC stream only stalls that stream. Other streams on the same connection continue flowing freely.

2. Built-in encryption: Unlike TLS which runs on top of TCP, QUIC has TLS 1.3 built into the protocol itself. The transport and security layers are integrated, reducing the number of round trips required before data can flow.

3. Faster connection establishment: A new QUIC connection requires one round trip before data can flow. For returning connections where a session ticket exists, QUIC can send data in zero round trips (0-RTT).

4. Connection migration: A TCP connection is identified by the four-tuple of source IP, source port, destination IP, and destination port. If any of these change (say, a mobile device switches from WiFi to cellular), the TCP connection breaks and must be re-established. QUIC connections are identified by a connection ID that survives network changes, enabling seamless handoff.

HTTP/3

HTTP/3 is HTTP semantics over QUIC. The request and response model remains the same. Headers, status codes, and methods are all identical. The transport underneath is QUIC instead of TCP.

HTTP/3 is particularly impactful for:

1. Mobile networks where packet loss is more common and devices frequently switch between networks.

2. High-latency connections where the reduced handshake round trips save meaningful time.

3. Applications with many concurrent streams where TCP head-of-line blocking was a real bottleneck.

As of 2026, HTTP/3 is supported by major browsers, CDNs, and an increasing number of backend servers. Adoption continues to grow.

Data Formats: How Information Is Encoded

Independent of which protocol carries data, systems need to agree on how data is encoded. The most important formats for API communication are JSON and Protocol Buffers.

JSON: The Universal Language

JSON (JavaScript Object Notation) was derived from JavaScript syntax and formalized as a standalone data format. Its design philosophy is human readability and simplicity.

A JSON object is a collection of key-value pairs enclosed in curly braces. Keys are always strings. Values can be strings, numbers, booleans, null, arrays, or other objects.

{
  "id": "usr_001",
  "name": "John Smith",
  "age": 28,
  "is_verified": true,
  "scores": [98, 87, 92],
  "address": {
    "city": "Lagos",
    "country": "Nigeria"
  }
}

JSON became the dominant API data format for several reasons. It's human-readable: a developer can look at a JSON response in a browser's developer tools and immediately understand it. It maps naturally to data structures in virtually every programming language. It requires no special tooling or schema definition. And it's flexible: fields can be added or removed without necessarily breaking existing clients.

The Structural Cost of JSON

JSON's human-readable design comes with a structural cost that becomes significant at scale.

Every field name is a string that travels over the network on every single response. In the example above, the strings "is_verified", "address", "country" aren't data. They're labels for data. They consume bytes, they must be tokenized and parsed, and they're repeated on every response for every user.

JSON is a text format, which means it must be parsed from text into the application's native data structures. This parsing isn't free: it requires allocating memory for strings, walking the text byte by byte to find delimiters, and constructing objects from the parsed values.

For a fintech platform with an internal API that returns a 1000-field response and is called by dozens of internal services millions of times per day, the cumulative cost of JSON's verbosity and parsing overhead becomes measurable in bandwidth bills and server CPU time.

JSON also has no formal schema at the network level. There's nothing in the JSON format itself that prevents a backend from changing "account_balance" to "balance". The change compiles fine. The server deploys. Clients that depend on "account_balance" break silently at runtime.

XML: The Predecessor

Before JSON, XML (eXtensible Markup Language) was the dominant data format for web services (used in SOAP, the predecessor to REST). XML is more verbose than JSON, wrapping every value in opening and closing tags:

<user>
  <id>usr_001</id>
  <name>John Smith</name>
  <age>28</age>
  <is_verified>true</is_verified>
</user>

XML has advantages: it supports schemas (XSD), namespaces, and complex document structures. It's still used in enterprise systems, document formats (DOCX, SVG, RSS), and configuration files. But for API communication, JSON's simplicity won.

REST: The Architecture That Took Over the World

REST (Representational State Transfer) was defined by Roy Fielding in his doctoral dissertation in 2000. Fielding was one of the principal authors of the HTTP specification, and REST emerged from his analysis of what made HTTP architecturally successful.

REST isn't a protocol. It's an architectural style: a set of constraints that, when applied to a distributed system, produce desired properties including scalability, simplicity, and modifiability.

The Six REST Constraints

Fielding defined six constraints that define a RESTful architecture. Most APIs described as "REST" implement a subset of these, which is why the term "RESTful" covers a wide spectrum.

1. Client-Server: The client and server are separate concerns. The client manages the user interface. The server manages data storage and business logic. They evolve independently. This separation allows each to scale and change without affecting the other.

2. Stateless: Each request from the client to the server must contain all the information needed to understand and process the request. The server doesn't store any session state between requests. If a client needs to be authenticated, the authentication information (typically a token) travels with every request.

Statelessness is what makes REST APIs horizontally scalable. Any server instance can handle any request because no session state needs to be co-located with the request. Load balancers can route requests freely.

3. Cacheable: Responses must define themselves as cacheable or non-cacheable. If a response is cacheable, clients and intermediate layers (CDN, reverse proxies) can store and reuse the response without hitting the server.

Caching is one of the most powerful properties of REST. A well-designed REST API can serve millions of identical GET requests from CDN cache, with only a fraction ever reaching the origin server.

4. Uniform Interface: The interface between client and server is standardized. Resources are identified by URIs. Resources are manipulated through representations. Messages are self-descriptive. This uniformity is what makes REST APIs universally accessible: a developer in any language can call a REST API using standard HTTP tooling.

5. Layered System: The client doesn't need to know whether it's connected directly to the server or to an intermediary (load balancer, CDN, API gateway, caching proxy). Each layer only sees the layer it is interacting with. This enables transparent scaling and security.

6. Code on Demand (Optional): Servers can extend client functionality by sending executable code (JavaScript). This is the only optional constraint and is the basis for how browsers work, but rarely relevant to API design.

Resources and URIs

The central concept in REST is the resource. A resource is any piece of information that can be named, like a user, an order, a product, or a collection of transactions.

Resources are identified by URIs (Uniform Resource Identifiers). The URI identifies what the resource is, not what to do with it. The HTTP method expresses the operation.

GET    /users           — retrieve all users
GET    /users/123       — retrieve user 123
POST   /users           — create a new user
PUT    /users/123       — replace user 123 entirely
PATCH  /users/123       — partially update user 123
DELETE /users/123       — delete user 123

GET    /users/123/orders        — orders belonging to user 123
POST   /users/123/orders        — create an order for user 123
GET    /users/123/orders/456    — order 456 belonging to user 123

The URI structure forms a hierarchy that reflects the relationships between resources. This makes APIs predictable: a developer who understands the resource model can guess the correct URIs.

Why REST Won

REST became the dominant architectural style for web APIs for reasons that go beyond technical merit:

Universal accessibility: Any device, any language, any framework that can make an HTTP request can call a REST API. There's no special client library needed.

HTTP alignment: REST leverages HTTP's existing infrastructure. CDN caching works for free. Load balancers understand HTTP. Monitoring tools speak HTTP. The entire ecosystem is built around HTTP semantics.

Simplicity: A REST API can be designed, documented, and consumed with minimal tooling. A developer can test endpoints in a browser or with curl immediately.

Developer experience: JSON over HTTP is something every web developer already understands. The learning curve is essentially zero.

Ecosystem maturity: OpenAPI/Swagger provides standardized documentation. Postman provides testing. Every programming language has robust HTTP client libraries.

The Limits of REST

REST's success is real. But so are its limitations, and understanding them is essential to knowing when to reach for something else.

Overfetching: Getting More Than You Need

A REST endpoint returns a fixed shape of data. The /users/123 endpoint returns the full user object: name, email, phone, address, preferences, account status, and thirty other fields.

A mobile screen that displays only the user's name and avatar must receive all of those fields to use two of them. The rest is waste: wasted bandwidth, serialization on the server, and deserialization on the client.

On a constrained mobile connection, this overfetching isn't just inefficient. It's a measurable degradation of user experience.

Underfetching: Not Getting Enough at Once

The opposite problem is equally common. A screen needs data from multiple resources: the user's profile, their recent orders, their notification count, and their account balance.

A REST API typically models these as separate endpoints. Loading this screen requires four separate HTTP requests, each with its own round-trip latency.

GET /users/123         → profile data
GET /users/123/orders  → orders data
GET /notifications?user=123 → notification count
GET /accounts/123/balance   → balance data

Four sequential round trips. On a 200ms latency connection, that's 800ms of network time before the screen can render completely.

The N+1 Problem

A common variant of underfetching: you fetch a list of resources, then must fetch additional data for each item in the list.

GET /orders            → returns 20 orders (each with a user_id)
GET /users/1           → user for order 1
GET /users/2           → user for order 2
...
GET /users/20          → user for order 20

21 requests to load one screen. This pattern appears constantly in REST APIs and is addressed in various ways: including nested data in responses, adding query parameters to expand related resources, or creating purpose-built endpoints for specific screens.

All of these workarounds create tension: the API becomes less general as it's optimized for specific client needs.

No Native Real-Time Support

REST is request-response. The client initiates every interaction. The server can never proactively push data.

Real-time features like live notifications, collaborative editing, and streaming data require either polling (inefficient), long-polling (complex), or a separate real-time technology bolted alongside the REST API.

The Documentation Drift Problem

A REST API contract lives in documentation. Nothing in the HTTP protocol enforces that the documentation accurately reflects the API's actual behavior. As APIs evolve, documentation falls behind. Fields are renamed, types change, endpoints are deprecated. Clients built against outdated documentation break.

This isn't a theoretical problem. It's a daily reality in engineering teams where the backend and frontend evolve at different speeds.

GraphQL: Letting the Client Decide

GraphQL was developed at Facebook starting in 2012 and open-sourced in 2015. Facebook built it to solve a specific problem: their mobile app needed to fetch complex, interconnected social data from a REST API, and the resulting overfetching and multiple round trips were degrading performance on mobile devices.

GraphQL's core insight is simple and radical: instead of the server deciding what data to return, let the client specify exactly what it needs.

The Query Language

GraphQL is both a query language for APIs and a runtime for executing those queries. Rather than calling different endpoints for different data, all GraphQL requests go to a single endpoint (typically /graphql) and include a query that describes precisely what data is needed.

A GraphQL query for a user profile screen:

query UserProfile {
  user(id: "usr_123") {
    name
    avatarUrl
    recentOrders(limit: 3) {
      id
      total
      status
      createdAt
    }
    notificationCount
  }
}

The response contains exactly and only the fields requested. Nothing more. If the client needs only name and avatarUrl, it requests only those two fields. The response contains only two fields.

Mutations and Subscriptions

GraphQL has three operation types:

1. Queries fetch data. They're the GraphQL equivalent of GET requests.

2. Mutations modify data: creating, updating, or deleting resources. They're the GraphQL equivalent of POST, PUT, PATCH, and DELETE.

3. Subscriptions establish a persistent connection and push data in real-time when specified events occur. A subscription to orderStatusChanged receives a push every time any order's status changes. This is GraphQL's real-time capability, typically implemented over WebSockets.

The Schema

Every GraphQL API is defined by a schema written in the Schema Definition Language (SDL). The schema declares every type, query, mutation, and subscription the API supports.

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
  notificationCount: Int!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
  createdAt: String!
}

enum OrderStatus {
  PENDING
  PROCESSING
  SHIPPED
  DELIVERED
}

type Query {
  user(id: ID!): User
  orders(userId: ID!, limit: Int): [Order!]!
}

type Mutation {
  createOrder(userId: ID!, items: [OrderItemInput!]!): Order!
}

The schema is introspectable: clients can query the schema itself to discover what types and operations are available. This enables powerful tooling: GraphQL IDEs can autocomplete queries, validate them against the schema before sending, and display documentation inline.

Where GraphQL Wins

Precise data fetching: Clients request exactly what they need. Overfetching is eliminated by design.

Single round trip for complex data: Data from multiple resources is fetched in a single request. The N+1 problem is solved at the query level rather than requiring the client to make multiple requests.

Strongly typed schema: The schema is the contract. Clients can validate their queries against it at build time. Type mismatches are caught before deployment.

Frontend agility: Frontend teams can evolve their data requirements without asking backend teams to create new endpoints. New screens, data combinations, and features are all handled by writing a new query.

Excellent tooling: GraphiQL and Apollo Studio provide interactive schema exploration, query building, and performance analysis.

Where GraphQL Struggles

Query complexity: A malicious or poorly written query can request enormous amounts of nested data. A query that fetches every user, each user's orders, each order's items, and each item's product details can bring a server to its knees.

REST endpoints can be individually optimized. GraphQL requires query complexity analysis, depth limiting, and rate limiting to protect the server.

Caching is harder: REST GET requests are cacheable at the HTTP level by default. GraphQL queries all go through POST requests to a single endpoint, breaking standard HTTP caching. Clients must implement their own caching (Apollo Client does this), but CDN-level caching is essentially unavailable for dynamic queries.

Over-engineering simple APIs: If your API is straightforward CRUD operations with no complex data relationships and no mobile clients with aggressive data constraints, GraphQL's added setup cost exceeds its benefit.

Real-time at scale is complex: GraphQL subscriptions work, but scaling WebSocket connections for thousands of concurrent subscribers is infrastructure-intensive and requires careful architecture.

Error handling is non-standard: A GraphQL request can partially succeed: some fields resolve successfully while others fail. The response includes both data and errors simultaneously. Handling this gracefully requires more nuanced error handling logic than a simple HTTP status code.

WebSockets: When HTTP Is Not Enough

HTTP, in all its versions, is fundamentally request-response. The client speaks first. The server responds. The conversation ends. Even with HTTP/2's server push, the client initiates every new exchange.

But some applications genuinely need both sides to be able to speak at any moment, without waiting for the other to ask first. For example, a chat application where both parties send messages freely. A live collaborative document where every keystroke is broadcast to co-editors. An online game where the server pushes state updates as they happen and the client sends actions continuously.

For these cases, WebSockets provide a fundamentally different communication model.

The WebSocket Handshake

A WebSocket connection starts as an HTTP request and then upgrades to a WebSocket connection. This upgrade mechanism means WebSockets work through existing HTTP infrastructure (firewalls, proxies, load balancers) without requiring special configuration.

The upgrade request:

GET /chat HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

The server confirms the upgrade:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Status code 101 means "Switching Protocols." From this point forward, the HTTP connection is replaced by a WebSocket connection. The protocol has changed. HTTP headers, status codes, and methods no longer apply.

Full-Duplex, Persistent Communication

The WebSocket connection is:

• Full-duplex: both the client and server can send messages at any time, simultaneously, without waiting for the other to finish.

• Persistent: the connection stays open until explicitly closed by either party or until a network interruption occurs.

• Low overhead: once established, WebSocket messages have minimal framing overhead compared to HTTP. A small WebSocket message may have only 2 to 10 bytes of overhead, versus potentially hundreds of bytes of HTTP headers.

WebSocket connection open

Client: "Hello, I'm user 123"
Server: "Welcome, user 123"
Server: "User 456 just sent you a message: Hey!"
Client: "Thanks, here's my reply: Hi there!"
Server: "New notification: your payment was confirmed"
Client: "Great, show me my balance"
Server: "Your balance is NGN 500,000"
Server: "Another notification: transfer from user 789 received"

[Both sides communicate freely, at any time, simultaneously]

Where WebSockets Win

True real-time bidirectional communication: Applications where both client and server need to send messages at unpredictable times and at high frequency. For example, chat, live collaboration, multiplayer games, financial trading terminals.

Low-latency messaging: Once the connection is established, message round-trip times can be in the single-digit milliseconds, limited only by network latency rather than connection setup overhead.

Native browser support: The WebSocket API is built into every modern browser. No libraries are needed for the fundamental connection.

Event-driven architecture on the client: WebSocket events (message, close, error) map naturally to event-driven client code.

Where WebSockets Struggle

Stateful connections: Each WebSocket connection must be maintained by a specific server instance. When scaling horizontally, a client connected to Server A can't receive messages from Server B without a shared pub/sub layer (like Redis) that all server instances publish to and subscribe from. This adds infrastructure complexity.

No built-in request-response correlation: WebSockets are a message stream. If you send a message and expect a response, there's no built-in mechanism to correlate which response corresponds to which request. You have to build this yourself.

No schema or contract: WebSockets send raw text or binary. The format of messages is defined entirely by the application. Two systems communicating over WebSockets must agree on message format out of band, in documentation, and there's nothing to enforce it at the connection level.

Firewall and proxy complications: Some corporate networks and older proxies don't support the HTTP upgrade mechanism correctly, breaking WebSocket connections. This is less common than it was but still occurs in enterprise environments.

Reconnection must be handled manually: WebSocket connections can drop due to network instability. Applications must implement reconnection logic, including managing state across reconnections.

Server-Sent Events: The Simpler Real-Time Option

Between REST's pure request-response and WebSocket's full bidirectional communication lies a middle option that most developers overlook: Server-Sent Events (SSE).

SSE establishes a one-directional persistent connection: the server pushes data to the client over a regular HTTP connection, and the client listens. The client can't send data back through the same connection.

How SSE Works

The client makes a standard HTTP GET request with an Accept: text/event-stream header:

GET /notifications HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer token123

The server responds with a 200 OK and keeps the connection open, periodically sending events:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache

data: {"type": "balance_update", "balance": 500000}

data: {"type": "transaction", "id": "txn_001", "amount": -5000}

event: notification
data: {"message": "Your transfer has been confirmed"}

id: 42
data: {"type": "order_status", "status": "shipped"}

Each event is separated by a blank line. Events can include a data field, an optional event type, and an optional id for resumability.

Automatic Reconnection

One of SSE's most practical features is automatic reconnection. If the connection drops, the browser automatically reconnects, sending the last received event ID in a Last-Event-ID header. The server can resume from that point, ensuring no events are missed.

Where SSE Wins

Simplicity: SSE works over plain HTTP. There's no protocol upgrade needed, and no special infrastructure. It works through every HTTP/2 connection, load balancer, and CDN that supports streaming.

Native browser support: The EventSource API is built into every modern browser. Automatic reconnection is built in.

Perfect for one-directional feeds: Live dashboards, notification streams, news feeds, real-time analytics, server logs: any scenario where the server pushes a continuous stream of updates and the client only reads.

HTTP/2 multiplexing: Over HTTP/2, multiple SSE connections can share a single TCP connection. The browser connection limit that affected SSE over HTTP/1.1 doesn't apply.

Natural fit for existing infrastructure: SSE responses are just HTTP responses. Existing load balancers, authentication middleware, and monitoring tools work without modification.

Where SSE Struggles

One direction only: The client can't send data back through the SSE connection. For bidirectional scenarios, SSE isn't sufficient on its own.

Text only (natively): SSE events are text. Binary data must be base64-encoded, adding overhead.

No native support in all environments. SSE is a browser API. In other environments (mobile apps, server-to-server), it requires an HTTP client configured to handle streaming responses.

SSE vs WebSockets: The Decision

Choose SSE when the server pushes data and the client only reads: notifications, live feeds, dashboards, or streaming responses from an AI model. SSE is simpler, works over plain HTTP, and has automatic reconnection built in.

Choose WebSockets when both the client and server need to send messages freely and simultaneously: chat, collaborative editing, and games. The added complexity of WebSockets is justified when you genuinely need bidirectional communication.

Protocol Buffers: A New Language for Data

Protocol Buffers (protobuf) is a binary serialization format developed by Google. Where JSON encodes data as human-readable text, protobuf encodes data as compact binary. This single difference has cascading implications for payload size, parsing speed, type safety, and schema enforcement.

The Schema-First Approach

Unlike JSON, where you simply start writing key-value pairs, protobuf requires defining a schema first. You describe your data structures in a .proto file using Protocol Buffer Language, a language-agnostic schema definition language.

The schema definition:

syntax = "proto3";

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  double balance = 4;
  bool is_verified = 5;
  int32 kyc_level = 6;
}

message Order {
  string id = 1;
  string user_id = 2;
  double total = 3;
  string status = 4;
  int64 created_at = 5;
}

Each field has a name and a type, as in any structured data format. But it also has a field number: the small integer after the equals sign. This field number is the key to protobuf's efficiency.

Binary Encoding: Why Field Numbers Matter

When protobuf encodes data to binary, field names don't appear in the output. Instead, only the field number and the encoded value are written. Field 1 (id) becomes a tag byte indicating "field 1, type string" followed by the string's length and bytes. Field 4 (balance) becomes a tag byte indicating "field 4, type 64-bit float" followed by eight bytes of IEEE 754 double-precision float.

No "id": string, "balance": string, quotation marks, colons, or braces. Just field tags and values in a compact binary stream.

The same user object that occupies approximately 100 bytes in JSON occupies approximately 35 bytes in protobuf. For a 1000-field enterprise API response called millions of times per day, this difference translates directly to reduced bandwidth consumption and infrastructure cost.

Parsing binary is also fundamentally faster than parsing text. A binary parser reads a fixed-length tag, determines the type and length of the following value, reads that value, and moves to the next field. A JSON parser must tokenize a text stream character by character, handle escape sequences, infer types from value format, and construct a dynamic object from parsed key-value pairs.

On constrained devices or in high-throughput server-to-server communication, this parsing speed difference is meaningful.

Code Generation: The Contract Comes Alive

The .proto schema file is the input to the protoc compiler. This compiler generates data classes in any supported language from the same schema definition.

The same user.proto file generates:

• A User class in Go for the backend server

• A User class in Dart for the Flutter client

• A User class in Python for the data processing service

• A User class in TypeScript for the web frontend

Every generated class has typed fields, serialization/deserialization methods, and equality comparison. There's no manual JSON parsing, type casting, or risk of field name typos. The compiler guarantees that every language's representation of a User is identical.

When the schema changes — a new field is added or a field is removed, for example — every team regenerates their classes. If the change is breaking (a required field removed or a type changed in an incompatible way), the compiler reports errors in every affected codebase. The problem is caught before any code reaches production.

Schema Evolution Rules

Protobuf's field number system enables backward-compatible schema evolution. Because fields are identified by number rather than name, the following changes are safe:

• Adding a new field with a new number is always safe. Existing clients ignore fields they don't recognize. New clients receive the new field.

• Removing a field by marking it as reserved is safe. Existing encoded data that contains the removed field is simply ignored when decoded. The field number must be marked reserved to prevent its reuse.

• Renaming a field is safe. Names aren't encoded. Only the number matters at the binary level.

• Changing a field's type in incompatible ways is unsafe and breaks existing encoded data.

This evolution model means protobuf schemas can grow over time without coordinated updates across all clients and servers.

Trade-offs

Protobuf's efficiency comes with costs that make it inappropriate for all contexts.

Binary data isn't human-readable. You can't open a protobuf response in a browser's developer tools and see what it contains. Debugging requires either decoding the binary with the schema or using specialized tools.

Protobuf also requires tooling. Every consumer of a protobuf-encoded API needs the schema and a protobuf library to decode it. For public APIs consumed by unknown third parties, this is a significant barrier. JSON requires nothing: every programming environment can parse it with built-in libraries.

Schema changes require coordination. When a schema changes, every consumer must update. For internal systems where you control all consumers, this is manageable. For public APIs, it requires versioning and migration strategies.

gRPC: Remote Procedure Calls at Scale

gRPC combines Protocol Buffers with HTTP/2 and Remote Procedure Call semantics to produce a framework for service-to-service communication that is faster, more structured, and more powerful than REST for specific use cases.

Remote Procedure Calls: The Core Concept

A Remote Procedure Call (RPC) framework makes calling a function on a remote server feel like calling a local function. Instead of constructing an HTTP request, serializing a body, parsing a response, and handling status codes, you call a function with typed arguments and receive a typed return value. The network communication is abstracted away.

// Without RPC (manual REST)
const response = await http.post('/users', headers: {...}, body: json.encode(data));
const user = User.fromJson(json.decode(response.body));

// With RPC (gRPC)
final user = await userService.createUser(CreateUserRequest(name: "John", email: "john@example.com"));

The second form is simpler, type-safe, and requires no knowledge of HTTP methods, endpoints, or serialization formats.

The Four Communication Patterns

gRPC's most significant advantage over REST is its support for four distinct communication patterns, all defined in the same .proto schema and accessible through the same generated client.

Unary RPC is the familiar request-response pattern. One request and one response. It's equivalent to a REST API call.

Client ——— LoginRequest ——→ Server
Client ←—— LoginResponse —— Server

Server Streaming RPC sends one request and receives a continuous stream of responses. The server pushes messages as they become available without the client needing to request each one.

Client ——— WatchBalanceRequest ——→ Server
Client ←— BalanceResponse ———————— Server (balance: 500,000)
Client ←— BalanceResponse ———————— Server (balance: 495,000)
Client ←— BalanceResponse ———————— Server (balance: 1,000,000)
[Stream stays open, server pushes on every change]

Client Streaming RPC sends a stream of messages to the server and receives one response at the end. The server processes all received messages and responds once.

Client ——— DocumentChunk 1 ——→ Server
Client ——— DocumentChunk 2 ——→ Server
Client ——— DocumentChunk 3 ——→ Server
Client ←————— UploadResponse —— Server (all chunks processed)

Bidirectional Streaming RPC allows both client and server to send streams of messages simultaneously, in any order.

Client ——— ChatMessage ——→ Server
Server ←— ChatMessage ——— Client
Client ——— ChatMessage ——→ Server
Server ←— ChatMessage ——— Client  (server-initiated)
[Both sides communicate freely and simultaneously]

Why HTTP/2 and Protobuf Make gRPC Efficient

gRPC's efficiency comes from the combination of its two underlying technologies working together.

HTTP/2's multiplexed persistent connections mean many concurrent gRPC calls, including long-running streaming calls, share a single connection. There's no connection setup overhead per call. Multiple streams proceed in parallel without blocking each other.

Protocol Buffer's binary encoding means payloads are compact and parsing is fast. A high-frequency service-to-service call that would transmit 100 bytes of JSON transmits 35 bytes of protobuf. At thousands of calls per second between microservices, this difference is significant.

The generated clients eliminate all serialization and deserialization code. The schema enforces that client and server agree on the contract. Breaking changes are caught by the compiler.

The Organizational Contract

In organizations using gRPC at scale, .proto files live in a dedicated repository separate from any individual service. This repository is the single source of truth for every service contract.

When an engineer wants to add a new field to an API, they open a pull request in the proto repository. Engineers from every affected team review it. The change is discussed, refined, and approved before any implementation begins. When it merges, every team regenerates their clients. Changes that break existing behavior are caught in code review, not in production.

This governance model transforms API evolution from a coordination problem into a code review process.

gRPC's Limitations

gRPC doesn't work natively in web browsers. Browsers can't directly make HTTP/2 requests with the necessary control required for gRPC. A proxy layer (gRPC-Web) is required to translate between gRPC-Web's browser-compatible format and standard gRPC. This adds infrastructure complexity and limits gRPC's applicability for browser-based clients.

gRPC also requires HTTP/2. Environments that don't support HTTP/2 can't use gRPC.

Binary encoding makes debugging harder as well. Inspecting gRPC traffic requires specialized tools and access to the proto schema.

For public APIs consumed by third-party developers, gRPC's tooling requirements are a higher barrier than REST's universally accessible JSON over HTTP.

The Complete Comparison

How to Choose: The Engineering Decision Framework

No single communication approach is universally best. Each exists because it solves specific problems better than the alternatives. The engineering decision involves matching the tool to your requirements.

When to Use REST

Use REST when the API is public or consumed by third parties. REST's universal accessibility makes it the only reasonable choice for public APIs. Any developer in any language can call a REST API with standard HTTP tools. There are no schema files, generated clients, or special libraries.

REST is also a good fit when caching is a priority. REST GET responses can be cached at every layer: CDN, reverse proxy, and browser. For content that doesn't change frequently, REST with proper cache headers can serve millions of requests without hitting the origin server.

It's also solid when the operation is simple request-response. If you're building straightforward CRUD operations with no streaming requirements and no complex data relationships, REST is simpler to implement, document, and debug than any alternative.

And finally use REST when developer experience for the consumer matters. REST APIs are immediately accessible in a browser. They can be tested with curl. Every developer already understands them.

When to Use GraphQL

Use GraphQL when multiple client types have significantly different data needs. A mobile app that needs minimal data for a list view and richer data for a detail view, alongside a desktop app that needs comprehensive data, are ideal GraphQL consumers. Each queries exactly what it needs.

GraphQL also works well for complex interconnected data with many relationships. Social graphs, product catalogs with deeply nested attributes, or content management systems with rich content relationships: GraphQL's ability to traverse relationships in a single query is a genuine advantage.

It's also a good choice for frontend teams that need to iterate quickly. When the frontend can evolve its data requirements without backend changes, development velocity increases. New screens, new data combinations, no new endpoints needed.

And finally, GraphQL works well if you're comfortable with the operational complexity. GraphQL requires query complexity protection, custom caching strategies, and more sophisticated error handling. These are worth the effort when the data fetching advantages are real.

When to Use WebSockets

Use WebSockets when both the client and server need to send messages at any time. Genuine bidirectional real-time communication where either party can initiate a message at any moment.

WebSockets also work great for chat, collaboration, and games. Live chat applications, collaborative document editing, multiplayer real-time games are the canonical WebSocket use cases.

And WebSockets is a solid choice when low-latency messaging is critical. The minimal framing overhead and persistent connection make WebSockets the lowest-latency option for frequent message exchange.

When to Use Server-Sent Events

Use SSE when the server needs to push updates but the client only reads. Notification feeds, live dashboards, streaming AI responses, real-time analytics, or any scenario where the server has a continuous stream of data to deliver and the client only consumes.

SSE also works well when you value simplicity over full bidirectionality. SSE is significantly simpler to implement and operate than WebSockets for one-directional use cases. Automatic reconnection is built in. It works over plain HTTP.

When to Use gRPC

Use gRPC when multiple internal services share the same contract. When several teams build services that call each other, a .proto schema enforced by the compiler prevents contract drift. Everyone generates their clients from the same source of truth.

gRPC also works well for high-frequency service-to-service communication. Two microservices exchanging thousands of calls per second benefit from protobuf's compact binary encoding and HTTP/2's persistent multiplexed connections.

It's also a solid choice for large payloads that are consumed by many internal systems. An internal enterprise API with hundreds of fields called by dozens of internal applications benefits enormously from protobuf's size reduction. Less bandwidth, less parsing overhead, and compiled contract enforcement.

gRPC also works great when low-bandwidth networks matter. For mobile applications in markets where network conditions are variable or constrained, protobuf's binary encoding reduces payload size by 3 to 10 times compared to JSON. The difference between a 15 kilobyte response and a 3 kilobyte response is the difference between a 3-second load and a sub-second load on a 2G connection.

And finally, use gRPC when streaming is a core requirement and you want one framework. gRPC's four communication patterns (unary, server streaming, client streaming, and bidirectional) cover every scenario without requiring separate WebSocket infrastructure alongside your API.

The Hybrid Reality

Most sophisticated systems use multiple approaches, each where it genuinely wins:

A Large Engineering Organization

Public REST API
  External developers, partners, open integrations
  JSON over HTTPS. OpenAPI documentation.
  CDN caching for frequently accessed resources.

Internal gRPC Network
  Service-to-service communication
  Auth service, payment service, notification service,
  fraud detection: all communicating with typed contracts
  over efficient binary protobuf on HTTP/2.

Real-Time Layer
  WebSockets for bidirectional features (live chat, collaboration)
  SSE for one-directional feeds (notifications, live dashboards)
  gRPC streaming for real-time data with typed contracts

Mobile API
  REST for standard operations (profile, settings, history)
  gRPC for high-frequency or large payload calls
  SSE for notification streaming

There's no architectural purity requirement. Each layer uses what fits its requirements. The discipline is in making these choices deliberately rather than by habit or default.

Conclusion

The history of how clients and servers communicate is the history of engineers discovering the limitations of existing tools and building better ones.

HTTP/1.1 gave us a universal request-response protocol that built the web. Its text-based format and sequential connection model worked well for the web of the 1990s and 2000s. As applications became more complex and performance expectations rose, its limitations became bottlenecks.

HTTP/2 rebuilt the transport layer with binary framing and multiplexing, eliminating head-of-line blocking at the HTTP level, compressing headers, and enabling server push. HTTP/3 took this further by replacing TCP with QUIC, addressing the remaining head-of-line blocking at the transport level and making connection establishment faster.

JSON became the dominant data format because of its human readability and universal support. Protocol Buffers emerged as an alternative for contexts where JSON's verbosity and lack of schema enforcement create real problems: internal services, high-frequency communication, constrained networks, and teams needing compile-time contract enforcement.

REST codified HTTP's architectural strengths into a style that made APIs universally accessible and HTTP-native. Its success wasn't purely technical: it aligned with what developers already understood and what the HTTP ecosystem already supported. Its limitations in data fetching efficiency and real-time communication opened the door for GraphQL and streaming alternatives.

GraphQL solved REST's overfetching and underfetching problems by inverting control: the client specifies exactly what it needs. WebSockets solved REST's inability to support genuine bidirectional real-time communication. Server-Sent Events provided a simpler real-time option for one-directional streaming. gRPC combined Protocol Buffers, HTTP/2, and RPC semantics into a framework that excels at typed service-to-service communication at scale.

Understanding all of these tools, along with why each was built, what problem it solves, and where it struggles, is what enables you to make deliberate architectural decisions rather than defaulting to whatever is most familiar.

The right communication approach is always the one that fits the specific requirements of the system you're building: the clients consuming it, the data being exchanged, the network conditions it operates in, the teams building and maintaining it, and the operational complexity you are prepared to manage.

That clarity of fit is what engineering judgment looks like in practice.

The question is never whether systems need to communicate. The question is always how.

For years, REST over HTTP with JSON was the default answer. It works, it's simple, and the tooling is everywhere. But as systems grow in scale (in the number of services talking to each other, the volume of data being exchanged, and the need for real-time communication), REST starts to show its limits.

This is where Remote Procedure Calls, Protocol Buffers, and gRPC enter the picture.

In this handbook, you'll learn what RPC is and the problem it was designed to solve. You'll also understand Protocol Buffers: what they are, why they exist, and how they work.

You'll then see how Google combined these ideas into gRPC, one of the most powerful communication frameworks in modern distributed systems. You'll learn all four gRPC communication patterns, see code generated across multiple languages from a single contract file, and walk through a complete end-to-end Flutter implementation with production-grade concerns including authentication, error handling, and timeouts.

By the end, you won't just know what gRPC is. You'll understand when to use it, when not to, and how to think about service communication as a systems engineer.

Table of Contents

• What is a Remote Procedure Call?

• The Problem RPC Solves

• Why gRPC Over REST: The Real Case

• Protocol Buffers: A New Language for Data

• The Proto File

• JSON vs Protocol Buffers

• The Protoc Compiler and Code Generation

• What is gRPC?

• Why HTTP/2 Matters for gRPC

• The Four gRPC Communication Patterns

• The Protobuf Repository: Organizational Best Practice

• Building a Complete gRPC System with Dart and Flutter

• Production Concerns

• gRPC vs REST vs WebSockets: When to Use What

• The Hybrid Architecture

• Conclusion

What is a Remote Procedure Call?

To understand RPCs, you first need to understand what a procedure call is.

A procedure call means invoking a procedure or function so that its code executes. For example, in Dart:

double calculateTax(double amount) {
  return amount * 0.075;
}

final tax = calculateTax(50000); // local procedure call

You call calculateTax, pass an argument, and get a result back. The function lives on the same machine, in the same process, in the same memory space. This is a local procedure call.

A Remote Procedure Call takes this same idea and stretches it across a network. The function you're calling lives on a different machine, in a different process, and potentially in a different country. But from the caller's perspective, it feels exactly like calling a local function.

// This looks like a local function call
final tax = await taxService.calculateTax(amount: 50000);

// But under the hood, this:
// 1. Serializes the argument into a binary format
// 2. Sends it over a network connection to a remote server
// 3. The server executes calculateTax with your argument
// 4. Serializes the result
// 5. Sends it back over the network
// 6. Deserializes it into a Dart object
// 7. Returns it to you as if it were local

The network complexity is completely hidden. You call a function. You get a result. Everything in between is handled by the RPC framework.

This is the fundamental idea behind RPC: make calling a remote function feel as natural as calling a local one.

The Problem RPC Solves

To appreciate why RPC matters, you need to understand what the alternative looks like.

Without RPC, calling a remote service looks like this:

Future<double> calculateTax(double amount) async {
  final response = await http.post(
    Uri.parse('https://tax-service.internal/api/v1/calculate'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $token',
    },
    body: jsonEncode({'amount': amount}),
  );

  if (response.statusCode != 200) {
    throw Exception('Tax calculation failed: ${response.statusCode}');
  }

  final data = jsonDecode(response.body);
  return (data['tax'] as num).toDouble();
}

Every service call requires you to:

• Know and hardcode the endpoint URL

• Know the correct HTTP method

• Manually serialize your request to JSON

• Handle HTTP status codes yourself

• Manually deserialize the response from JSON

• Cast dynamic types to the types you actually expect

• Hope the field names in the response match what you think they are

Now multiply this by every single service call in your application. An authentication service, a user service, a payment service, a notification service, a transaction service. Every one of them requires the same manual boilerplate. Every one of them introduces the possibility of a typo in a field name, a wrong status code assumption, or a JSON deserialization failure that only surfaces at runtime.

With RPC:

// Feels like a local function call
final tax = await taxService.calculateTax(
  TaxRequest(amount: 50000),
);
// tax is already a strongly typed TaxResponse object
// No URLs. No HTTP methods. No JSON parsing. No casting.

The framework handles everything. The function signature is defined in a contract file that both the client and server use. The types are enforced at compile time. If the server changes the response shape, the client fails to compile before anything reaches production.

This is what RPC solves: it removes the accidental complexity of network communication and lets you focus on what you're actually trying to do.

Why gRPC Over REST: The Real Case

Before going into the technical details of Protocol Buffers and gRPC, it's important to make a solid case for why you'd choose gRPC over REST in specific scenarios. This isn't a claim that gRPC is always better. It's a clear look at where it genuinely wins.

Large Payloads Called by Many Internal Systems

Consider an internal enterprise API in a large telecommunications company. A single request and response payload for a plan registration or activation flow can contain over a thousand fields. This endpoint is called by dozens of internal applications: billing systems, CRM platforms, customer-facing mobile apps, internal dashboards, and partner portals.

With REST and JSON, every one of those applications sends and receives that thousand-field payload as text. Field names like subscription_activation_status, rate_plan_identifier, and network_provisioning_reference travel over the wire as strings on every single request. A significant portion of every payload isn't data. It's labels for data.

With Protocol Buffers, field names never appear in the payload at all. Only field numbers and values travel over the wire. That thousand-field payload shrinks dramatically. For an endpoint called millions of times per day by dozens of systems, the bandwidth saving is enormous and translates directly to infrastructure cost reduction.

Beyond size, the generated client guarantee is equally important. With REST, each of those dozens of applications reads the API documentation and builds its own understanding of the contract. When the backend changes a field name or type, not every application finds out immediately. Some find out in production when they break.

With a shared .proto file, every application generates its own strongly typed client from the same source. A contract change means every application regenerates. The compiler immediately reports where the breaking change affects each codebase. Nothing reaches production in a broken state.

Low Bandwidth and Remote Network Conditions

This is one of the most under-appreciated advantages of gRPC in markets where network quality varies significantly.

In many regions, a substantial portion of mobile users are on 2G or 3G connections. On a 2G connection, bandwidth can be as low as 50 to 100 kilobits per second. A REST JSON response that is 80 kilobytes takes over 6 seconds to download on a 2G connection. The equivalent protobuf binary, which can be 3 to 10 times smaller, takes under 2 seconds.

That difference isn't a technical footnote. It's the line between an application that feels usable and one that feels broken to a significant portion of your users. For any product that operates in markets with variable network conditions, protobuf's binary efficiency is a direct competitive advantage.

Beyond size, gRPC runs over HTTP/2 which maintains a single persistent connection rather than opening a new connection for every request. On slow networks where connection establishment (the TCP handshake and TLS negotiation) can itself take hundreds of milliseconds, reusing a single connection across many calls saves significant time over a session.

Microservice to Microservice Communication

When two internal services need to communicate, you have options. A message bus like Kafka or RabbitMQ is excellent when you don't need an immediate response, when the operation can happen asynchronously, and when you're broadcasting something that happened to multiple consumers.

But many service-to-service calls are synchronous by nature. An authentication service needs to validate a token right now before the request proceeds. A fraud detection service needs to assess a transaction right now before the payment is authorized. A pricing service needs to calculate a rate right now before the quote is generated. These operations can't publish an event and wait.

For synchronous service-to-service calls at high frequency, gRPC over HTTP/2 with protobuf encoding is significantly more efficient than REST. The persistent multiplexed connection means no connection setup overhead per call. The binary encoding means no JSON serialization and deserialization overhead on every hop. The generated clients mean both services compile against the same contract.

At scale, when two services are calling each other thousands of times per second, these efficiency differences compound into real performance and cost differences.

Managing API Contracts Across Multiple Teams

In a large engineering organization, multiple teams build services that others depend on. REST API contracts live in documentation. Documentation goes stale. The backend team changes a field name. The mobile team finds out when users report crashes. The data team finds out when their pipeline throws an error at 2am.

gRPC's protobuf repository approach transforms contract management from a documentation problem into a code problem. Contract changes go through pull requests. Every dependent team reviews the change. Breaking changes are caught at compile time. Nobody is surprised in production.

This governance benefit scales with team size. The larger the organization, the more valuable it becomes.

Real-Time Communication

REST is request-response. The client asks and the server answers. The conversation ends. For real-time features, you either poll (wasteful) or bolt on a separate WebSocket server alongside your REST API (two different systems to maintain).

gRPC's streaming patterns handle real-time communication natively within the same framework you use for regular calls. A live balance update, a real-time transaction notification, or a bidirectional chat session all use the same generated client, the same connection, and the same protobuf encoding as your regular unary calls.

One framework with all communication patterns. No separate infrastructure.

Protocol Buffers: A New Language for Data

RPC is a concept. To implement it, you need two things: a way to define the contract between client and server, and a way to serialize data efficiently for transmission over the network.

This is where Protocol Buffers comes in.

Protocol Buffers, commonly called protobuf, is a language-neutral, platform-neutral, extensible mechanism for serializing structured data. It was developed at Google in 2001, used internally for years, and open-sourced in 2008.

The JSON Problem at Scale

JSON is the dominant data format for web APIs. It's human-readable, flexible, and universally supported. For many use cases, it's the right choice.

But JSON has structural inefficiencies that become painful at scale.

Consider a user profile response:

{
  "id": "usr_001",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john@example.com",
  "phone_number": "+2348012345678",
  "account_type": "savings",
  "balance": 500000.00,
  "currency": "NGN",
  "is_verified": true,
  "is_active": true,
  "kyc_level": 3,
  "created_at": "2024-01-15T10:30:00Z",
  "last_login": "2026-07-20T09:15:00Z"
}

Every field name travels over the network as a string on every single response. "first_name", "account_type", "phone_number" aren't data. They're labels for data. But they consume bytes on every request.

Now consider an internal enterprise API with over a thousand fields in its request and response payload, being called by dozens of internal applications thousands of times per day. A significant portion of every payload is field name strings, not actual data. The overhead accumulates into real bandwidth and processing costs.

Beyond size, JSON has another problem: it has no schema at the network level. Nothing prevents a backend engineer from renaming "first_name" to "firstName" in a new deployment. The client breaks at runtime in production with real users.

What Protocol Buffers Do Differently

Protocol Buffers solve both problems with a fundamentally different approach to data encoding.

Instead of encoding data as human-readable text with field names, protobuf encodes data as compact binary using only field numbers and values. Field names never travel over the network.

Here's the same user profile defined in protobuf:

message UserProfile {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
  string email = 4;
  string phone_number = 5;
  string account_type = 6;
  double balance = 7;
  string currency = 8;
  bool is_verified = 9;
  bool is_active = 10;
  int32 kyc_level = 11;
  string created_at = 12;
  string last_login = 13;
}

When protobuf encodes this data, the output is binary that no human can read. But to a machine, it's extremely compact and fast to parse. The field numbers (1, 2, 3...) identify each field. The names never appear in the encoded output at all.

The result: the same user profile that's approximately 280 bytes in JSON is approximately 95 bytes in protobuf. That's three times smaller. For a thousand-field enterprise payload, this difference is enormous.

And because the schema is defined in a .proto file that both client and server compile against, field name changes are caught at compile time, not at runtime.

The Proto File

The .proto file is the heart of everything in the protobuf and gRPC ecosystem. It's where you define your data models and your service contracts.

It's written in Protocol Buffer Language (proto3) – not Go, not Dart, not Python, not Java. You write it in any text editor. VS Code with the vscode-proto3 extension gives you syntax highlighting, autocomplete, and inline validation.

Here's a complete .proto file for a fintech platform:

syntax = "proto3";

package banking;

option go_package = "./banking";
option java_package = "com.fintech.banking";



service BankingService {
  // Unary: one request, one response
  rpc Login (LoginRequest) returns (LoginResponse);

  // Unary: fetch user profile
  rpc GetProfile (ProfileRequest) returns (UserProfile);

  // Server streaming: real-time balance updates
  rpc WatchBalance (BalanceRequest) returns (stream BalanceResponse);

  // Server streaming: live transaction feed
  rpc StreamTransactions (TransactionRequest) returns (stream Transaction);

  // Client streaming: upload KYC documents in chunks
  rpc UploadDocument (stream DocumentChunk) returns (UploadResponse);

  // Bidirectional streaming: live chat support
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}



message LoginRequest {
  string email = 1;
  string password = 2;
}

message LoginResponse {
  string token = 1;
  string user_id = 2;
  int64 expires_at = 3;
}

message ProfileRequest {
  string user_id = 1;
}

message UserProfile {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
  string email = 4;
  string phone_number = 5;
  string account_type = 6;
  double balance = 7;
  string currency = 8;
  bool is_verified = 9;
  int32 kyc_level = 10;
}

message BalanceRequest {
  string user_id = 1;
}

message BalanceResponse {
  double balance = 1;
  string currency = 2;
  int64 timestamp = 3;
}

message TransactionRequest {
  string user_id = 1;
  int32 limit = 2;
}

message Transaction {
  string id = 1;
  double amount = 2;
  string description = 3;
  string type = 4;
  int64 timestamp = 5;
}

message DocumentChunk {
  bytes data = 1;
  string document_type = 2;
  int32 chunk_index = 3;
  bool is_last = 4;
}

message UploadResponse {
  bool success = 1;
  string document_id = 2;
  string message = 3;
}

message ChatMessage {
  string sender_id = 1;
  string content = 2;
  int64 timestamp = 3;
}

Let's walk through every part of this file carefully.

The Syntax Declaration

syntax = "proto3";

This tells the protobuf compiler which version of the Protocol Buffer language you're using. proto3 is the current standard. It must be the first non-comment line in every .proto file.

The Package Declaration

package banking;

The package name prevents naming conflicts when you have multiple .proto files across different services. It functions like a namespace. If two services both define a UserProfile message, the package name distinguishes them: banking.UserProfile versus auth.UserProfile.

Language-Specific Options

option go_package = "./banking";
option java_package = "com.fintech.banking";

These options tell the compiler how to organize the generated code for specific languages. They don't affect the proto file itself, only the generated output.

The Service Definition

service BankingService {
  rpc Login (LoginRequest) returns (LoginResponse);
  rpc WatchBalance (BalanceRequest) returns (stream BalanceResponse);
}

The service block defines the RPC contract. Think of it exactly like an abstract class in any object-oriented language. It declares what functions exist, what they accept, and what they return.

Each rpc line defines one remote procedure. The stream keyword before a type indicates that multiple messages will flow rather than just one.

Message Definitions

message LoginRequest {
  string email = 1;
  string password = 2;
}

A message is a data structure. Think of it as a class with only fields: no methods, no logic. Each field has three parts.

The type can be string, int32, int64, double, bool, bytes, or another message type.

The name is the field name as it appears in generated code. This is for human readability only. It never appears in the binary encoding.

The field number (= 1, = 2, = 3) is the unique identifier that protobuf uses in the binary output instead of the field name. This is critical: once you assign a field number, you must never change it or reuse it. The binary encoding uses these numbers, not names. If you change a field number, old encoded data becomes unreadable.

You can safely add new fields with new numbers, remove fields (the number stays reserved, never reuse it), and rename fields (names don't appear in binary). You must never change a field number, reuse a removed field's number, or change a field's type.

JSON vs Protocol Buffers

Now that you understand both formats, let's make a direct comparison.

Size Comparison

Let's look at the same login request in both formats:

JSON (text):

{
  "email": "john@example.com",
  "password": "securepassword123"
}

Approximately 55 bytes.

Protobuf binary:

Field 1 (email): tag + length + value bytes. Field 2 (password): tag + length + value bytes.

Approximately 38 bytes.

For a simple two-field message, the difference is modest. Now consider a thousand-field enterprise payload. Field names alone in JSON can account for 40-60% of the total payload size. In protobuf, field names contribute zero bytes to the payload.

On a 2G connection where bandwidth can be as low as 50 kilobits per second, the difference between an 80 kilobyte JSON response and a 15 kilobyte protobuf response is the difference between a 13-second load and a 2-second load. For users in areas with limited network infrastructure, this isn't a performance metric. It's a usability threshold.

Speed Comparison

Protobuf serialization and deserialization is significantly faster than JSON parsing because binary parsing requires no string tokenizing, quote handling, whitespace skipping, or type inference. The parser reads a field number, reads the value type, reads the value, and moves to the next field. It's a direct binary read.

JSON parsing must tokenize a string character by character, identify keys and values by their surrounding quotes and delimiters, infer types from the value format, and construct objects from dynamic maps.

On a mobile device handling hundreds of responses per session, this parsing difference translates to measurable CPU and battery savings.

Schema and Type Safety

JSON has no schema enforcement at the network level. A backend can change "balance" to "current_balance" and the client only discovers this when the app crashes in production.

Protobuf schemas are enforced at compile time. If the .proto file changes in a way that breaks the client, the client fails to compile. The problem is caught before it reaches any user.

The Honest Comparison

The Protoc Compiler and Code Generation

The protoc compiler reads your .proto file and generates code in any language you specify. This is where the universal contract becomes reality.

Generating Go code (for the backend server):

protoc \
  --go_out=. \
  --go-grpc_out=. \
  proto/banking.proto

Generates:

banking.pb.go        <- the message structs
banking_grpc.pb.go   <- the server interface

Generating Dart code (for the Flutter client):

protoc \
  --dart_out=grpc:lib/generated \
  proto/banking.proto

Generates:

lib/generated/
  banking.pb.dart        <- the message classes
  banking.pbgrpc.dart    <- the client stub

Generating Python code (for a data service):

protoc \
  --python_out=. \
  --grpc_python_out=. \
  proto/banking.proto

Generates:

banking_pb2.py         <- the message classes
banking_pb2_grpc.py    <- the client and server classes

Generating TypeScript code (for a web frontend):

protoc \
  --ts_out=. \
  proto/banking.proto

Generates:

banking.ts             <- typed message classes and client

All of this from the same single banking.proto file.

The Go backend engineer never writes serialization code. The Flutter engineer never writes deserialization code. The Python data engineer never parses binary manually. The TypeScript web engineer never constructs HTTP requests. All of that is generated automatically from the contract that every team agreed on.

Here's what the generated code looks like in each language to make this concrete:

Generated Go server interface (the backend implements this):

// Generated — do not edit
type BankingServiceServer interface {
    Login(context.Context, *LoginRequest) (*LoginResponse, error)
    WatchBalance(*BalanceRequest, BankingService_WatchBalanceServer) error
    mustEmbedUnimplementedBankingServiceServer()
}

// The Go backend engineer writes this implementation
type bankingServer struct {
    pb.UnimplementedBankingServiceServer
}

func (s *bankingServer) Login(
    ctx context.Context,
    req *pb.LoginRequest,
) (*pb.LoginResponse, error) {
    token, err := authService.Login(req.Email, req.Password)
    if err != nil {
        return nil, status.Errorf(codes.Unauthenticated, "invalid credentials")
    }
    return &pb.LoginResponse{
        Token:  token,
        UserId: user.Id,
    }, nil
}

Generated Python client (the data team uses this):

import grpc
import banking_pb2
import banking_pb2_grpc

channel = grpc.secure_channel(
    'api.fintech-platform.com:50051',
    grpc.ssl_channel_credentials()
)
stub = banking_pb2_grpc.BankingServiceStub(channel)

response = stub.Login(banking_pb2.LoginRequest(
    email='john@example.com',
    password='password123'
))

print(f"Token: {response.token}")
print(f"User ID: {response.user_id}")

Generated Dart client (you use this in Flutter):

import 'package:grpc/grpc.dart';
import 'generated/banking.pbgrpc.dart';
import 'generated/banking.pb.dart';

final channel = ClientChannel('api.fintech-platform.com', port: 50051);
final client = BankingServiceClient(channel);

final response = await client.login(
  LoginRequest(email: 'john@example.com', password: 'password123'),
);

print('Token: ${response.token}');
print('User ID: ${response.userId}');

Three different languages. Three different teams. One .proto file. All of them are generated, strongly typed, and guaranteed to be in sync with the server.

What is gRPC?

gRPC is Google's open-source Remote Procedure Call framework. It was open-sourced in 2016 and is now a Cloud Native Computing Foundation (CNCF) graduated project. This means it's been production-proven at the highest level of the cloud-native ecosystem.

gRPC combines three things:

1. Remote Procedure Calls as the programming model: calling remote functions like local ones.

2. Protocol Buffers as the interface definition language and data serialization format: strongly typed contracts and compact binary encoding.

3. HTTP/2 as the transport protocol: multiplexed, persistent connections with binary framing.

The combination of these three produces a framework that's faster than REST, more structured than WebSockets, and more powerful than any of its predecessors.

gRPC is used internally at Google for virtually all service-to-service communication. Netflix, Uber, Square, Dropbox, Lyft, and hundreds of other organizations use it for their internal microservice communication. Official support exists for Go, Java, Python, C++, C#, Ruby, Node.js, PHP, Dart, Kotlin, and more.

Why HTTP/2 Matters for gRPC

gRPC is built exclusively on HTTP/2. Understanding what HTTP/2 provides is essential to understanding why gRPC performs the way it does.

HTTP/1.1, which powers most REST APIs, has fundamental performance constraints. Each request must complete before the next one begins on the same connection. Headers are sent as verbose text on every request. The server can't send data unless the client asks first.

HTTP/2 was designed to fix these constraints at the protocol level.

Multiplexing

HTTP/2 introduces streams within a single connection. Multiple independent requests can travel over the same TCP connection simultaneously.

Single TCP connection to api.fintech-platform.com

Stream 1: Login request ---------> Login response
Stream 2: Profile request -------> Profile response
Stream 3: Balance request -------> Balance stream (ongoing)
Stream 4: Transactions request --> Transaction stream (ongoing)

All four streams active simultaneously over ONE connection

In HTTP/1.1, you would need four separate connections or wait for each to complete before starting the next. HTTP/2 handles all four over a single persistent connection with no waiting.

This is the foundation of gRPC's streaming capabilities. A persistent multiplexed connection is what allows the server to keep pushing balance updates and transaction notifications while the client continues making other calls.

Binary Framing

HTTP/1.1 sends everything as text. HTTP/2 sends everything as binary frames. Binary is more compact and significantly faster for machines to parse.

Every gRPC message is broken into binary frames and sent over the HTTP/2 connection. Combined with protobuf's binary encoding, gRPC data travels in the most compact form possible at every layer.

Header Compression (HPACK)

HTTP/1.1 sends full headers on every request. An Authorization header carrying a JWT token can be 500 bytes or more, repeated on every request.

HTTP/2 uses HPACK compression. Headers sent on previous requests are cached. Subsequent requests only send headers that changed. The Authorization header, once sent, is referenced by a short index rather than retransmitted in full.

On a mobile application making dozens of authenticated requests per session, this compression is a meaningful bandwidth saving, especially on slow networks where every byte matters.

Server Push

HTTP/2 allows the server to proactively send data to the client without waiting for a request. The client opens a stream and the server keeps pushing messages through it as events occur.

This is the mechanism behind gRPC server streaming. The client sends one WatchBalance request and the server pushes a new BalanceResponse every time the balance changes. No polling or repeated requests. The connection stays open and the server speaks whenever it has something new to say.

The Four gRPC Communication Patterns

This is the most important section of this article. gRPC doesn't have one communication model. It has four. Each one is defined precisely in the .proto file and serves different use cases.

Pattern 1: Unary RPC

One request from the client and one response from the server. This is identical to a REST API call in terms of the request-response flow.

rpc Login (LoginRequest) returns (LoginResponse);

Client ----LoginRequest----> Server
Client <---LoginResponse---- Server
Done.

When to use Unary RPC: Login, profile fetch, payment initiation, data creation, configuration retrieval: any operation that follows a simple ask-and-answer pattern.

Dart implementation:

Future<LoginResponse> login(String email, String password) async {
  try {
    return await _client.login(
      LoginRequest(email: email, password: password),
    );
  } on GrpcError catch (e) {
    throw _mapGrpcError(e);
  }
}

Go server implementation:

func (s *bankingServer) Login(
    ctx context.Context,
    req *pb.LoginRequest,
) (*pb.LoginResponse, error) {
    user, err := s.authService.Login(req.Email, req.Password)
    if err != nil {
        return nil, status.Errorf(codes.Unauthenticated, "invalid credentials: %v", err)
    }
    token, _ := s.tokenService.Generate(user.Id)
    return &pb.LoginResponse{
        Token:  token,
        UserId: user.Id,
    }, nil
}

Pattern 2: Server Streaming RPC

One request from the client and a continuous stream of responses from the server. The connection stays open and the server pushes messages as they become available.

rpc WatchBalance (BalanceRequest) returns (stream BalanceResponse);
rpc StreamTransactions (TransactionRequest) returns (stream Transaction);

Client ----BalanceRequest----> Server
Client <---BalanceResponse---- Server (balance: 500000)
Client <---BalanceResponse---- Server (balance: 495000, after a debit)
Client <---BalanceResponse---- Server (balance: 995000, after a credit)
[stream stays open, server pushes on every change]

When to use Server Streaming: Live account balance, real-time transaction notifications, live stock prices, sports scores, news feeds, system monitoring dashboards: anything where the server has an ongoing series of updates to deliver.

Dart implementation:

Stream<BalanceResponse> watchBalance(String userId) {
  return _client.watchBalance(
    BalanceRequest(userId: userId),
  );
}

In Flutter, consume this with a StreamBuilder:

StreamBuilder<BalanceResponse>(
  stream: _dataSource.watchBalance(currentUserId),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }

    if (snapshot.hasError) {
      return Text('Error: ${snapshot.error}');
    }

    if (!snapshot.hasData) {
      return const Text('Waiting for balance...');
    }

    final balance = snapshot.data!;
    return Column(
      children: [
        Text(
          '${balance.currency} ${balance.balance.toStringAsFixed(2)}',
          style: const TextStyle(
            fontSize: 36,
            fontWeight: FontWeight.bold,
          ),
        ),
        Text(
          'Updated: ${DateTime.fromMillisecondsSinceEpoch(balance.timestamp.toInt())}',
        ),
      ],
    );
  },
)

Every time the server pushes a new balance, the StreamBuilder calls builder again and the widget shows the updated value. There's zero polling logic or manual refresh. The server speaks and the widget listens.

Go server implementation:

func (s *bankingServer) WatchBalance(
    req *pb.BalanceRequest,
    stream pb.BankingService_WatchBalanceServer,
) error {
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-stream.Context().Done():
            return nil
        case <-ticker.C:
            balance, err := s.accountService.GetBalance(req.UserId)
            if err != nil {
                return status.Errorf(codes.Internal, "failed to fetch balance: %v", err)
            }

            if err := stream.Send(&pb.BalanceResponse{
                Balance:   balance.Amount,
                Currency:  balance.Currency,
                Timestamp: time.Now().UnixMilli(),
            }); err != nil {
                return err
            }
        }
    }
}

Pattern 3: Client Streaming RPC

The client sends a stream of messages to the server. The server processes them all and responds once at the end.

rpc UploadDocument (stream DocumentChunk) returns (UploadResponse);

Client ----Chunk 1 (bytes 0-1024)-----> Server
Client ----Chunk 2 (bytes 1024-2048)--> Server
Client ----Chunk 3 (bytes 2048-3072)--> Server
Client ----Chunk 4 (last chunk)-------> Server
Client <---UploadResponse-------------- Server (document_id: "doc_001")

When to use Client Streaming: Uploading large files (KYC documents, profile photos) in chunks, sending a batch of sensor readings, submitting bulk records to a server.

Dart implementation:

Future<UploadResponse> uploadDocument(
  List<Uint8List> chunks,
  String documentType,
) async {
  try {
    Stream<DocumentChunk> chunkStream() async* {
      for (int i = 0; i < chunks.length; i++) {
        yield DocumentChunk(
          data: chunks[i],
          documentType: documentType,
          chunkIndex: i,
          isLast: i == chunks.length - 1,
        );
      }
    }

    return await _client.uploadDocument(chunkStream());
  } on GrpcError catch (e) {
    throw _mapGrpcError(e);
  }
}

chunkStream() is an async generator function. The async* keyword means it yields values over time rather than returning a single value. Each yield produces one DocumentChunk message that gRPC sends to the server. The server receives these one by one and processes them all before sending a single UploadResponse at the end.

Go server implementation:

func (s *bankingServer) UploadDocument(
    stream pb.BankingService_UploadDocumentServer,
) error {
    var allData []byte
    var documentType string

    for {
        chunk, err := stream.Recv()
        if err == io.EOF {
            break
        }
        if err != nil {
            return status.Errorf(codes.Internal, "failed to receive chunk: %v", err)
        }

        allData = append(allData, chunk.Data...)
        documentType = chunk.DocumentType
    }

    docId, err := s.documentService.Store(allData, documentType)
    if err != nil {
        return status.Errorf(codes.Internal, "failed to store document: %v", err)
    }

    return stream.SendAndClose(&pb.UploadResponse{
        Success:    true,
        DocumentId: docId,
        Message:    "Document uploaded successfully",
    })
}

Pattern 4: Bidirectional Streaming RPC

Both the client and server stream messages simultaneously. Both sides can send at any time. Neither waits for the other.

rpc Chat (stream ChatMessage) returns (stream ChatMessage);

Client ----"Hello"---------------------------> Server
Server <---"Hi, how can I help?"-------------- Client
Client ----"What is my account balance?"-----> Server
Server <---"Your balance is NGN 500,000"------ Client
Server <---"New transaction alert: -5,000"---- Client (server-initiated)
Client ----"Thanks"--------------------------> Server
[both sides communicate freely and simultaneously]

When to use Bidirectional Streaming: Real-time chat, live collaborative document editing, multiplayer game state synchronization, interactive trading terminals, real-time customer support sessions.

Dart implementation:

void startChat(String userId) {
  final outgoing = StreamController<ChatMessage>();

  final incoming = _client.chat(outgoing.stream);

  incoming.listen(
    (message) {
      print('${message.senderId}: ${message.content}');
    },
    onError: (error) {
      print('Chat error: $error');
    },
    onDone: () {
      print('Chat session ended');
    },
  );

  outgoing.add(ChatMessage(
    senderId: userId,
    content: 'Hello, I need help with my account',
    timestamp: DateTime.now().millisecondsSinceEpoch,
  ));
}

StreamController manages the outgoing message stream. You add messages to outgoing whenever the user sends something. The incoming stream delivers messages from the server. Both run simultaneously over the same HTTP/2 connection.

Go server implementation:

func (s *bankingServer) Chat(stream pb.BankingService_ChatServer) error {
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        response := s.chatService.Process(msg)
        if err := stream.Send(&pb.ChatMessage{
            SenderId:  "support_agent",
            Content:   response,
            Timestamp: time.Now().UnixMilli(),
        }); err != nil {
            return err
        }
    }
}

The Protobuf Repository: Organizational Best Practice

In a small project, the .proto file can live inside the backend repository. The mobile engineer clones the backend repo to get it. This works at small scale.

In any organization of meaningful size, this approach breaks down. The backend repo becomes the source of truth, giving the backend team unilateral control over the contract. Other teams find out about changes when their builds break.

The industry best practice is a dedicated protobuf repository: a standalone repository that belongs to everyone and is owned exclusively by no one.

fintech-api-contracts/
  proto/
    auth/
      auth.proto
    banking/
      banking.proto
    payments/
      payments.proto
    notifications/
      notifications.proto
    kyc/
      kyc.proto
  scripts/
    generate_dart.sh
    generate_go.sh
    generate_python.sh
  README.md

How Contract Changes Work

Every API change follows the same process:

Engineer proposes a change to banking.proto
          |
          raises a Pull Request in fintech-api-contracts
          |
Flutter team lead reviews:
  "Does this break our client? Do we need to update?"

Go backend lead reviews:
  "Is this implementable? Does it follow our conventions?"

React web lead reviews:
  "Does the web client need changes?"

Python data lead reviews:
  "Does this affect our data pipelines?"
          |
All teams approve
          |
PR merges — the change is now the law
          |
Every team runs their code generation script
          |
Builds fail where breaking changes exist
Changes are caught at compile time
Before any code reaches production

This process gives you something REST with documentation can never provide: guaranteed contract synchronization across every team, enforced by the compiler, before anything reaches users.

Building a Complete gRPC System with Dart and Flutter

Now let's put everything together in a complete, production-structured example.

Project Setup

Add the gRPC dependency to your Flutter project:

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  grpc: ^3.2.4
  protobuf: ^3.1.0

dev_dependencies:
  protoc_plugin: ^21.1.2

Install the protoc compiler and the Dart plugin:

# macOS
brew install protobuf

# Install the Dart protoc plugin
dart pub global activate protoc_plugin

Generate the Dart code from the proto file:

protoc \
  --dart_out=grpc:lib/generated \
  -I proto \
  proto/banking/banking.proto

The Data Source Layer

// lib/features/banking/data/datasources/banking_remote_datasource.dart

import 'package:grpc/grpc.dart';
import '../../../../generated/banking.pb.dart';
import '../../../../generated/banking.pbgrpc.dart';
import '../../../../core/error/app_exception.dart';

class BankingRemoteDataSource {
  late final BankingServiceClient _client;
  late final ClientChannel _channel;

  BankingRemoteDataSource({
    required String host,
    required int port,
    required String authToken,
  }) {
   
    _channel = ClientChannel(
      host,
      port: port,
      options: const ChannelOptions(
        credentials: ChannelCredentials.secure(),
        connectionTimeout: Duration(seconds: 10),
      ),
    );

   
    _client = BankingServiceClient(
      _channel,
      options: CallOptions(
        metadata: {'authorization': 'Bearer $authToken'},
        timeout: const Duration(seconds: 30),
      ),
    );
  }

  Future<LoginResponse> login(String email, String password) async {
    try {
      return await _client.login(
        LoginRequest(email: email, password: password),
      );
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  Future<UserProfile> getProfile(String userId) async {
    try {
      return await _client.getProfile(
        ProfileRequest(userId: userId),
      );
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  Stream<BalanceResponse> watchBalance(String userId) {
    return _client
        .watchBalance(BalanceRequest(userId: userId))
        .handleError((error) {
      if (error is GrpcError) throw _mapGrpcError(error);
      throw error;
    });
  }

  Stream<Transaction> streamTransactions(String userId, {int limit = 20}) {
    return _client
        .streamTransactions(
          TransactionRequest(userId: userId, limit: limit),
        )
        .handleError((error) {
      if (error is GrpcError) throw _mapGrpcError(error);
      throw error;
    });
  }

  Future<UploadResponse> uploadDocument(
    List<Uint8List> chunks,
    String documentType,
  ) async {
    try {
      Stream<DocumentChunk> chunkStream() async* {
        for (int i = 0; i < chunks.length; i++) {
          yield DocumentChunk(
            data: chunks[i],
            documentType: documentType,
            chunkIndex: i,
            isLast: i == chunks.length - 1,
          );
        }
      }
      return await _client.uploadDocument(chunkStream());
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  ResponseStream<ChatMessage> startChat(Stream<ChatMessage> outgoing) {
    return _client.chat(outgoing);
  }

  Future<void> dispose() async {
    await _channel.shutdown();
  }

  AppException _mapGrpcError(GrpcError error) {
    switch (error.code) {
      case StatusCode.unauthenticated:
        return AppException.unauthorized(
          message: error.message ?? 'Unauthorized',
        );
      case StatusCode.notFound:
        return AppException.notFound(
          message: error.message ?? 'Not found',
        );
      case StatusCode.deadlineExceeded:
        return AppException.timeout(message: 'Request timed out');
      case StatusCode.unavailable:
        return AppException.serverUnavailable(
          message: 'Service unavailable',
        );
      default:
        return AppException.unknown(
          message: error.message ?? 'Unknown error',
        );
    }
  }
}

Let's walk through the important decisions in this data source.

The Channel:

_channel = ClientChannel(
  host,
  port: port,
  options: const ChannelOptions(
    credentials: ChannelCredentials.secure(),
    connectionTimeout: Duration(seconds: 10),
  ),
);

The channel is the physical HTTP/2 connection to the server. You create it once and reuse it for every call. ChannelCredentials.secure() enables TLS encryption. connectionTimeout prevents the app from waiting indefinitely if the server is unreachable.

The channel is the core of gRPC's performance advantage. A single persistent channel multiplexes all requests through one HTTP/2 connection. Creating a new channel per request would eliminate this advantage entirely and perform worse than REST.

Authentication via Metadata:

_client = BankingServiceClient(
  _channel,
  options: CallOptions(
    metadata: {'authorization': 'Bearer $authToken'},
    timeout: const Duration(seconds: 30),
  ),
);

gRPC uses metadata (key-value pairs) for what HTTP uses headers. Passing the auth token as metadata on the CallOptions means every single call made through this client automatically includes the Authorization metadata. You write it once. It applies everywhere.

Error Mapping:

AppException _mapGrpcError(GrpcError error) {
  switch (error.code) {
    case StatusCode.unauthenticated:
      return AppException.unauthorized(...);
    case StatusCode.deadlineExceeded:
      return AppException.timeout(...);
    ...
  }
}

gRPC has its own set of status codes similar to HTTP status codes but not identical. Mapping them to your application's exception types at the data source layer means the rest of your code (use cases, notifiers, widgets) never deals with gRPC-specific errors directly. Your domain layer stays clean and framework-independent.

The Repository Layer

abstract class BankingRepository {
  Future<Result<UserProfile, AppException>> getProfile(String userId);
  Stream<BalanceResponse> watchBalance(String userId);
  Stream<Transaction> streamTransactions(String userId);
  Future<Result<UploadResponse, AppException>> uploadDocument(
    List<Uint8List> chunks,
    String documentType,
  );
}


class BankingRepositoryImpl implements BankingRepository {
  final BankingRemoteDataSource _dataSource;

  BankingRepositoryImpl(this._dataSource);

  @override
  Future<Result<UserProfile, AppException>> getProfile(String userId) async {
    try {
      final profile = await _dataSource.getProfile(userId);
      return Result.success(profile);
    } on AppException catch (e) {
      return Result.failure(e);
    }
  }

  @override
  Stream<BalanceResponse> watchBalance(String userId) {
    return _dataSource.watchBalance(userId);
  }

  @override
  Stream<Transaction> streamTransactions(String userId) {
    return _dataSource.streamTransactions(userId);
  }

  @override
  Future<Result<UploadResponse, AppException>> uploadDocument(
    List<Uint8List> chunks,
    String documentType,
  ) async {
    try {
      final response = await _dataSource.uploadDocument(chunks, documentType);
      return Result.success(response);
    } on AppException catch (e) {
      return Result.failure(e);
    }
  }
}

The Riverpod Providers

part 'banking_providers.g.dart';

@riverpod
Stream<BalanceResponse> balanceStream(BalanceStreamRef ref, String userId) {
  final repository = ref.watch(bankingRepositoryProvider);
  return repository.watchBalance(userId);
}

@riverpod
Stream<Transaction> transactionStream(
  TransactionStreamRef ref,
  String userId,
) {
  final repository = ref.watch(bankingRepositoryProvider);
  return repository.streamTransactions(userId);
}

With Riverpod, a provider that returns a Stream automatically becomes an AsyncValue that widgets can watch. Every new value pushed from the gRPC server stream triggers a widget rebuild automatically.

The UI

// lib/features/banking/presentation/pages/dashboard_page.dart
class DashboardPage extends ConsumerWidget {
  final String userId;

  const DashboardPage({required this.userId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final balanceAsync = ref.watch(balanceStreamProvider(userId));
    final transactionsAsync = ref.watch(transactionStreamProvider(userId));

    return Scaffold(
      appBar: AppBar(title: const Text('Dashboard')),
      body: Column(
        children: [
          balanceAsync.when(
            data: (balance) => BalanceCard(
              amount: balance.balance,
              currency: balance.currency,
            ),
            loading: () => const BalanceShimmer(),
            error: (e, _) => ErrorCard(message: e.toString()),
          ),

          const SizedBox(height: 24),

          Expanded(
            child: transactionsAsync.when(
              data: (transaction) => TransactionTile(
                transaction: transaction,
              ),
              loading: () => const TransactionShimmer(),
              error: (e, _) => ErrorCard(message: e.toString()),
            ),
          ),
        ],
      ),
    );
  }
}

Both the balance and transactions arrive through gRPC server streams. Both update in real-time as the server pushes new data. Both are handled identically through Riverpod's AsyncValue pattern. One framework with all patterns covered.

Production Concerns

Authentication with Interceptors

For more granular authentication control, such as refreshing an expired token and retrying automatically, you implement a client interceptor:

class AuthInterceptor extends ClientInterceptor {
  final TokenService _tokenService;

  AuthInterceptor(this._tokenService);

  @override
  ResponseFuture<R> interceptUnary<Q, R>(
    ClientMethod<Q, R> method,
    Q request,
    CallOptions options,
    ClientUnaryInvoker<Q, R> invoker,
  ) {
    final token = _tokenService.currentToken;
    final authenticatedOptions = options.mergedWith(
      CallOptions(metadata: {'authorization': 'Bearer $token'}),
    );
    return invoker(method, request, authenticatedOptions);
  }

  @override
  ResponseStream<R> interceptServerStreaming<Q, R>(
    ClientMethod<Q, R> method,
    Q request,
    CallOptions options,
    ClientServerStreamingInvoker<Q, R> invoker,
  ) {
    final token = _tokenService.currentToken;
    final authenticatedOptions = options.mergedWith(
      CallOptions(metadata: {'authorization': 'Bearer $token'}),
    );
    return invoker(method, request, authenticatedOptions);
  }
}

Pass the interceptor when creating the client:

_client = BankingServiceClient(
  _channel,
  interceptors: [AuthInterceptor(tokenService)],
);

The interceptor fires on every call automatically. The data source code never touches auth logic directly.

Error Handling: gRPC Status Codes

gRPC defines a standard set of status codes that every implementation follows:

AppException _mapGrpcError(GrpcError error) {
  switch (error.code) {
    case StatusCode.unauthenticated:
      return AppException.unauthorized(message: 'Session expired');
    case StatusCode.permissionDenied:
      return AppException.forbidden(message: 'Access denied');
    case StatusCode.notFound:
      return AppException.notFound(message: error.message ?? 'Not found');
    case StatusCode.deadlineExceeded:
      return AppException.timeout(message: 'Request timed out');
    case StatusCode.unavailable:
      return AppException.serverUnavailable(message: 'Service unavailable');
    case StatusCode.resourceExhausted:
      return AppException.rateLimited(message: 'Too many requests');
    case StatusCode.invalidArgument:
      return AppException.validation(
        message: error.message ?? 'Invalid input',
      );
    default:
      return AppException.unknown(
        message: error.message ?? 'An error occurred',
      );
  }
}

Deadlines and Timeouts

Every gRPC call should have a deadline. Without deadlines, a slow server can make your app hang indefinitely.

Per-call deadline:

Future<UserProfile> getProfile(String userId) async {
  return await _client.getProfile(
    ProfileRequest(userId: userId),
    options: CallOptions(timeout: const Duration(seconds: 10)),
  );
}

Default deadline for all calls:

_client = BankingServiceClient(
  _channel,
  options: CallOptions(
    timeout: const Duration(seconds: 30),
    metadata: {'authorization': 'Bearer $authToken'},
  ),
);

When the deadline is exceeded, the call throws a GrpcError with StatusCode.deadlineExceeded, which your error mapper handles appropriately.

Logging Interceptor

class LoggingInterceptor extends ClientInterceptor {
  @override
  ResponseFuture<R> interceptUnary<Q, R>(
    ClientMethod<Q, R> method,
    Q request,
    CallOptions options,
    ClientUnaryInvoker<Q, R> invoker,
  ) {
    final stopwatch = Stopwatch()..start();
    debugPrint('[gRPC] --> ${method.path}');

    final response = invoker(method, request, options);

    response.then((_) {
      stopwatch.stop();
      debugPrint(
        '[gRPC] <-- ${method.path} (${stopwatch.elapsedMilliseconds}ms)',
      );
    }).catchError((error) {
      stopwatch.stop();
      debugPrint(
        '[gRPC] ERROR ${method.path}: $error (${stopwatch.elapsedMilliseconds}ms)',
      );
    });

    return response;
  }
}

gRPC vs REST vs WebSockets: When to Use What

When to Use REST

The API is consumed by third-party developers or external partners. JSON over HTTP is the universal language that every developer in every language can access immediately without learning new tooling.

The operation is simple request-response with no streaming requirements and only one client platform. REST is simpler to implement, simpler to debug, and simpler to test for straightforward CRUD operations.

Public documentation and human readability matter. REST with OpenAPI/Swagger gives you browsable, testable documentation that developers can explore in a browser.

Caching is important. REST GET responses can be cached at every layer: CDN, reverse proxy, browser cache. gRPC requests can't leverage standard HTTP caching.

Use WebSockets When

You need true bidirectional real-time communication and gRPC isn't already in your stack. Chat applications, multiplayer games, and collaborative tools where both sides need to speak freely are natural WebSocket use cases.

Browser support without a proxy layer is required. WebSockets work natively in every modern browser. gRPC in the browser requires gRPC-Web and a proxy layer.

When to Use gRPC

Multiple platform teams share the same service contract. When Flutter, React, Go, and Python services all call the same backend, a .proto file enforced by the compiler prevents contract drift across every team.

Large payloads are called by many internal applications. The more fields in the payload and the more applications consuming it, the stronger the case for protobuf's binary encoding and generated clients.

Network conditions are variable and payload size matters. Users on 2G or 3G connections benefit directly from protobuf's compact binary format. The same data in protobuf can be 3 to 10 times smaller than JSON, translating to faster load times and lower data consumption for users on limited data plans.

Real-time streaming is required and you want one unified framework for all communication patterns. gRPC's four patterns cover every scenario without requiring a separate WebSocket server alongside your API.

Service-to-service communication at high frequency is involved. Two internal services calling each other thousands of times per second over a persistent multiplexed HTTP/2 connection with binary protobuf encoding will significantly outperform REST with JSON over HTTP/1.1.

The Hybrid Architecture

The mature engineering decision is not choosing gRPC over REST or REST over gRPC. It's knowing where each belongs and using both deliberately.

Most organizations of meaningful scale end up with a hybrid:

The public REST API serves external consumers who need simplicity and JSON. The internal gRPC network handles high-frequency, high-performance service-to-service calls. The mobile gRPC endpoints give Flutter clients real-time capabilities over efficient binary connections.

Each layer uses the right tool for its specific requirements. No ideological commitment to one protocol. Pure engineering pragmatism.

Conclusion

Remote Procedure Calls began with a simple observation: network communication shouldn't require developers to think about network communication. Calling a function on another machine should feel like calling a function on your own.

Protocol Buffers took this further by solving the data problem. JSON is readable but verbose. Binary encoding with a compiler-enforced schema produces payloads that are smaller, faster to parse, and guaranteed to match the contract every team agreed on. For users on slow networks and internal systems processing millions of requests daily, this efficiency is a business advantage.

gRPC combined RPC semantics, Protocol Buffer encoding, and HTTP/2 transport into a framework that supports four distinct communication patterns: unary request-response, server streaming, client streaming, and bidirectional streaming. All from the same generated client, using the same persistent connection, and enforced by the same .proto contract.

The organizational practice of a shared protobuf repository transforms gRPC from a technical tool into an engineering discipline. Contract changes go through review. Breaking changes are caught by the compiler. Every team generates their own strongly typed client from the same source of truth and stays in sync automatically, regardless of programming language.

In Flutter specifically, gRPC server streams integrate naturally with Dart's Stream type and Riverpod's stream providers. Real-time balance updates and live transaction feeds that would require polling with REST or a separate WebSocket implementation become simple stream subscriptions. The server pushes, the widget listens, and nothing else is required.

The decision of when to use gRPC versus REST versus WebSockets isn't about preference. It's about matching the tool to the requirement. Public APIs belong behind REST. High-frequency internal service communication belongs on gRPC. Large payloads consumed by many internal systems belong in protobuf. Real-time bidirectional features belong on gRPC streaming. Users on variable networks deserve the smallest payloads you can give them.

Understanding all of these tools, understanding why they exist, and knowing when to reach for each one is what separates engineers who use tools from engineers who think in systems.

Happy Coding!

A user logs in, and the app needs to save a token, cache the user profile, fire an analytics event, and navigate to the home screen.

A payment is confirmed, and the inventory needs to update, the user needs a receipt, and the fulfillment system needs to kick off delivery.

A sensor reading changes, and three different UI panels need to reflect the new value simultaneously.

The naïve solution is to write all of that logic in one place. One function that does everything or one class that knows about everything.

This works at first. Then requirements change. A new reaction needs to be added. An existing one needs to be removed. A side effect starts failing and takes everything else down with it. The code becomes a wall of responsibilities that's impossible to test, painful to extend, and dangerous to touch.

The Observer Design Pattern exists to solve exactly this problem. It gives you a structured, production-grade way to say: when this event happens, notify everyone who cares, without the event source knowing who those people are.

In this handbook, you'll learn the Observer pattern from first principles. You'll see how it's implemented in Dart, understand how it connects to Event-Driven Architecture, and discover how it integrates cleanly with Domain-Driven Design and Riverpod in a real Flutter application.

By the end, you won't just understand the pattern. You'll know how to use it deliberately in production code.

Table of Contents

• What is the Observer Design Pattern?

• The Problem It Solves

• Core Components

• Implementing Observer in Dart

• A Real-World Example: The Login Flow

• Making It Production-Grade with a Generic EventBus

• Observer Is Already in Your Flutter Code

• Deep Dive Into Event-Driven Architecture

• Application in Domain-Driven Design

• The Riverpod Hybrid: Clean Architecture in Practice

• Testing the Observer Architecture

• When to Use the Observer Pattern

• When Not to Use It

• Conclusion

What is the Observer Design Pattern?

The Observer pattern is a behavioural design pattern that defines a one-to-many dependency between objects. When one object changes state or fires an event, all of its dependents are notified and updated automatically.

Think of a newspaper subscription service. The newspaper publisher doesn't know who its individual subscribers are. It doesn't call each reader personally. It publishes the paper, and every subscriber who signed up receives it.

A subscriber can cancel at any time. A new subscriber can join at any time. The publisher's job never changes. It just publishes.

That's the Observer pattern in plain terms.

The publisher is called the Subject. The subscribers are called Observers. The newspaper is the event.

The pattern was formally defined in the Gang of Four book, Design Patterns: Elements of Reusable Object-Oriented Software. It remains one of the most widely used patterns in software engineering, especially in reactive and event-driven systems.

The Problem It Solves

Let's look at what happens without the Observer pattern.

Say you have a login feature. When login succeeds, you need to do four things:

• Save the authentication token to secure storage

• Cache the user profile data

• Navigate to the home screen

• Fire an analytics event

The straightforward approach puts all of this inside the login function:

Future<void> login(String email, String password) async {
  final response = await _authRepository.login(email, password);

  await _secureStorage.write(key: 'token', value: response.token);
  await _userCache.save(response.user);
  _navigationService.navigateTo('/home');
  _analytics.track('login_success', {'userId': response.user.id});
}

This looks fine at first glance. But count how many reasons this single function has to change:

• The token storage strategy changes. You modify this function.

• The navigation destination changes. You modify this function.

• The analytics event name or payload changes. You modify this function.

• The user caching logic changes. You modify this function.

Every single change to any of these four concerns forces you back into this one function. And every time you touch it, you risk breaking all the other three things it's doing.

Now imagine you need to add a fifth thing, such as enrolling the user in push notifications. You open this function again. You add more code. The function grows. Testing it requires mocking four, then five different dependencies. New teammates struggle to understand what this function is actually responsible for. The answer, of course, is everything. And that's the problem.

This is called tight coupling. The login logic is coupled to every single consequence of a successful login.

The Observer pattern breaks these couplings completely. The login logic does one thing: it performs the login and announces the result. Every consequence is handled by a separate, independent observer. Each observer has one job. None of them know about each other. The login logic doesn't know they exist.

Core Components

The Observer pattern has four core building blocks. Understanding each one before writing code makes the implementation much easier to follow.

Subject

The Subject is the object that something happens to. It holds a list of observers and is responsible for notifying them when an event occurs. It exposes methods for observers to register and unregister themselves. The Subject doesn't care what observers do with the notification. It just delivers it.

Observer

The Observer is an interface or abstract class that defines the contract all observers must follow. It declares the method or methods the Subject will call when notifying. Any class that wants to react to an event must implement this interface.

Concrete Subject

The Concrete Subject is the real implementation of the Subject. It manages the actual list of observers, handles subscriptions, and fires notifications at the right moment.

Concrete Observers

These are the real classes that implement the Observer interface. Each one has a specific, focused job to do when notified. One saves the token. One navigates. One fires analytics. They don't know about each other and don't need to.

Here's how they relate to each other:

Subject (LoginService)
    |
    |-- subscribe(observer)    <- observer registers itself
    |-- unsubscribe(observer)  <- observer removes itself
    |-- notifySuccess(data)    <- fires when login succeeds
    |-- notifyFailure(error)   <- fires when login fails
         |
         |-----> TokenObserver.onLoginSuccess()
         |-----> UserObserver.onLoginSuccess()
         |-----> NavigationObserver.onLoginSuccess()
         |-----> AnalyticsObserver.onLoginSuccess()

The Subject notifies all of them. They each handle their own job independently.

Implementing Observer in Dart

Let's build the pattern step by step.

Step 1: Define the Observer Interface

abstract class LoginObserver {
  void onLoginSuccess(UserDto user);
  void onLoginFailed(AppException error);
}

This is the contract that every observer must sign. Any class that wants to react to login events must implement both of these methods.

onLoginSuccess is called when the login succeeds and receives the user data. onLoginFailed is called when the login fails and receives the error.

Step 2: Define the Subject Interface

abstract class LoginSubject {
  void subscribe(LoginObserver observer);
  void unsubscribe(LoginObserver observer);
  void notifySuccess(UserDto user);
  void notifyFailure(AppException error);
}

subscribe lets an observer join the notification list. unsubscribe lets an observer leave the notification list. notifySuccess broadcasts a success event with the user data to all registered observers. notifyFailure broadcasts a failure event with the error to all registered observers.

Defining this as an abstract class instead of going straight to a concrete class is important. It means anything that depends on the subject depends on the abstraction, not the implementation. This makes your code testable and swappable.

Step 3: Implement the Concrete Subject

class LoginService implements LoginSubject {
  final List<LoginObserver> _observers = [];

  @override
  void subscribe(LoginObserver observer) {
    _observers.add(observer);
  }

  @override
  void unsubscribe(LoginObserver observer) {
    _observers.remove(observer);
  }

  @override
  void notifySuccess(UserDto user) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onLoginSuccess(user);
      } catch (e) {
        debugPrint('Observer error on success: $e');
      }
    }
  }

  @override
  void notifyFailure(AppException error) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onLoginFailed(error);
      } catch (e) {
        debugPrint('Observer error on failure: $e');
      }
    }
  }
}

There are two important decisions in this implementation that are easy to miss.

1. Snapshot iteration with List.of()

Instead of iterating directly over _observers, we iterate over List.of(_observers), which creates a copy of the list before the loop runs.

Why does this matter? Imagine a NavigationObserver that, after navigating to the home screen, unsubscribes itself because it no longer needs to listen. If it calls unsubscribe while the notifySuccess loop is still running over the same list, Dart throws a ConcurrentModificationError. The list is being modified while it's being read.

List.of() prevents this entirely. The loop runs over the snapshot. The original list can be modified freely during iteration without any errors.

2. Per-observer try/catch

Each observer call is wrapped in its own try/catch block. This is a deliberate choice. If TokenObserver throws an exception while writing to secure storage, you don't want NavigationObserver and AnalyticsObserver to silently never fire. Each observer gets its chance to run regardless of what the others do.

Without this, one failing observer would stop the entire notification chain. That's a hidden bug that's extremely difficult to trace in production.

A Real-World Example: The Login Flow

Now let's build the full login flow using this foundation.

The Login Logic

class LoginLogic {
  final LoginSubject _subject;
  final AuthRepository _repository;

  LoginLogic({
    required LoginSubject subject,
    required AuthRepository repository,
  })  : _subject = subject,
        _repository = repository;

  Future<void> callLogin(LoginRequest request) async {
    try {
      final user = await _repository.login(request);
      _subject.notifySuccess(user);
    } on AppException catch (e) {
      _subject.notifyFailure(e);
    } catch (e) {
      _subject.notifyFailure(AppException.unknown(message: e.toString()));
    }
  }
}

Let's walk through this carefully.

LoginLogic takes two dependencies through its constructor: a LoginSubject and an AuthRepository. Notice it takes LoginSubject, the abstraction, not LoginService, the concrete class. This means you can swap the implementation in tests or in different environments without changing LoginLogic at all.

Inside callLogin, the logic is straightforward. It calls the repository to perform the actual login. If that succeeds, it calls notifySuccess on the subject with the returned user. If it throws an AppException, it calls notifyFailure with that error. If it throws anything unexpected, it wraps it in an AppException.unknown and notifies failure.

Notice what LoginLogic does NOT do. It doesn't save a token. It doesn't navigate anywhere. It doesn't cache anything. It doesn't fire analytics. And it doesn't know how many observers exist or what they do.

Its entire responsibility is: perform the login, announce the result.

The Concrete Observers

class TokenObserver implements LoginObserver {
  final SecureStorageService _storage;

  TokenObserver(this._storage);

  @override
  void onLoginSuccess(UserDto user) {
    _storage.write(key: 'auth_token', value: user.token);
  }

  @override
  void onLoginFailed(AppException error) {
    _storage.delete(key: 'auth_token');
  }
}

TokenObserver has one job: manage the authentication token. On success, it saves the token. On failure, it clears any stale token that might be sitting in storage. It knows nothing about navigation, caching, or analytics.

class UserObserver implements LoginObserver {
  final UserCacheService _cache;

  UserObserver(this._cache);

  @override
  void onLoginSuccess(UserDto user) {
    _cache.save(user);
  }

  @override
  void onLoginFailed(AppException error) {
    _cache.clear();
  }
}

UserObserver has one job: manage the user cache. On success, it saves the user profile. On failure, it clears the cache. It knows nothing about tokens, navigation, or analytics.

class NavigationObserver implements LoginObserver {
  final NavigationService _navigation;

  NavigationObserver(this._navigation);

  @override
  void onLoginSuccess(UserDto user) {
    _navigation.navigateTo('/home');
  }

  @override
  void onLoginFailed(AppException error) {
    _navigation.showError(error.message);
  }
}

NavigationObserver has one job: handle navigation after a login attempt. It uses an injected NavigationService abstraction rather than a BuildContext. This is intentional. An observer that depends on BuildContext is tied to the widget lifecycle. Using an abstraction keeps this observer completely independent of the UI layer.

class AnalyticsObserver implements LoginObserver {
  final AnalyticsService _analytics;

  AnalyticsObserver(this._analytics);

  @override
  void onLoginSuccess(UserDto user) {
    _analytics.track('login_success', {'userId': user.id});
  }

  @override
  void onLoginFailed(AppException error) {
    _analytics.track('login_failed', {'reason': error.message});
  }
}

AnalyticsObserver has one job: fire the right analytics event for each outcome. It has no knowledge of storage, navigation, or caching.

Each observer has exactly one responsibility. Each one has exactly one reason to change. When the analytics payload needs to change, you touch only AnalyticsObserver. When navigation logic changes, you touch only NavigationObserver. Nothing else is affected.

Wiring It Together

void setupLogin() {
  final service = LoginService();

  service
    ..subscribe(TokenObserver(secureStorage))
    ..subscribe(UserObserver(userCache))
    ..subscribe(NavigationObserver(navigationService))
    ..subscribe(AnalyticsObserver(analyticsService));

  final loginLogic = LoginLogic(
    subject: service,
    repository: authRepository,
  );
}

This is the composition step. All observers are created with their dependencies and registered onto the service. The cascade operator .. calls subscribe multiple times on the same service object, which keeps the setup readable.

LoginLogic receives the service as its LoginSubject. From this point forward, every time callLogin is called and an outcome occurs, all four observers are notified automatically.

Adding a fifth observer, say a PushNotificationObserver, means creating the class and adding one line here: ..subscribe(PushNotificationObserver(pushService)). Nothing else in the entire codebase changes.

Making It Production-Grade with a Generic EventBus

The login example above works well, but it's specific to login. In a real application, many features have the same fan-out requirement. Payment confirmed, order placed, profile updated, session expired. All of them need one event to trigger multiple independent reactions.

Rewriting the Subject and Observer interfaces per feature is repetitive and unnecessary. The better approach is a generic EventBus that any feature can use.

abstract class DomainObserver<T> {
  void onSuccess(T data);
  void onFailure(AppException error);
}

DomainObserver<T> is a generic observer. The type parameter T represents the data type the observer expects on success. A login observer would be DomainObserver<UserDto>. A payment observer would be DomainObserver<PaymentDto>. The interface is the same. The data type changes per feature.

class EventBus<T> {
  final List<DomainObserver<T>> _observers = [];

  void subscribe(DomainObserver<T> observer) {
    _observers.add(observer);
  }

  void unsubscribe(DomainObserver<T> observer) {
    _observers.remove(observer);
  }

  void publishSuccess(T data) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onSuccess(data);
      } catch (e) {
        debugPrint('[EventBus] Observer error on success: $e');
      }
    }
  }

  void publishFailure(AppException error) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onFailure(error);
      } catch (e) {
        debugPrint('[EventBus] Observer error on failure: $e');
      }
    }
  }
}

EventBus<T> is a generic subject. It manages a list of typed observers and notifies them with the same snapshot iteration and per-observer error isolation we established earlier.

Now every feature gets the same infrastructure without duplicating a single line of the pattern:

final loginBus = EventBus<UserDto>();
final paymentBus = EventBus<PaymentDto>();
final orderBus = EventBus<OrderDto>();

Each bus is typed to its domain concept. Observers registered on loginBus will never accidentally receive payment events. The type system enforces correctness.

Observer Is Already in Your Flutter Code

Before going further into architecture, here's something worth pausing on. You've been using the Observer pattern all along without calling it by that name.

Streams and StreamController:

final controller = StreamController<String>();

controller.stream.listen((event) {
  print('Observed: $event');
});

controller.sink.add('Login succeeded');

StreamController is a Subject. stream.listen is subscribe. sink.add is notifyObservers. Every stream subscription is an Observer. The pattern is identical. Flutter just gave it different names.

ChangeNotifier:

class CounterModel extends ChangeNotifier {
  int _count = 0;

  void increment() {
    _count++;
    notifyListeners();
  }
}

notifyListeners() iterates over every registered listener and calls them. Those listeners are Observers. addListener is subscribe. removeListener is unsubscribe. ChangeNotifier is a concrete Subject.

BLoC:

When a BLoC emits a new state, every widget that wrapped itself in a BlocBuilder or BlocListener reacts. The BLoC is the Subject. The builders and listeners are Observers. The state emission is the notification.

Flutter's entire reactive system (Streams, ChangeNotifier, BLoC, ValueNotifier) is the Observer pattern with lifecycle management built in. Understanding the pattern at this fundamental level means you understand why all of these tools work the way they do. You aren't just using them. You understand them.

Deep Dive Into Event-Driven Architecture

Understanding Observer at the class level is the foundation. The pattern becomes significantly more powerful when applied at the architectural level, and that's where Event-Driven Architecture comes in.

What is Event-Driven Architecture?

Event-Driven Architecture is a design paradigm where the flow of the application is determined by events. Instead of components calling each other directly, they communicate by producing and consuming events through a shared bus or channel.

In a traditional request-driven flow, this is what happens:

Component A calls Component B directly
Component B does its work and returns a result
Component A waits for that result and then continues

Component A knows about Component B. It depends on it by name. It waits for it to finish. If you want Component C to also react to whatever Component A is doing, you have to go back into Component A and add that call.

But then Component A grows. Component A becomes responsible for orchestrating consequences it should know nothing about.

In an event-driven flow, this is what happens instead:

Component A publishes an event to the EventBus
EventBus delivers the event to whoever is registered

Component B handles the event
Component C handles the event
Component D handles the event

Component A doesn't know about B, C, or D. It doesn't wait for them. It publishes what happened and moves on. New handlers can be added without touching Component A at all. This is the Observer pattern scaled to the architectural level.

Events Are Facts, Not Commands

This distinction is one of the most important concepts in Event-Driven Architecture.

A command says: "do this." It's an instruction that can be rejected. It expects a response.

An event says: "this happened." It's an immutable record of a fact. It doesn't expect a response. It doesn't care who handles it.

SaveUserToken is a command. UserLoggedIn is an event.

When you model your system with events as facts, you get a historical record of everything that happened in your application. You can replay events to reconstruct state. You can add new handlers that process historical events. Your system becomes auditable and predictable in ways that command-driven systems are not.

Modelling Domain Events in Dart

Events should be immutable value objects. They're facts. Facts don't change after they happen.

abstract class DomainEvent {
  final DateTime occurredAt;
  final String eventId;

  const DomainEvent({
    required this.occurredAt,
    required this.eventId,
  });
}

DomainEvent is the base class for all events in the system. Every event has a timestamp (occurredAt) recording when it happened, and a unique identifier (eventId) for traceability.

class UserLoggedIn extends DomainEvent {
  final UserDto user;

  const UserLoggedIn({
    required this.user,
    required super.occurredAt,
    required super.eventId,
  });
}

class LoginFailed extends DomainEvent {
  final AppException error;

  const LoginFailed({
    required this.error,
    required super.occurredAt,
    required super.eventId,
  });
}

UserLoggedIn carries the user data. LoginFailed carries the error. Both are immutable. Both have timestamps and identifiers. Both are concrete facts about something that happened in the domain.

A Type-Safe DomainEventBus

Now we can build an event bus that's typed to domain events specifically:

abstract class EventHandler<T extends DomainEvent> {
  void handle(T event);
}

EventHandler<T> is the Observer interface for this architecture. Any class that wants to handle a domain event implements this with the specific event type it cares about.

class DomainEventBus {
  final _handlers = <Type, List<EventHandler>>{};

  void register<T extends DomainEvent>(EventHandler<T> handler) {
    _handlers.putIfAbsent(T, () => []).add(handler);
  }

  void publish<T extends DomainEvent>(T event) {
    final handlers = List.of(_handlers[T] ?? []);
    for (final handler in handlers) {
      try {
        (handler as EventHandler<T>).handle(event);
      } catch (e) {
        debugPrint('[DomainEventBus] Handler error for ${T}: $e');
      }
    }
  }
}

Let's go through DomainEventBus carefully.

_handlers is a map where the key is a Type (the event class itself, like UserLoggedIn) and the value is a list of all handlers registered for that event type.

register<T> takes a handler and adds it to the list for type T. putIfAbsent ensures the list is created if this is the first handler for that event type.

publish<T> looks up all handlers registered for the type of event being published and calls each one's handle method. The snapshot with List.of() and the per-handler try/catch are both present for the same reasons we established earlier.

Here's how you register handlers and publish events:

// Registration happens once at startup
eventBus.register<UserLoggedIn>(TokenHandler(secureStorage));
eventBus.register<UserLoggedIn>(UserCacheHandler(userCache));
eventBus.register<UserLoggedIn>(NavigationHandler(navigationService));
eventBus.register<UserLoggedIn>(AnalyticsHandler(analyticsService));

eventBus.register<PaymentConfirmed>(ReceiptHandler(receiptService));
eventBus.register<PaymentConfirmed>(InventoryHandler(inventoryService));

// Publishing happens at the use case level
eventBus.publish(UserLoggedIn(
  user: user,
  occurredAt: DateTime.now(),
  eventId: const Uuid().v4(),
));

When UserLoggedIn is published, only its registered handlers fire. Payment handlers aren't touched. Every handler for UserLoggedIn runs independently with full error isolation.

Application in Domain-Driven Design

Event-Driven Architecture and the Observer pattern find their most structured home inside Domain-Driven Design. DDD gives us the vocabulary and structure to know exactly where events belong, who creates them, and who handles them.

Key DDD Concepts You Need to Know

Domain Events are first-class citizens in DDD. They represent something meaningful that happened in the business domain. Not a technical detail, not an HTTP response, but a business fact.

UserLoggedIn is a domain event. LoginResponseDto is a data transfer object. The distinction matters deeply. The event belongs to the domain model and expresses business language. The DTO belongs to the data layer and expresses data structure.

Aggregates are the natural source of domain events. An Aggregate is a cluster of domain objects that form a consistency boundary. The Aggregate enforces business rules and raises domain events when significant state changes occur within it.

Use Cases are the orchestrators. A use case calls the repository, gets the result, raises the appropriate domain event, and returns the outcome. It doesn't handle side effects directly. It announces what happened and lets the registered handlers take over.

Where Everything Lives in Clean Architecture

lib/
  core/
    events/
      domain_event.dart           <- Base DomainEvent class
      domain_event_bus.dart       <- The DomainEventBus
      event_handler.dart          <- Base EventHandler interface

  features/
    auth/
      domain/
        events/
          user_logged_in.dart     <- Domain event (pure Dart, no Flutter)
          login_failed.dart       <- Domain event
        handlers/
          token_handler.dart      <- Handles token storage
          user_cache_handler.dart <- Handles user caching
          analytics_handler.dart  <- Handles analytics
        entities/
          user.dart
        repositories/
          auth_repository.dart    <- Abstract interface only
        usecases/
          login_usecase.dart      <- Orchestrates, publishes events

      data/
        repositories/
          auth_repository_impl.dart
        datasources/
          auth_remote_datasource.dart

      presentation/
        providers/
          login_provider.dart     <- Riverpod notifier (thin)
        pages/
          login_page.dart

The critical rule: the domain layer is pure Dart. No Flutter imports. No Riverpod imports. No HTTP imports. The DomainEventBus, domain events, handlers, and use cases all live in the domain layer and have zero framework dependencies.

This means that the same domain logic works in Flutter, server-side Dart, or a CLI tool without changing a single line. Framework upgrades, say from Riverpod 2.x to a future version, never touch the domain. Unit tests for the domain run in milliseconds with no widget test overhead.

The Login Use Case in DDD

class LoginUseCase {
  final AuthRepository _repository;
  final DomainEventBus _eventBus;

  LoginUseCase({
    required AuthRepository repository,
    required DomainEventBus eventBus,
  })  : _repository = repository,
        _eventBus = eventBus;

  Future<Result<UserDto, AppException>> execute(LoginRequest request) async {
    try {
      final user = await _repository.login(request);

      _eventBus.publish(UserLoggedIn(
        user: user,
        occurredAt: DateTime.now(),
        eventId: const Uuid().v4(),
      ));

      return Result.success(user);
    } on AppException catch (e) {
      _eventBus.publish(LoginFailed(
        error: e,
        occurredAt: DateTime.now(),
        eventId: const Uuid().v4(),
      ));

      return Result.failure(e);
    }
  }
}

Let's walk through this step by step.

LoginUseCase receives two dependencies: an AuthRepository abstraction and a DomainEventBus. Neither is a concrete class. Both can be swapped in tests.

Inside execute, it calls the repository to perform the login. If the login succeeds, it publishes a UserLoggedIn event to the bus, which immediately notifies all registered handlers. Then it returns a Result.success wrapping the user data.

If an AppException is caught, it publishes a LoginFailed event to the bus, which notifies all failure handlers. Then it returns a Result.failure wrapping the error.

The use case doesn't know how many handlers are registered. It doesn't know what they do. It performs the operation, publishes the outcome as a domain event, and returns the result.

The Result type is a return value for the caller (the Riverpod notifier) to know the outcome. The domain event is the broadcast for all side effect handlers. Both travel from the same single use case call. This is what makes the architecture clean.

The Riverpod Hybrid: Clean Architecture in Practice

This is where everything comes together in a real Flutter application.

The Problem We Are Solving

There are two common pain points in Flutter apps that use Riverpod:

Fat ref.listen in widgets:

// This is messy
ref.listen<AsyncValue<UserDto?>>(loginProvider, (previous, next) {
  next.whenData((user) {
    if (user != null) {
      secureStorage.write(key: 'token', value: user.token);
      userCache.save(user);
      context.go('/home');
      analytics.track('login_success');
    }
  });
});

The widget is mounted. If it unmounts before all of this completes, some side effects may never run. Business consequences like token storage and navigation shouldn't depend on whether a widget is still alive. This is fragile architecture.

Fat notifiers:

// Notifier doing too much
Future<void> login(LoginRequest request) async {
  state = const AsyncLoading();
  try {
    final user = await _loginUseCase.execute(request);
    await _secureStorage.write(key: 'token', value: user.token);
    await _userCache.save(user);
    _navigationService.navigateTo('/home');
    _analytics.track('login_success');
    state = AsyncData(user);
  } catch (e, st) {
    state = AsyncError(e, st);
  }
}

The notifier is violating the Single Responsibility Principle. It's performing the login, saving the token, caching the user, navigating, tracking analytics, and managing UI state. That's six responsibilities in one class. It's impossible to test cleanly and painful to maintain.

The Clean Rule

Before looking at the solution, establish this rule clearly:

The use case owns domain consequences. The notifier owns UI state. Widgets own nothing.

The use case performs the operation and publishes domain events. Handlers fire when those events are published and run completely independently of the widget lifecycle. The notifier receives the result from the use case and emits loading, success, or error state so the UI knows what to display. Widgets read that state and render accordingly.

That's the full picture. And it means this architecture works correctly whether login is triggered from a widget, a biometric prompt, a deep link, or a background service. The use case always publishes. The handlers always fire. The notifier only deals with UI state.

Understanding AsyncNotifier

Before writing the notifier, let's understand what AsyncNotifier is and how it works.

AsyncNotifier is a Riverpod 2.0 class designed specifically for asynchronous state. It holds an AsyncValue<T>, which is a sealed type that can be one of three things:

AsyncData<T> means the operation succeeded and data is available. AsyncLoading means an operation is in progress. AsyncError means an operation failed.

When you extend AsyncNotifier<T>, you implement a build method that returns the initial state, and you write methods that mutate state as async operations progress.

With code generation using @riverpod, you annotate your class and run flutter pub run build_runner build. The generator creates the provider and all the boilerplate automatically. You focus entirely on the logic.

Here's the full setup for code generation:

# pubspec.yaml
dependencies:
  flutter_riverpod: ^2.5.1
  riverpod_annotation: ^2.3.5

dev_dependencies:
  riverpod_generator: ^2.4.0
  build_runner: ^2.4.9

The Thin Notifier

// login_provider.dart
part 'login_provider.g.dart';

@riverpod
class LoginNotifier extends _$LoginNotifier {

  @override
  AsyncValue<UserDto?> build() {
    return const AsyncData(null);
  }

  Future<void> login(LoginRequest request) async {
    state = const AsyncLoading();

    final result = await ref.read(loginUseCaseProvider).execute(request);

    result.fold(
      onSuccess: (user) => state = AsyncData(user),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

Let's go through this line by line.

part 'login_provider.g.dart' tells Dart that the generated file is part of this library. The @riverpod annotation and _$LoginNotifier base class come from the generated file.

build() is the initialisation method. It runs when the provider is first read. It returns AsyncData(null), meaning the initial state is a successful state with no user yet. This is correct because no login has been attempted.

Inside login, the first thing we do is set state = const AsyncLoading(). This immediately notifies any widget watching this provider that an operation is in progress. The UI can show a loading indicator.

We then call the use case and await its result. The use case returns a Result<UserDto, AppException>, which is a type that holds either a success value or a failure value, never both. We call fold on it to handle each case.

In the onSuccess branch, we set state = AsyncData(user). This tells the UI the operation succeeded and here is the user data to render.

In the onFailure branch, we set state = AsyncError(error, StackTrace.current). This tells the UI something went wrong so it can display the appropriate error state.

That's the entire notifier. It does exactly one thing: reflect the outcome of the use case as UI state.

Notice there's no token saving here. No navigation, caching, or analytics. All of that is already handled. The moment the use case called _eventBus.publish(UserLoggedIn(...)) inside execute, every registered handler fired automatically. By the time result is returned to this notifier, all side effects are already done. The notifier just needs to update the UI.

This is the cleanest possible separation. The use case owns domain consequences. The notifier owns render state. Each has exactly one responsibility.

The Widget

class LoginPage extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final loginState = ref.watch(loginNotifierProvider);

    return Scaffold(
      body: loginState.when(
        data: (_) => const LoginForm(),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => ErrorView(message: error.toString()),
      ),
    );
  }
}

class LoginForm extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: () {
            ref.read(loginNotifierProvider.notifier).login(
              LoginRequest(email: 'user@example.com', password: 'secret'),
            );
          },
          child: const Text('Login'),
        ),
      ],
    );
  }
}

ref.watch(loginNotifierProvider) subscribes this widget to the notifier's state. Every time state changes inside the notifier, build is called again and the widget re-renders.

loginState.when is how you handle each case of AsyncValue. When the state is AsyncData, it renders the login form. When it is AsyncLoading, it renders a loading indicator. When it is AsyncError, it renders the error view.

The widget knows nothing about tokens, navigation, or caching. It renders what it's told to render by the state. That's its entire job.

Wiring the Composition Root

All handler registrations happen once at app startup inside a Riverpod provider:

@riverpod
DomainEventBus eventBus(EventBusRef ref) {
  final bus = DomainEventBus();

  bus.register<UserLoggedIn>(
    TokenHandler(ref.read(secureStorageProvider)),
  );
  bus.register<UserLoggedIn>(
    UserCacheHandler(ref.read(userCacheProvider)),
  );
  bus.register<UserLoggedIn>(
    NavigationHandler(ref.read(navigationServiceProvider)),
  );
  bus.register<UserLoggedIn>(
    AnalyticsHandler(ref.read(analyticsServiceProvider)),
  );

  bus.register<LoginFailed>(
    AnalyticsFailureHandler(ref.read(analyticsServiceProvider)),
  );

  return bus;
}

eventBus is a provider that creates the DomainEventBus and registers all handlers at the moment it is first read. Because Riverpod providers are lazy by default and cached after first creation, this runs once and the bus lives for the entire app session.

Every handler gets its dependencies injected via ref.read. Nothing is hardcoded. Everything is swappable in tests.

The LoginUseCase receives this event bus as a dependency through its own provider:

@riverpod
LoginUseCase loginUseCase(LoginUseCaseRef ref) {
  return LoginUseCase(
    repository: ref.read(authRepositoryProvider),
    eventBus: ref.read(eventBusProvider),
  );
}

This is the only place that connects the use case to the event bus. The notifier receives only the use case. The widget receives only the notifier's state. Each layer knows only about the layer directly below it and nothing else.

Adding a new side effect to login means creating a new handler class and adding one bus.register line in the composition root. The notifier, the use case logic, the widget, and every existing handler remain completely untouched.

Testing the Observer Architecture

One of the most significant advantages of this architecture is how clearly it separates test concerns. Each layer has its own focused test scope.

Testing the Use Case

void main() {
  group('LoginUseCase', () {
    late LoginUseCase useCase;
    late MockAuthRepository mockRepository;
    late MockDomainEventBus mockEventBus;

    setUp(() {
      mockRepository = MockAuthRepository();
      mockEventBus = MockDomainEventBus();
      useCase = LoginUseCase(
        repository: mockRepository,
        eventBus: mockEventBus,
      );
    });

    test('publishes UserLoggedIn event on success', () async {
      final user = UserDto(id: '1', token: 'token123');
      when(() => mockRepository.login(any())).thenAnswer((_) async => user);

      await useCase.execute(LoginRequest(email: 'a@b.com', password: '123'));

      verify(() => mockEventBus.publish(any<UserLoggedIn>())).called(1);
    });

    test('publishes LoginFailed event on error', () async {
      when(() => mockRepository.login(any()))
          .thenThrow(AppException.unauthorized(message: 'Invalid credentials'));

      await useCase.execute(LoginRequest(email: 'a@b.com', password: 'wrong'));

      verify(() => mockEventBus.publish(any<LoginFailed>())).called(1);
    });
  });
}

The use case test mocks the repository and the event bus. It verifies that the correct event type was published for each outcome. It doesn't test what any handler does. That's not the use case's responsibility, so it's not the use case's test.

Testing Each Handler

void main() {
  group('TokenHandler', () {
    late TokenHandler handler;
    late MockSecureStorageService mockStorage;

    setUp(() {
      mockStorage = MockSecureStorageService();
      handler = TokenHandler(mockStorage);
    });

    test('writes token to secure storage on UserLoggedIn', () {
      final event = UserLoggedIn(
        user: UserDto(id: '1', token: 'abc123'),
        occurredAt: DateTime.now(),
        eventId: 'event-1',
      );

      handler.handle(event);

      verify(
        () => mockStorage.write(key: 'auth_token', value: 'abc123'),
      ).called(1);
    });
  });
}

Each handler test is tiny. It creates the handler with a mocked dependency, fires the event, and verifies the exact side effect that handler is responsible for. No other handler is involved, no notifier is involved, and no widget is involved.

Testing the Notifier

void main() {
  group('LoginNotifier', () {
    test('transitions from loading to data on success', () async {
      final mockUseCase = MockLoginUseCase();
      final user = UserDto(id: '1', token: 'token123');

      when(() => mockUseCase.execute(any()))
          .thenAnswer((_) async => Result.success(user));

      final container = ProviderContainer(overrides: [
        loginUseCaseProvider.overrideWithValue(mockUseCase),
      ]);

      final notifier = container.read(loginNotifierProvider.notifier);

      await notifier.login(LoginRequest(email: 'a@b.com', password: '123'));

      expect(
        container.read(loginNotifierProvider),
        isA<AsyncData<UserDto?>>(),
      );
    });

    test('transitions from loading to error on failure', () async {
      final mockUseCase = MockLoginUseCase();
      final error = AppException.unauthorized(message: 'Invalid credentials');

      when(() => mockUseCase.execute(any()))
          .thenAnswer((_) async => Result.failure(error));

      final container = ProviderContainer(overrides: [
        loginUseCaseProvider.overrideWithValue(mockUseCase),
      ]);

      final notifier = container.read(loginNotifierProvider.notifier);

      await notifier.login(LoginRequest(email: 'a@b.com', password: 'wrong'));

      expect(
        container.read(loginNotifierProvider),
        isA<AsyncError>(),
      );
    });
  });
}

The notifier test only verifies state transitions. It doesn't need to mock the event bus because the notifier no longer touches the event bus. That's the use case's job, and the use case has its own test that verifies events are published correctly. Each layer is tested in complete isolation with no overlap.

When to Use the Observer Pattern

Use Observer when:

• One event needs to trigger multiple independent reactions

• You want to add or remove reactions without modifying the event source

• Side effects need to be decoupled from business logic

• Each reaction should be independently testable

• Multiple parts of the system need to react to the same state change

• You are building a feature that will grow in number of side effects over time

When Not to Use It

Avoid Observer when:

• You have only one consumer and no realistic expectation of more

• The relationship between producer and consumer is simple and direct

• The pattern adds structural overhead without meaningful benefit

• Streams, ChangeNotifier, or Riverpod's built-in reactivity already solve the problem naturally

• Strict ordering of side effects is critical and fan-out makes that hard to guarantee

Conclusion

The Observer Design Pattern is one of the most important tools in a software engineer's arsenal. This isn't because it's clever, but because it solves a problem every growing application faces: how do you let one event trigger many reactions without turning your codebase into a tightly coupled mess?

You started by understanding the pattern at its core. A Subject holds a list of Observers and notifies them when events occur. You saw it built step by step in Dart, with snapshot iteration to prevent concurrent modification errors, per-observer try/catch to prevent failure cascades, and dependency inversion to keep everything testable.

You discovered that the Observer pattern is already embedded in Flutter's Streams, ChangeNotifier, and BLoC. Understanding its foundations means you understand why those tools work the way they do.

You then took the pattern into Event-Driven Architecture, where events become immutable domain facts and the system is composed of producers and consumers with no direct coupling between them.

You applied it inside Domain-Driven Design, giving events a proper home in a pure Dart domain layer that is framework-independent, fully portable, and fully testable.

And you saw how it integrates with Riverpod through a hybrid architecture with a clear and enforced rule: handlers own side effects, the notifier owns UI state, and widgets own nothing.

The result is a codebase that scales gracefully. When a new side effect needs to be added, you create one handler and register it in one place. Nothing else changes. That's the promise of the Observer pattern. And as you've seen throughout this handbook, it's a promise it keeps.

Happy Coding!