Explicit Architecture

Architecture is often misunderstood, but it is essential to understanding systems. Architecture, put simply, are rules that govern behavior in a system, and Explicit Architecture states that an architecture needs to be intentional, separate from infrastructure, and explicit.

Built on Domain-Driven Design, Explicit Architecture is a pillar of the Semantic Operations Framework because I believe that an architecture that is aligned with business goals and operations is a necessary semantic condition for the successful integration of AI.

Adoption Lifecycle

Adopting Explicit Architecture is a staged process: Understanding it, Be Intentional, Make it Explicit. I arrived at this process by going through it myself, albeit in a circuitous and clumsy manner. The truth is that architecture as a key pillar of the framework was not at all a goal or a pre-conceived notion. When I searched for a way to capture the semantic state of an entire organization (a "3P domain pattern" in SemOps lingo), I assumed there was no such thing, but indeed there kind of was in the form of Domain Driven Design.

Understanding Architecture

In a similar dynamic to how Strategic Data seeks to address confusion around data systems and management, Explicit Architecture seeks to address the same for architecture. I was my own first customer, because, despite encountering and making many architecture decisions in my career, I didn't understand it correctly. This was embarrassing, but further research revealed that I was not alone and in crowded company. The industry has conflated architecture with infrastructure for decades, and every canonical authority on software architecture disagrees with the mainstream usage. A quick Google search for "software architecture" will give you a Gemini-generated definition that is fundamentally wrong. For more, see: What is Architecture?. Long story short, here's the clarification:

• Architecture is encoded business rules — what entities exist, how they relate, what constraints apply.
• Infrastructure is where it runs. Swap every tool and the architecture remains, keep tools and change architecture - they are independent concerns.

It seems simple, but actually it's not. Architecture is not easy to understand, and I feel imposter syndrome explaining it to anyone else, because I'm no expert. Luckily for me, and for everyone, implementing it is really the path to understanding, and being an expert is not the goal. Also, as with all well-defined and well-structured concepts, LLMs will help tremendously.

Intentionality

As I will state repeatedly, SemOps is not just about technology. A shift in mind-set and what becomes a priority is necessary, in my view, to get real acceleration from AI, and Explicit Architecture is probably going to be the hardest pill to swallow. Being intentional means acknowledging a starting point, choosing an approach, and designing the architecture before implementation rather than discovering it accidentally. A lot of organizations do not have architecture — they have accumulated infrastructure they draw boxes around and label. This sounds worse than it is in reality, because organizations can operate with implicit architecture — the infrastructure boxes aren't wildly off, and humans navigate ambiguity very well. The typical failure mode is presented when an organization needs to scale or adopt new strategies, and "re-architecting" or some refactoring may ensue, and this is chalked up to "good problem to have" and everyone moves on.

We are playing a different game, though. In Semantic Operations, correct application of architecture isn't optional. The conditions that enable AI to add value are systematic conditions, where everything important is encoded - that's architecture.

Explicit

There is a discipline of AI-Ready Architecture that says code should be "well-structured, explicit, and self-documenting". This is good advice, and Explicit Architecture says the same thing, but not just for code - for everything. The fact that they call it architecture when it only applies to code (infrastructure) is something that we'll just have to let pass (for now).

Most systems begin with implicit architecture: rules embedded in code, boundaries discovered through production failures, contracts defined arbitrarily by whatever the current implementation does, and critical knowledge stored in people's heads.

A useful test: can an agent — human or AI — determine what rules apply in a given situation by reading a document that describes the architecture? If so, the architecture is serving its purpose. The distinction matters because AI agents amplify whichever state exists. Ambiguity that humans can navigate most of the time becomes systematic failure when machines inherit it at scale.

In the SemOps implementation, "explicit" is literal, and instead of a document, the architecture is encoded in SQL schemas, queryable as data, and virtually everything that exists is connected. Capabilities, repositories, patterns, integration relationships - even theoretical concepts - are structured, traceable artifacts ingested into a database. This creates a full traceability chain from meaning to implementation: Pattern → Capability → Script → Library → Service → Port. Each link serves a purpose: a capability without a pattern is unjustified intent; a pattern without a capability is unimplemented theory; a script without capability traceability is unjustified code.

---

Domain Driven Design (DDD)

Domain-Driven Design (DDD) is the architecture design approach for Semantic Operations. I chose DDD based on its ability to link "domain meaning to system boundaries" aligning with my goal to manage amorphous "business semantics". DDD is a rich topic, and I would not be the person to explain it generally, but I can provide insights on how I implemented for SemOps and its fit with AI.

• I had arrived at the idea of operating with more meaningful "complete idea" semantic objects as a way to leverage LLMs while encoding very human-understandable chunks directly related to goals. This is the "Pattern", and it is central to SemOps. Early attempts to encode Patterns worked, but enabling them as a central, shared component got very messy and wiring up context for agents became even messier. In DDD, there is a concept of "aggregates", which is a very abstract way of saying "a container with some stuff in it that's recognizable and has shared rules as a unit". That was exactly what I had been reaching for, and once I implemented that, everything around it fell into place.

• One of the challenges to implementing AI into an organization is delivering the core agent inputs context (pre-load information) and prompt (do something) that are precise and consistent. DDD promotes the idea of "Ubiquitous language", a canonical, versioned vocabulary shared between engineers and "domain experts" (aka non-engineers). In SemOps, the document is automatically updated when anything changes in the architecture, which is everything important. It's a dictionary for me and my agents, and I think I use it as much as they do, because they are usually way ahead of me, which is how I like it.

