Microservice architecture

GenAI-based development platform - part 3: Announcing Isolarium, three flavors of secure sandboxes for GenAI-based coding agents

Thu, 26 Mar 2026 08:03:00 +0000

I’m pleased to announce that I’ve open-sourced Isolarium, a companion project to Idea to Code workflow that provides secure sandboxes for running GenAI-based coding agents like Claude Code.

This article is part of a series about the GenAI-based development platform (a.k.a. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive, more secure and less frustrating. The complete list of articles in the series is as follows:

In this article, I first describe the risks of running coding agents on a developer workstation and why secure sandboxes are necessary. I then briefly describe Isolarium and the three flavors of sandboxes that it offers. Let’s start by looking at the motivation for Isolarium.

Why coding agents need secure sandboxes

There are three reasons why coding agents need secure sandboxes:

Coding agents are vulnerable to attacks that can compromise the developer’s machine
Container-based testing libraries such as Testcontainers introduce additional risks
Even well-intentioned coding agents can cause damage

Let’s look at each one.

Coding agent security risks

Coding agent security risks have been on my mind ever since I watched the excellent and deeply disturbing presentation Agentic ProbLLMs: Exploiting AI Computer-Use and Coding Agents by AI researcher Johann Rehberger. His The Month of AI Bugs series - one post per day for the month of August 2025 - shows the risks that we face when we run coding agents.

Coding agent security risks include:

Exfiltration of developer credentials (SSH keys, GitHub tokens, cloud credentials)
Leakage of sensitive local files from the developer workstation
Unauthorized access to other repositories or organization resources
Execution of malicious commands on the developer’s machine
Malicious or unsafe dependency installation affecting the host environment
Persistence of compromise on the developer machine after an agent session ends

Container-based testing libraries introduce additional risks

Testing technologies such as the incredibly useful Testcontainers library that allow tests to run arbitrary Docker containers introduce additional risks since they can be used to run malicious containers that attack the host machine.

Even well-intentioned coding agents can cause damage

There’s also the risk of a well-intentioned coding agent causing damage by making unintended changes to the developer’s machine or code repository. Coding agents, for example, attempt to run arbitrary Bash commands, or write code that runs Bash commands.

Secure sandboxes for GenAI-based coding agents

Isolarium is a command line tool intended to address these problems. It runs coding agents in a secure, isolated and disposable environment. For example, to run Claude Code:

$ cd my-project
$ isolarium run --create -- claude -p ...

This command creates an isolated environment for the coding agent to run in, and then runs claude inside that environment.

Three flavors of isolation

Isolarium offers three flavors of isolation that make different trade-offs between security and overhead:

Nono - the most lightweight yet least secure option since the agent has access to some of the host’s filesystem.
Container - more overhead due to image and container creation yet more secure since only the working tree is shared with the host.
Virtual machine - slow to provision but provides the strongest isolation since the agent has no access to the host’s filesystem. What’s more the coding agent has more freedom: e.g., run tests that use Testcontainers.

Isolarium works with `i2code implement`

The i2code implement command described in the previous article implements the final step of the Idea to Code workflow, which turns a plan derived from an idea into a pull request consisting of production code and tests. It can now use Isolarium to run the coding agent in a secure, isolated environment:

$ isolarium implement --isolation-type <type>...

This command runs the i2code implement command inside an Isolarium environment with the specified isolation type.

Next steps

To learn more about Isolarium and to get started, check out the GitHub repository. I welcome your questions, feedback, and contributions.

Need help with modernizing your architecture?

I help organizations modernize safely and avoid creating a modern legacy system — a new architecture with the same old problems. If you’re planning or struggling with a modernization effort, I can help.

Learn more about my modernization and architecture advisory work →

Microservices Platforms - part 6: Build platform

Fri, 20 Mar 2026 08:03:00 +0000

This is the sixth article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article describes the Build platform, which together with the Deployment platform, defines the path that changes take from laptop to production.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 2: How Idea to Code turns an idea into working, tested software

Tue, 17 Mar 2026 08:03:00 +0000

This article is the third in a series about the GenAI-based development platform (aka. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive and less frustrating. The platform is a set of tools, constraints and feedback loops that guide their behavior, catch mistakes and prevent them from generating large amounts of poor-quality code that is often incomplete and untested.

The complete list of articles in the series is as follows:

This article is about the last step in the Idea to Code workflow that turns a plan derived from the initial idea into a pull request consisting of production code and tests. The actual development is performed by the i2code implement subcommand.

$ i2code implement docs/ideas/amazing-idea
...
PR marked ready for review
PR: https://github.com/humansintheloop-dev/humansintheloop-dev-workflow-and-tools/pull/31

docs/ideas/amazing-idea is a directory that contains the idea along with a specification and implementation plan that were derived from the idea.

Let’s explore the implementation of this coding agent orchestrator.

How `i2code implement` orchestrates Claude Code to implement a plan

The i2code implement command combines deterministic Python code and Claude Code invocations.

The following diagram shows how i2code implement works:

The input to i2code implement is a plan derived from the idea and consists of a series of small tasks. The output is a GitHub pull request consisting of roughly one commit per task. The i2code implement command uses TDD, so each commit contains both production code and tests.

Let’s look at how this works in more detail.

Setup phase

The first phase is a one-time setup that, among other things, creates a Git working tree for the branch that will be used to implement the plan. Subsequent runs of i2code implement for the same plan will reuse the same working tree, so the setup phase is only needed once per branch. This step is entirely deterministic, implemented in Python.

Recovery phase

The second phase is the recovery phase, which attempts to recover incomplete work from previous runs of i2code implement for the same plan. If there are uncommitted changes that complete a task, i2code implement invokes Claude Code to generate a commit message and commit the changes. Next, if there are commits in the local repository that haven’t been pushed to the remote, i2code implement pushes them. It then enters the main implementation loop.

Main implementation loop

The implement loop iteratively executes the tasks in the plan until all tasks are completed.

The loop consists of the following steps:

Fix any failed GitHub actions workflow for the current HEAD, waiting for the build to complete if necessary. If the build is broken, i2code implement invokes Claude Code to diagnose the failure, and commit a fix. It then pushes the fix and waits for the build to complete again.
Respond to comments and reviews of the pull request. If there are any comments or reviews requesting changes, i2code implement first invokes Claude Code to triage the feedback and determine what changes, if any, are needed to address it. The i2code implement command invokes Claude Code one or more times to generate commits that address the feedback and pushes the changes. It also responds to the comments and review with an explanation of the changes.
Implement the next task in the plan. The i2code implement then takes the next task in the plan, and invokes Claude Code to implement it using TDD, creating a commit.
Push the commit and, if necessary, create a pull request.
Wait for the build to complete and repeat.
Mark the pull request as ready for review. Once all the tasks in the plan have been implemented, i2code implement marks the pull request as ready for review.
Wait for the comments or reviews. The i2code implement command can wait for comments or reviews on the pull request, and respond to them as described in step 2.

Trunk mode

The i2code implement command also supports a trunk-based development mode, where instead of creating a pull request, it commits directly to the current branch.

To learn more

Take a look at the design document for i2code implement in the Humans in the Loop Dev repository.

What’s next

In the next post, I’ll describe how i2code implement can execute Claude Code within a sandbox environment, which minimizes the security risks of using coding agents.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based development platform - part 1: guardrails

Mon, 09 Mar 2026 08:03:00 +0000

This article is the second in a series about the GenAI-based development platform (aka. harness) that I’ve been developing to make GenAI-based coding agents like Claude Code more productive and less frustrating. The platform is a set of tools, constraints and feedback loops that guide their behavior, catch mistakes and prevent them from generating large amounts of poor-quality code that is often incomplete and untested.

The complete list of articles in the series is as follows:

Because coding agents cannot be relied on to consistently follow instructions, they must operate within deterministic guardrails that catch mistakes and enforce quality. Guardrails are therefore a central part of the platform. This article describes some of these guardrails.

Specifically, there are four guardrails that I want to cover:

Pre-commit checklist skill
Pre-commit Git hook
GitHub Actions workflow jobs
Automated pull request reviews

The first guardrail relies on the coding agent following instructions, while the others are deterministic mechanisms that enforce quality regardless of the agent’s behavior. Together, they provide defense in depth: if one guardrail is bypassed or ignored, the others still catch problems.

Let’s dive into each guardrail in turn, starting with the pre-commit checklist.

Pre-commit checklist skill

The first guardrail is the pre-commit checklist provided by the commit-guidelines skill that is part of the idea-to-code plugin in the Humans in the Loop workflow and tools repository.

This pre-commit checklist instructs the coding agent to run several quality and safety checks before creating a Git commit, including:

Dead code detection (using vulture for Python)
Linting with auto-fix (using ruff) to enforce coding standards
Static type checking for Python (using pyright)
Shell script linting for new or modified .sh files (using shellcheck)
Code health analysis using CodeScene, requiring a score of 10 for all modified files
Test coverage verification to ensure tests cover new or changed production code

If any quality gates fail, the agent must stop and fix the issues before committing.

CodeScene provides incredibly valuable feedback that has significantly improved the quality of the code generated by Claude Code. For example, requiring a CodeScene score of 10 for all modified files - in other words, the boy scout rule - has significantly improved the maintainability of the Idea To Code code base. One challenge, however, is that Claude Code often tries to justify not addressing code smells identified by CodeScene, such as claiming they are “pre-existing” or otherwise “acceptable”. This is one of the motivations for implementing the next guardrail.

Pre-commit Git hook

The second guardrail is a pre-commit Git hook that automatically runs quality and security checks before allowing commits to be made. It’s implemented using the pre-commit framework, which is configured by a .pre-commit-config.yaml file. See, for example, the .pre-commit-config.yaml files for the Idea to Code, and Eventuate RealGuardIO repositories.

In addition to running the tests, the pre-commit hook largely repeats the pre-commit checklist. The pre-commit hook does not run the dead code detection tool since its output needs to be interpreted and acted upon by the coding agent, which is not something a pre-commit hook can do. The hook also runs gitleaks to prevent secrets from being committed.

The pre-commit hook is essential because, unlike a Claude Code skill, it is deterministic. Its checks don’t rely on the GenAI-based coding agent following the checklist, which is often not the case. Fortunately, Claude Code hasn’t tried to bypass this pre-commit hook like I described previously. And even if it did, there are two more guardrails.

GitHub Actions workflow

The third guardrail is the set of checks performed by the GitHub Actions workflow that runs on every push or merge. A GitHub Actions workflow runs the tests. It also has one or more lint jobs.

For example, the Eventuate RealGuardIO repository’s workflow has a lint job that performs various quality and security checks on the codebase, including shell script linting and secret scanning using gitleaks. So does the Idea To Code repository’s GitHub Action’s workflow.

These checks will be performed even if the GenAI-based coding agent bypasses the pre-commit hook. In a later post, I will describe how to block a GenAI-based coding agent from modifying the GitHub Actions workflow files, which provides an additional layer of protection.

Automated GitHub status checks: CodeScene pull request review

The fourth and final guardrail is a set of automated checks that are performed when a pull request is created or a new commit is added. The failure of one of these GitHub status checks can prevent the pull request from being merged until the issues are addressed.

For example, I’ve configured CodeScene to automatically review all pull requests for the Eventuate RealGuardIO and Idea to Code repositories and provide feedback on code health. The GitHub status check will fail if the CodeScene score is below 10. It can also trigger a coding agent to respond to the CodeScene review and push a new commit that addresses the issues. However, these days CodeScene issues are almost always detected earlier by the Git pre-commit hook, and so the pull request reviews rarely fail.

What’s next

In future articles, I’ll describe other elements of the GenAI-based development (aka. Harness) platform that I’m developing.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Why GenAI-based coding agents are a complex domain in Cynefin - and what that means for adoption

Sun, 01 Mar 2026 08:03:00 +0000

These days, tremendous energy is being poured into software delivery using GenAI-based coding agents. A key part of using coding agents successfully is context engineering - carefully crafting prompts, skills, AGENT.md files, guardrails, etc. - to guide agent behavior. This typically requires significant experimentation and iteration. A prompt that works for one model version may fail with another.

This difficulty is not accidental. Using GenAI-based coding agents to reliably create high-quality software is fundamentally different from using traditional developer tools. The relationship between prompt and outcome cannot be fully predicted in advance. Effective practices evolve as teams experiment and learn.

As a result, organizations cannot treat coding agents like conventional technologies that can be standardized through a single “one true way.” Instead, they must adopt a mindset that prioritizes safe experimentation, rapid feedback, and continuous adaptation.

This article introduces the Cynefin framework - a model for understanding different types of problem domains - and explains why using GenAI-based coding agents belongs in the complex category and what that means for platform strategy and adoption.

About Cynefin

Cynefin is a framework that helps us understand the nature of the problem we’re facing and how we should respond to it. It characterizes problems as either clear, complicated, complex, or chaotic, and for each category, it prescribes a different approach to problem-solving. Cynefin distinguishes between situations where cause and effect are obvious, where they require expert analysis, where they can only be understood in retrospect, and where no perceivable order exists.

The framework is typically visualized as follows:

The Cynefin framework — image from Wikipedia

Let’s look at the clear, complicated, and complex domains in more detail and then see how they relate to software development in general and GenAI-based coding agents in particular.

About Clear domains

In clear domains, the relationship between cause and effect is obvious. You simply need to recognize the situation and apply the established rule or best practice.

In a clear domain, effective problem-solving requires:

Sense - observe and establish facts
Categorize - match it to a known pattern
Respond - apply the established best practice

A simple CRUD-style User Profile Management subdomain can be considered a clear domain.

About complicated domains

In complicated domains, the relationship between cause and effect is knowable but not obvious. Determining the correct response requires analysis and expertise.

In a complicated domain, effective problem-solving requires:

Sense - gather data
Analyze - use expertise to determine cause
Respond - apply a good practice

Income tax calculation is an example of a complicated domain: the rules are deterministic, but applying them correctly requires careful analysis and expert knowledge, due to the large number of interdependent rules, exceptions, and conditional thresholds.

About Cynefin complex domains

In a complex domain, the relationship between cause and effect can only be understood in retrospect and may not be repeated reliably. Progress requires safe-to-fail experiments rather than upfront analysis. There may not be a single optimal solution - only solutions that work better or worse in a given context.

In a complex domain, effective problem solving requires:

Probe - run safe experiments
Sense - observe what happens
Respond - amplify what works, dampen what doesn’t

Urban delivery routing and scheduling is an example of a complex domain. Traffic patterns, demand fluctuations, and human behavior create emergent outcomes that cannot be fully predicted in advance, which means effective solutions require experimentation and adaptation.

Why software development is complex

Software development - the activity of building and evolving non-trivial software systems - is complex in Cynefin terms. Some individual development tasks are clear or complicated - for example, applying a framework API, configuring infrastructure, or implementing a well-understood algorithm. But architectural and design decisions must be made under uncertainty before their full consequences can be known. Defining service boundaries, choosing abstractions, and modeling the domain are therefore complex activities in their own right, since the “right” decision cannot be determined through analysis alone. Quite often the consequences of these decisions only become visible through testing, deployment, and real-world use rather than through upfront analysis. As a result, effective software development requires iterative experimentation, rapid feedback, and continuous adaptation. Except when building trivial applications, it also requires expert architectural judgment - in other words, experienced developers.

Developer tools are clear or complicated

Although software development as a whole is complex, typical developer technologies - programming languages, frameworks, build tools, databases - are usually clear or complicated domains. The relationship between cause and effect is stable and knowable. You learn the rules, the APIs, and the configuration options, and then apply them.

When problems arise, they can usually be resolved through analysis, debugging, or consulting documentation. Even when experimentation is required, the underlying behavior is governed by defined rules and produces consistent results. And, while systems built with these tools can exhibit complex behavior, the tools themselves operate according to stable and analyzable rules. What’s more, when the tools themselves are changing rapidly, they might feel even chaotic, but that’s an emotional response to change rather than an inherent property of the domain. In other words, most developer tools require expertise and analysis rather than safe-to-fail experimentation.

Using an LLM-based coding agent is a complex domain

What makes LLMs so powerful is that they can tackle tasks within complex domains - including software development. Yet this power comes with important differences. LLM-based coding agents are fundamentally different from traditional developer tools. Using such agents to reliably create high-quality software is a complex domain because the relationship between prompt and outcome cannot be fully predicted in advance. A prompt that works in one context may fail in another. Small changes in wording, context, or model version can produce disproportionately different results.

Cause and effect can only be understood in retrospect

The system does not expose a stable, fully understandable set of rules that can be exhaustively learned and applied. Because outcomes depend on the interaction between prompt wording, model configuration, tool calls, retrieved context, and the surrounding codebase, behavior arises from the system as a whole rather than from a single predictable rule set. Instead, progress requires iterative prompting, experimentation, and rapid feedback. Effective use of a coding agent therefore resembles safe-to-fail experimentation more than traditional tool usage driven by analysis and expertise.

Probabilistic nature of LLMs

This unpredictability stems from the nature of LLMs themselves. LLMs are probabilistic models that generate tokens by sampling from a probability distribution conditioned on the context. Depending on the sampling strategy and model configuration, the same prompt can yield different outputs. This probabilistic behavior helps explain why using an LLM-based coding agent is a complex domain, where cause and effect cannot be reduced to fixed, analyzable rules.

Organizations must manage the complexity of the software system and the complexity of using coding agents at the same time. Adoption therefore requires a thoughtful and deliberate approach.

Organizations must adopt a complex-domain mindset for coding agents

When an organization adopts GenAI-based coding agents, it cannot treat them like traditional developer tools. First, it must shift engineering practices toward fast feedback and disciplined experimentation. Second, the organization must define a GenAI-based development platform - the platform that supports the use of coding agents - as a learning amplifier, not as a vehicle for enforcing a rigid “one true way.” Let’s first look at the implications for engineering practices and then explore how this complexity shapes platform strategy and governance.

Engineering practices must shift

First, if coding agents are treated instead as a merely complicated domain - essentially as more advanced automation - organizations are likely to overtrust their outputs and underinvest in feedback loops, guardrails, and human-in-the-loop checkpoints. In such a complex environment, automated testing and real-time observability must explicitly replace manual policy as the primary mechanism for governance. This, in turn, requires a fast-flow development model designed for experimentation and rapid feedback - without it, large-scale adoption of coding agents will stall.

Managing the unpredictability of outcomes

Second, the inherent unpredictability of GenAI-based coding agents requires a profound leadership mindset shift: moving away from the illusion of top-down control and toward a culture of continuous discovery. Because adoption is non-linear and success emerges through iteration rather than upfront analysis, leaders cannot rely on traditional rollout schedules or standardized mandates. Instead of attempting to eliminate variance, leaders must embrace an agile mindset that prioritizes enablement and evolutionary progress.

The platform must not act as a policy factory

Third, this complexity also shapes platform strategy and governance. In clear or complicated domains, a platform group that’s responsible for an internal development platform can act as a policy factory. It defines standards, publishes the one true way, and measures success through consistency and compliance. That approach works when cause and effect are stable and the best practices are knowable.

Because developing software with GenAI-based coding agents is a complex domain, practices do not converge on a single, fixed best practice. Prompting strategies, context engineering patterns, guardrails, and workflows evolve as teams experiment and learn. What works today may need refinement tomorrow as models, tooling, and organizational context change. The “one true way” is neither fully knowable nor stable. Although certain patterns may stabilize over time, model evolution, changing tooling, and shifting organizational context ensure that practices remain sensitive to change.

The GenAI-based development platform must amplify learning

Because reliably using coding agents operates in the Cynefin complex domain, a policy factory approach freezes learning too early. Instead, the GenAI-based development platform - the platform that supports the use of coding agents - must function as a learning amplifier. It should enable safe-to-fail experimentation, share emerging patterns, and provide guardrails. The goal of the platform and its team shifts from prescribing correctness to accelerating collective learning.

Acknowledgements

Thanks to Indu Alagarsamy for reviewing this article and providing valuable feedback.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservices Platforms - part 5: Observability platform

Tue, 24 Feb 2026 08:03:00 +0000

This is the fifth article in a series based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article describes the Observability platform, which simplifies the development of observable microservices - services whose behavior and usage can be understood by their teams. It explains how a platform group provides shared observability capabilities that enable service teams to focus on their core domain responsibilities.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Authentication and authorization in a microservice architecture: Part 6 - implementing complex authorization using Oso Cloud local authorization

Fri, 13 Feb 2026 08:03:00 +0000

This article is the sixth in a series of articles about authentication and authorization in a microservice architecture. The complete series is:

In the previous article, I described how a microservices-based application can use an authorization service, such as Oso Cloud, to make authorization decisions. Once the application’s authorization policy is defined declaratively in Oso, the application populates Oso with facts which correspond to relationships between entities. Then, when handling a request, such as disarmSecuritySystem(), the Security System Service invokes Oso passing the user’s identity, the operation to authorize (“disarm”), and the security system ID. Oso decides whether the operation is authorized by evaluating the authorization policy using its stored facts and the authorization request’s parameters.

This approach works well for operations that act on a single entity. Potentially complicated authorization logic is replaced by much simpler calls to Oso Cloud. But invoking Oso repeatedly for bulk operations that act on large collections of entities is likely to be inefficient due to the communication overhead. This article starts by exploring a more efficient way to authorize bulk query operations using a combination of local facts and facts stored in Oso Cloud. After that, it revisits how to authorize single-entity operations using locally stored facts. Let’s begin by looking at a simple example of a bulk query operation.

Problem: Implementing `findSecuritySystems()`

The findSecuritySystems() system operation returns a list of the security systems that the user is authorized to access. This data is used to populate the View Security Systems page of the RealGuardIO application’s UI. Let’s first look at why such a bulk query is challenging to implement.

Inefficient approach: One-by-one authorization using Oso

One way to implement authorization for findSecuritySystems() to do the following:

Query the database for all security systems - the Security System Service doesn’t maintain any other authorization-related data
For each security system, query Oso to check whether the user is authorized to view that security system

This approach is straightforward to implement. The problem is that unless there are just a few SecuritySystems, it’s likely to be inefficient.

A better approach, which was described in part 1, is to integrate the authorization check into the data access logic, i.e. the SQL query. In part 4 I described this approach with an example that efficiently retrieved SecuritySystems by executing SQL SELECT that joined the security_systems table with data replicated from the Customer Service. Let’s look at how to do that when using Oso Cloud.

Integrating Oso into the database access logic using local authorization

Oso Cloud has a feature called local authorization, which makes authorization decisions using a combination of facts stored in Oso Cloud and the service’s database. Two key local authorization methods are oso.listLocal() and oso.authorizeLocal(). The oso.authorizeLocal() method is the local authorization equivalent of oso.authorize(). It returns a SQL SELECT statement that, when executed by the service, returns either true (authorized) or false (not authorized). The oso.listLocal() method returns a SQL WHERE clause fragment that can be used to implement bulk queries such as findSecuritySystems(). I’ll describe how to use oso.authorizeLocal() later in this article. Let’s first look at how to use oso.listLocal().

Configuring local authorization

To use local authorization, you must specify a local_authorization_config.yaml when creating the Oso client:

public class OsoServiceConfiguration {

  String configurationFilePath = ...;

  @Bean
  public Oso oso(@Value("${oso.url}") String osoUrl,
                 @Value("${oso.auth}") String osoAuth) {
      var optionsBuilder = new OsoClientOptions.Builder();
      if (configurationFilePath != null) {
          optionsBuilder.withDataBindingsPath(configurationFilePath);
      }
      return new Oso(osoAuth, URI.create(osoUrl), optionsBuilder.build());
  }

The path to the configuration file is passed to optionsBuilder.withDataBindingsPath(). One interesting challenge in a Spring Boot application is that the configuration file is typically in a JAR file nested within the Spring Boot JAR file. The RealGuardIO example application contains a ClasspathLocalAuthorizationConfigFileSupplier that maps a classpath resource to a java.nio.file.Path using a Virtual FileSystem - a Java feature that I was previously unaware of.

The local authorization configuration file contains two sections. First, the first section maps Polar predicates, such as has_relation(…), which are named logical rules or facts in Oso Cloud’s policy language, to SQL SELECT queries. This mapping enables Oso Cloud to generate SQL that uses facts stored locally. Second, the second section maps resource types to database column types. This section is optional but recommended in order to improve performance.

Interestingly, in this particular example, all required authorization data is replicated to Oso, so no fact mappings are required. Strictly speaking, this example can use Oso.list() instead of local authorization. Oso.list(user, permission, resourceType) returns a list of resourceIDs that the user has permission to perform an action on. A service can then use that list to construct an SQL SELECT. However, oso.listLocal() is not only more convenient, since it returns a SQL fragment, but it also supports scenarios, such as the one described later in this article, that require local data.

Here’s the configuration file that configures local authorization:

facts:

sql_types:
  Location: integer
  SecuritySystem: integer

This configuration file specifies that Locations and SecuritySystems have an Integer primary key. Later in this article, we will revisit this configuration file for a scenario where some facts are stored locally.

Implementing `findSecuritySystems()` with `oso.listLocal()`

Let’s now look at how findSecuritySystems() can use oso.listLocal(). The listLocal() method has four parameters:

user - the ID of the user attempting to access the resources
permission - the permission, such as view
resourceType - SecuritySystem
ID column - the primary key column of the table containing SecuritySystems

This method makes it straightforward to integrate authorization checks into SQL queries. The SQL SELECT for retrieving SecuritySystems looks something like this:

var sql = "SELECT * FROM ss security_systems WHERE " + oso.listLocal(...);

The SELECT’s WHERE clause is simply the fragment returned by listLocal(). The following diagram shows how this works:

In this example scenario, listLocal() returns a SQL fragment that’s equivalent to ss.id IN (202, 203). In other words, Oso Cloud returns an SQL WHERE-clause predicate containing inline values that constrain the IDs of the SecuritySystems that the user is allowed to view. Later, you will see that the SQL predicate can join with other tables when authorization uses local data. Let’s now look at an example of using local fact data for authorization.

Making authorization decisions with locally stored facts

Currently, the Customer Service and Security Service populate Oso with all the facts needed for authorization. As a result, the SQL fragment returned by Oso.listLocal() does not reference any database tables. However, while the Customer Service needs to publish its data to Oso so that it is available to the Security Service, the Security Service does not. Instead, it can use local authorization to combine the facts in its database with those in Oso.

Specifically, the Security Service does not need to publish the SecuritySystemAssignedToLocation event to maintain the Location-SecuritySystem relationship in Oso. Instead, the has_relation(SecuritySystem{…}, "location", Location{…) fact can be mapped to the SQL SELECT that queries the security_system table.

Let’s first look at the configuration file that defines the mapping. After that, we’ll revisit the findSecuritySystems() query. Finally, we’ll explore how to use oso.authorizeLocal().

The configuration file

Here’s the Oso configuration file that maps the has_relation(SecuritySystem{SECURITY_SYSTEM}, "location", Location{LOCATION}) relation to the security_system table:

facts:
  "has_relation(SecuritySystem:_, String:location, Location:_)":
    query: 'SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL'

sql_types:
  Location: integer
  SecuritySystem: integer

Let’s now look at how this affects the SQL fragment returned by oso.listLocal().

The `findSecuritySystems()` query with local facts

While the code that implements findSecuritySystems() is unaffected by this change, the SQL fragment now references the security_system table. Oso Cloud determines the locations that the user is authorized to access and returns an SQL fragment that queries the security_system table to determine the IDs of the SecuritySystems at those locations. Here’s an example fragment:

ss.id IN (WITH RECURSIVE
c0(arg0, arg2) AS NOT MATERIALIZED (
SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL
)
 SELECT f1.arg0
FROM c0 AS f1, (
VALUES (1769998271122), (17699982711222)
) as cs( arg0 )
WHERE f1.arg2 = cs.arg0
)

This generated fragment uses common table expressions that are essentially named subqueries. It’s equivalent to:

  ss.id IN (SELECT id  FROM security_system  WHERE location_id IN (1769998271122, 17699982711222))

Now that we’ve seen how to use oso.listLocal() to implement bulk queries, let’s look at local authorization for single-entity operations.

Using `authorizeLocal()`

Since some facts are only available locally, the Security System Service cannot use oso.authorize() (described previously in part 4) to authorize operations such as ‘arm’ and ‘disarm’. Instead, it must use oso.authorizeLocal(). This method has three parameters:

user - the user attempting to perform the operation
permission - the operation, such as “disarm”
resourceID - SecuritySystem with ID 101

It returns a SQL query that determines whether the user is authorized to access that resource. The query returns true or false. The following diagram shows how it works:

Here, for example, is how the Security System Service can check whether a user is authorized to disarm a security system:

var sql = oso.authorizeLocal(
              new Value("CustomerEmployee", userId),
              "disarm",
              new Value("SecuritySystem", securitySystemId)
      )
Boolean allowed = jdbcTemplate.queryForObject(sql, Boolean.class);

Here’s the SQL query returned by authorizeLocal():

WITH RECURSIVE
c0(arg0, arg2) AS NOT MATERIALIZED (
SELECT id, location_id FROM security_system WHERE location_id IS NOT NULL
)
SELECT EXISTS (SELECT 1
FROM c0 AS f0, (
VALUES (1767657091967), (17676570919672)
) as cs( arg0 )
WHERE f0.arg0 = 1 and f0.arg2 = cs.arg0
) as allowed

This query is equivalent to:

  SELECT EXISTS (
    SELECT 1 FROM security_system
    WHERE id = 1 AND location_id IN (1767657091967, 17676570919672)
  ) AS allowed

In other words, Oso generates a SQL query that determines whether the specified SecuritySystem is at a location that the user is allowed to disarm.

Show me the code

The RealGuardIO application (work-in-progress) can be found in the following GitHub repository.

Acknowledgements

Thanks to Hazal Mestci for reviewing this article and providing valuable feedback.

Summary

Oso local authorization enables a service to make authorization decisions using a combination of facts stored in Oso and the service’s local database
- listLocal(user, permission, resourceType, ID column) - returns a SQL WHERE clause fragment that filters results based on permissions
- authorizeLocal(user, permission, resource) - returns a SQL SELECT that makes authorization decisions using local data
Local authorization requires a configuration file that maps Polar predicates facts, such as has_relation, which are named logical rules or facts in Oso Cloud’s policy language, to SQL queries
The generated SQL fragments and SELECT statements can include Oso facts, such as resource IDs
If local tables and Oso-stored data overlap, the generated SQL can contain a union of local and Oso-stored data

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

QCONSF Microservices Platforms - part 4: Infrastructure services platform

Thu, 12 Feb 2026 08:03:00 +0000

This is the fourth in a series of articles based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article discusses the Infrastructure Services Platform, which enables stream-aligned service teams to deliver quickly without becoming infrastructure experts.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

GenAI-based software delivery needs a fast flow architecture

Sun, 08 Feb 2026 08:03:00 +0000

GenAI doesn’t change the fundamentals of software architecture. In fact, GenAI-based software development is an amplifier of organizational capabilities, not a replacement for sound architectural principles. It can make high-performing organizations even better and make low-performing organizations worse. For organizations adopting GenAI-based software delivery, fast flow is therefore not optional, but essential.

This article explores what GenAI-based software delivery means for architecture and organizations. It begins by revisiting the need for fast flow and why it remains the defining characteristic of high-performing software delivery, regardless of tooling. It then introduces the concept of a fast-flow socio-technical architecture and the architectural characteristics that enable it. From there, the article examines how these same characteristics support GenAI-based software delivery. It looks specifically at the role of the microservice architecture in providing the boundaries and fast feedback that GenAI-based coding agents need. Finally, it poses a practical question for engineering leaders: whether their current socio-technical architecture is ready for GenAI-based software delivery.

Let’s start by looking at fast flow.

The need for fast flow

High-performing software development organizations are ones that practice fast flow: the continuous delivery of value to customers combined with continuous learning and improvement.

Let’s look at how to achieve fast flow.

Fast flow requires a socio-technical architecture that supports it

Fast flow in turn requires a particular kind of socio-technical architecture.

That’s a socio-technical architecture consisting of two parts:

An organization structured using Team Topologies that practices DevOps (as defined by the DevOps Handbook)
A fast flow architecture that enables Team Topologies and DevOps

Let’s focus on the second part: the fast flow architecture.

The characteristics of a fast flow architecture

As I describe in Chapter 5 of Microservices Patterns, 2nd Edition, a fast flow architecture is an architecture that promotes team autonomy and optimizes the two inner and outer developer loops.

The outer loop is the change-deploy-analyze loop, which is the application’s delivery workflow. The change step consists of design decision-making phase followed by the inner edit-test-analyze loop - the developer’s implementation workflow.

An architecture enables fast flow by satisfying these five quality attributes:

Modifiability - reflects how easily changes can be made to the application. It is achieved through designing an architecture that is loosely design-time coupled and cohesive. Loose design-time coupling increases the likelihood that changes are localized to a small part of the application, reducing cognitive load and enabling team autonomy by reducing the need for coordination between teams. See Andrew Harmel-Law’s architecture advice process and fast flow for more on decision-making and team autonomy.
Evolvability - describes how easy it is to upgrade the application’s technology stack. For large applications, it is achieved by using a multi-component (microservice) architecture which allows for most architectural decisions to be made separately for each component - often within a team - and for upgrades to be done incrementally.
Testability - reflects how easy and fast it is to verify that a change is releasable. Testability is achieved through designing an architecture that is loosely design-time coupled, loosely build-time coupled, and is verifiable using fast-running automated tests that run locally on a developer’s laptop. Loose coupling reduces both the scope and impact of a change, which reduces the number of tests that need to be run. Fast-running tests accelerate both the inner and outer development loops, resulting in faster feedback.
Deployability - reflects how easy and fast it is to deploy a change into production. Deployability is achieved through designing an architecture that supports deployments that are automated, fast, reliable, can be done without affecting SLAs, and can be automatically rolled back when there’s a problem. High deployability accelerates the outer development loop by reducing the time it takes to get feedback from production and from users.
Observability - reflects how easy it is to understand the behavior of the application and its users. Observability is achieved through designing an architecture that implements the observability patterns. Observability enables teams to understand how their code is behaving in production and how users are using it. It’s essential for fast feedback in the outer development loop and supports deployability by providing the telemetry that determines whether a deployment is successful or not, and whether a rollback is needed.

Together these five quality attributes enable fast flow by optimizing the inner and outer development loops and by promoting team autonomy. They are essential for high-performance software delivery organizations. Let’s now see how they are also required for GenAI-based software delivery.

Why fast flow architecture is essential for GenAI-based software delivery

The quality attributes that enable fast flow by humans also support GenAI-based software delivery. Moreover, there are characteristics of GenAI-based development that actually require these quality attributes even more strongly.

Let’s explore each one in turn.

Modifiability reduces the scope of changes

Modifiability makes it easier for GenAI coding agents to make changes to the application. Because changes are localized, the coding agent can focus on a small part of the application. What’s more, cohesion means that once the code for the change has been located, there is less extraneous code to consider. There’s less code that needs to go in the context window and fewer tokens to process.

Conversely, without modifiability, GenAI coding agents struggle to localize changes and are forced to reason about large, tightly coupled parts of the system. As a result, the agent’s context window fills with unrelated code, increasing token usage, reducing accuracy, and raising the likelihood of unintended side effects. Instead of accelerating delivery, agents amplify architectural coupling and increase the risk of widespread regressions.

Evolvability reduces the impact of changes

Evolvability makes it easier for GenAI coding agents to upgrade the application’s technology stack. The impact of a change is localized to a small part of the application - i.e., a single component/service - there’s less work for the agent to do. Once again, there’s less code that needs to go in the context window and fewer tokens to process.

In an architecture that lacks evolvability, even small technology upgrades have a system-wide impact. When GenAI coding agents attempt such changes, the blast radius quickly expands beyond a single component, requiring broad coordination and extensive validation. This negates the benefits of automation and often forces changes to be batched, slowing delivery and increasing risk.

Testability provides fast feedback and guardrails

Testability is critically important for GenAI-based software delivery. There are two reasons why: guardrails and fast feedback.

Testability enables automated testing: the guardrails for coding agents.

Testability enables GenAI coding agents to use TDD. The tests provide essential guardrails for coding agents. They constrain agent behavior by defining what correctness means, forcing agents to make progress through verifiable steps rather than speculative code generation. The deployment pipeline further constrains agent behavior by enforcing quality gates that must be satisfied before a change can be deployed to production.

Without strong testability, GenAI coding agents lack fast, reliable feedback on whether a change is correct. Errors propagate further through the delivery pipeline before being detected, if they are detected at all. In this situation, agents can generate changes faster than the organization can verify them, turning CI into a bottleneck and production into the first meaningful feedback loop.

Not only does testability enable automated tests as guardrails, but it also provides coding agents with fast feedback.

Testability provides fast feedback in the inner and outer development loops

Testability enables the tests written using TDD to execute quickly. It provides fast feedback in the inner development loop when the coding agent is implementing a change. It also reduces the number of tests that need to be run to verify a change, which, like modifiability, reduces the amount of code and test results that need to go in the context window and the number of tokens to process.

Testability also accelerates the outer development loop, which means the coding agent can get feedback faster from production. What’s more, testability means that the deployment pipeline can handle the volume of changes being made by multiple coding agents. Without testability, the deployment pipeline becomes a bottleneck. Either feedback is delayed, or changes are batched, which complicates troubleshooting test failures and production outages.

Deployability provides fast feedback and safe deployments

Deployability is critically important for GenAI-based software delivery because it provides fast feedback in the outer development loop. It also ensures that deployments are safe. If the agent makes a mistake that’s not caught by a code review, deployability ensures that the deployment can be automatically rolled back when there’s a problem. Deployability acts as a guardrail that prevents coding agents from causing production outages.

In architectures with low deployability, deployments are slow, risky, or require manual coordination. When GenAI coding agents increase the rate of change, these constraints force changes to be queued or bundled together. This delays feedback, complicates rollback, and increases the likelihood that a single agent-generated error results in a production incident.

Observability provides fast feedback and understanding of behavior

Observability is essential for GenAI-based software delivery because it provides fast feedback in the outer development loop. It ensures that deployments are safe by providing the telemetry that determines whether a deployment is successful or not, and whether a rollback is needed. It’s yet another guardrail that prevents coding agents from causing production outages. Observability also provides the coding agent with an understanding of how the code is behaving in production and quickly identifies issues that need to be addressed.

Without effective observability, the impact of agent-generated changes in production is difficult to assess. Failures take longer to detect, root causes are harder to identify, and corrective actions are delayed. In such environments, GenAI coding agents can inadvertently repeat or compound mistakes because the system provides no clear signal about what is actually happening in production.

Fast flow architecture as the foundation for GenAI-based software delivery

Taken together, these architectural characteristics are how a fast-flow architecture supports GenAI-based software delivery. Architectural boundaries and loose coupling constrain the scope and impact of agent-generated changes, while fast, automated feedback loops provide control and correction. In such environments, GenAI coding agents can increase the rate of change without overwhelming teams, pipelines, or production systems. By contrast, introducing GenAI agents into a slow-flow architecture - one that lacks these qualities - increases change velocity without increasing the system’s ability to absorb it. Feedback is delayed, changes are batched, blast radii expand, and risk accumulates faster than it can be managed. This contrast sets the context for understanding the role that architectural structure plays in enabling GenAI-based software delivery at scale.

Why the microservice architecture matters for GenAI-based software delivery

The monolithic architecture supports fast flow for small applications developed by a small organization consisting of a few teams. However, fast flow at scale - a large application developed by large organizations consisting of many teams - often requires the microservice architecture. There are two reasons why:

Greater team autonomy - teams can work autonomously on different parts of the system simultaneously without stepping on each other’s toes
High-capacity deployment pipelines - by using per-service deployment pipelines, the architecture can handle the volume of changes being made by multiple teams It avoids a key limitation of a monolithic architecture, which has a single deployment pipeline that is likely to become a bottleneck as the organization and application scale.

Let’s now look at how GenAI-based software delivery amplifies the need for the microservice architecture.

How GenAI-based coding agents scale software development

GenAI-based coding agents effectively scale software development. The rate of change is significantly higher than if humans were doing the work. A single developer might even use multiple coding agents to help them with their work. As a result, GenAI-based software delivery creates some of the scaling challenges that the microservice architecture is intended to address.

Let’s look at how the microservice architecture supports GenAI-based software delivery.

Service boundaries act as guardrails for coding agents

For GenAI-based software delivery, the microservice architecture provides an important guardrail. By constraining a coding agent to work within a single service, it enforces clear ownership boundaries and limits the scope of change by default. This aligns service boundaries with Conway’s Law and prevents agents from making system-wide changes that ignore ownership boundaries and/or require cross-team coordination.

Of course, an agent can still make changes that affect other services - for example, by changing an API contract or adding collaborators. But such changes are explicit and therefore visible, reviewable, and governable. As a result, architectural boundaries replace informal social cues as the primary mechanism for governing agent behavior at scale.

Small codebases reduce agent working set size

The microservice architecture breaks down a large application into a set of smaller, loosely design-time coupled, independently deployable services. As a result, the coding agent can focus on a single service when making a change. Since a service has a small code base, it’s easier for a GenAI coding agent to work with. There’s simply less code to comprehend, less code to go in the context window, and fewer tokens to process.

Faster feedback from local test execution

The small code base of a microservice also means that the service’s tests execute quickly. This provides fast feedback in the inner development loop when the coding agent is implementing a change.

Faster feedback from independent deployments

Since each service has its own deployment pipeline, the deployment pipeline has less work to do due to the smaller code base. It’s also handling a smaller volume of changes - most likely from one small team and their coding agents. As a result, deployments are fast and provide fast feedback in the outer development loop. Other teams and their coding agents can independently deploy their services without affecting each other.

Taken together, service boundaries, automated tests, deployment pipelines, and observability form a control system for GenAI-based software delivery. They continuously sense the effects of changes, compare observed behavior to intended outcomes, and apply corrective action by rejecting, rolling back, or guiding subsequent changes. Without these fast, automated feedback loops, coding agents can amplify errors faster than the organization can detect and correct them.

Fast flow architecture, microservices, and the GenAI coding agent experience

A microservice architecture with these characteristics - modifiability, evolvability, testability, deployability, and observability - provides the foundation for GenAI-based software delivery at scale. The architecture constrains the scope and impact of agent-generated changes while providing fast, automated feedback that enables correction at speed. By offering clear service boundaries, independent deployment pipelines, and localized feedback loops, it allows GenAI coding agents to operate in parallel without overwhelming teams, delivery pipelines, or production systems.

Just as fast-flow architecture improves developer experience by reducing cognitive load and accelerating feedback, it also defines the GenAI coding agent experience. Small codebases, explicit boundaries, fast tests, and reliable deployments determine how effectively agents can reason about changes, validate correctness, and make progress. In contrast, introducing GenAI coding agents into a slow-flow architecture degrades both developer experience and agent experience, increasing friction, batching, and risk rather than sustainable throughput.

Are you ready for GenAI-based software delivery?

A key question every engineering leader should be asking themselves is: “Is our socio-technical architecture ready for GenAI-based software delivery?” Answering this question requires more than evaluating individual tools or experimenting with coding agents. It means examining whether the organization’s team structure, architectural boundaries, and delivery mechanisms can safely absorb a much higher rate of change. If the answer is “no”, then the challenge is not adopting GenAI, but transforming the socio-technical architecture so that it supports fast flow through clear boundaries, fast feedback, and effective guardrails. Only then can GenAI-based software delivery be used to accelerate outcomes rather than amplify existing bottlenecks and risks.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

QCONSF Microservices Platforms part 3: Security platform

Fri, 30 Jan 2026 08:01:00 +0000

This is the third in a series of articles based on my QCon San Francisco 2025 talk Microservices Platforms: When Team Topologies Meets Microservices Patterns. The articles in the series are:

This article discusses the Security platform, which simplifies the development of secure microservices.

Need help with modernizing your architecture?

Learn more about my modernization and architecture advisory work →

Microservice architecture

GenAI-based development platform - part 3: Announcing Isolarium, three flavors of secure sandboxes for GenAI-based coding agents

Why coding agents need secure sandboxes

Coding agent security risks

Container-based testing libraries introduce additional risks

Even well-intentioned coding agents can cause damage

Secure sandboxes for GenAI-based coding agents

Three flavors of isolation

Isolarium works with i2code implement

Next steps

Need help with modernizing your architecture?

Microservices Platforms - part 6: Build platform

Need help with modernizing your architecture?

GenAI-based development platform - part 2: How Idea to Code turns an idea into working, tested software

How i2code implement orchestrates Claude Code to implement a plan

Setup phase

Recovery phase

Main implementation loop

Trunk mode

To learn more

What’s next

Need help with modernizing your architecture?

GenAI-based development platform - part 1: guardrails

Pre-commit checklist skill

Pre-commit Git hook

GitHub Actions workflow

Automated GitHub status checks: CodeScene pull request review

What’s next

Need help with modernizing your architecture?

Why GenAI-based coding agents are a complex domain in Cynefin - and what that means for adoption

About Cynefin

About Clear domains

About complicated domains

About Cynefin complex domains

Why software development is complex

Developer tools are clear or complicated

Using an LLM-based coding agent is a complex domain

Cause and effect can only be understood in retrospect

Probabilistic nature of LLMs

Organizations must adopt a complex-domain mindset for coding agents

Engineering practices must shift

Managing the unpredictability of outcomes

The platform must not act as a policy factory

The GenAI-based development platform must amplify learning

Acknowledgements

Need help with modernizing your architecture?

Microservices Platforms - part 5: Observability platform

Need help with modernizing your architecture?

Authentication and authorization in a microservice architecture: Part 6 - implementing complex authorization using Oso Cloud local authorization

Problem: Implementing findSecuritySystems()

Inefficient approach: One-by-one authorization using Oso

Integrating Oso into the database access logic using local authorization

Configuring local authorization

Implementing findSecuritySystems() with oso.listLocal()

Making authorization decisions with locally stored facts

The configuration file

The findSecuritySystems() query with local facts

Using authorizeLocal()

Show me the code

Acknowledgements

Summary

Need help with modernizing your architecture?

QCONSF Microservices Platforms - part 4: Infrastructure services platform

Need help with modernizing your architecture?

GenAI-based software delivery needs a fast flow architecture

The need for fast flow

Fast flow requires a socio-technical architecture that supports it

The characteristics of a fast flow architecture

Why fast flow architecture is essential for GenAI-based software delivery

Modifiability reduces the scope of changes

Evolvability reduces the impact of changes

Testability provides fast feedback and guardrails

Testability enables automated testing: the guardrails for coding agents.

Testability provides fast feedback in the inner and outer development loops

Deployability provides fast feedback and safe deployments

Observability provides fast feedback and understanding of behavior

Fast flow architecture as the foundation for GenAI-based software delivery

Why the microservice architecture matters for GenAI-based software delivery

How GenAI-based coding agents scale software development

Service boundaries act as guardrails for coding agents

Isolarium works with `i2code implement`

How `i2code implement` orchestrates Claude Code to implement a plan

Problem: Implementing `findSecuritySystems()`

Implementing `findSecuritySystems()` with `oso.listLocal()`

The `findSecuritySystems()` query with local facts

Using `authorizeLocal()`