• Governance is a big component of SemOps. Semantic Coherence is governance, relying fundamentally on provenance and lineage, two fundamental data governance methods. DDD builds governance into the architecture, with "Anti-corruption layers (ACL)" being one of its key features. Domain boundaries makes governance structural rather than procedural, encoded in the architecture boundary itself rather than fragile code in multiple locations or even just documented (as is often the case).

---

What Explicit Architecture Delivers

Semantic Flywheel

Everything described above may sound daunting and complicated, but the machine can be built while in motion using AI. The more of the machine you build, the better AI works at both building the machine and doing what the machine was designed to do. I call it the Semantic Flywheel, and having an Explicit Architecture is one of the critical accelerants. One of my founding tenets was "lean into what AI is good at". LLMs are remarkably good at keeping track of a lot of details if they are highly structured. Make a giant mess of a GitHub repo on purpose and watch a coding assistant blast through hundreds of git records and fix it for a demonstration. By making your architecture explicit, you can deliver a lot of meaning in a small and highly structured package about your whole project or product or company. If you take a look at this System Landscape document and consider this is just a step in an update process, you can get a sense of how this global context will enable speed and autonomy with confidence.

Scale Projection

I have made big deal about separating architecture from infrastructure, and this will surely conjure the looming spectre of "scale". This is fair, and my current infrastructure is anti-scale at the moment (local environment, self-hosted services, local models, local GPU). However, this is by choice, and because architecture is truly explicit and independent of infrastructure, I don't think scaling is the problem it once was. If you isolate scaling to infrastructure, then the infrastructure scaling plan could be quite predictable, vendor neutral, and, frankly, boring. I call this Scale Projection. As of this writing, I'm just beginning to build the tooling and try to prove this out. In practice, every infrastructure component in the Global Infrastructure doc is mapped to a repository and a stated capability — when everything is wired to the architecture, a scaling plan writes itself: walk the map, swap the infrastructure, leave the architecture alone.

Stable core, Flexible edge

An architecture where everything is encoded and tracked may seem like it would be rigid and difficult to do new things, make changes, or experiment. Explicit Architecture isn't because we have a stable core and a flexible edge.

The stable core is the architecture itself — the rules, boundaries, and language described above. It changes slowly and deliberately. The flexible edge is everything else — experiments, integrations, new ideas — and it can move as fast as needed without risking what works.

The mechanism is simple: everything at the edge carries metadata in a standard shape (data shapes), and a knowledge graph automatically detects connections between edge artifacts.

In this architecture doc from the semops-core repo, you can see the pattern in practice:

Detected edges in Neo4j are the flexible edge — model-proposed relationships that may be wrong, incomplete, or use free-form predicates. The edge table is the stable core — committed relationships with constrained predicates (derived_from, cites, version_of, part_of, documents, depends_on, related_to, implements, delivered_by, integration). Graph traversal and human review are the promotion gate between them.

Explicit Enterprise

A side effect of making architecture explicit was that it changed opinion of what "enterprise" could mean. Traditional enterprise strategy is to pick a platform - a vendor - and then that's what you have, work with it or around it. The platform's interpretation of which capabilities you need and how they work is what you bought, but it's your data. Explicit Enterprise inverts this — architecture defines the data structures, infrastructure serves the architecture, the business defines the architecture, and AI agents can run amok.

So, am I suggesting that you "roll your own" enterprise? No Microsoft Office or Salesforce or Zendesk or Netsuite? Maybe trending towards "kind of". Part of the SemOps experiment is to give this a go, and it stemmed from experiencing SaaS platforms as an obstacle to the kind of AI integration and semantic integrity I wanted. Once the architecture became explicit, and everything was wired together (capabilities, patterns, repositories, governance), the enterprise systems became straightforward. Code repositories become functional "agent departments", simple email and calendar apps become agentic routing, Email becomes event routing, an orchestrator repo manages GitHub issues and projects to manage all development work, and accounting is locally hosted (fully secure) free, and almost fully agentic. Now, I am going "all-in" to learn what's feasible, and my guess is that there is a certain size where this might break down, but who knows. At the very least, your choice of platform could be driven by your architecture and your business, and you will have more options. The market is taking notice - the demand for simpler, agent-friendly enterprise is growing quickly.

Where to Start

Making architecture explicit is iterative work, not a one-time project. Five starting points that deliver value immediately:

Name the boundaries. Identify what bounded contexts exist — even informally — and document what each one owns. The act of naming boundaries makes implicit assumptions visible and creates a foundation for everything else.

Version the language. Create a canonical document for domain terminology. It does not need to be comprehensive on day one — start with the terms that cause the most confusion. Version it in source control so changes are traceable and reviewable.

Type the relationships. When systems integrate, document what kind of relationship exists: is one system the authority and the other a consumer? Do they share a kernel? Does an anti-corruption layer translate between them? Typing these relationships prevents the accumulation of undocumented, ad-hoc integrations.

Trace one capability end-to-end. Pick a single business capability and trace it from the domain concept through to the running service. Where do gaps appear? Where is the logic implicit rather than inspectable? This diagnostic reveals the state of the architecture more effectively than any audit.

Measure with AI. Use an AI coding assistant against a specific bounded context. If a straightforward change requires extensive prompting, the architecture in that context has implicit assumptions that need to be made explicit. If the AI generates correct, contextual code with a simple prompt, the architecture is serving its purpose.

---

Related Links

• The Semantic Funnel — The mental model and rule classification behind the framework
• Strategic Data — The D→I pillar: how organizations think about and manage data
• Why SemOps? — The full case for why meaning matters and what makes it hard
• What is SemOps? — The framework definition and overview