Coder Legion - Recent posts tagged domain-driven-design

Domain Templates: Stop Configuring Your LLM Knowledge Base From Scratch

Mon, 14 Sep 2026 16:56:15 +0000

The Two Weeks Before the First Document

There is a common pattern in knowledge management projects that nobody talks about enough: the first two weeks are not spent capturing knowledge. They are spent arguing about structure.

What pages should exist? How should the query routing be organized so that "show me the LBO sensitivity table for the Acme deal" lands on the right page instead of returning a generic financial overview? Which source types need their own intake forms, and what fields matter for a pharmaceutical company versus an investment fund? How aggressively should the lint gate fire - a compliance team needs every claim to be citation-backed, while a personal learning wiki can afford to be looser?

These decisions are not arbitrary. They reflect how knowledge actually moves through a domain: the document types people produce, the questions they ask against existing content, the verification standards that professionals in that field consider non-negotiable. A compliance analyst's knowledge base has a fundamentally different shape than a DevOps runbook system, even if both are backed by the same LLM infrastructure.

The problem is that most teams figure this out by trial and error. They install a blank wiki, start ingesting, discover the routing is wrong after a dozen queries fail to route correctly, rebuild the index, start over. The structural questions that should be answered on day one get answered by week four, after the team has already ingested content that no longer fits the corrected structure.

This is the problem that domain templates solve.

What a Domain Template Actually Provides

A domain template is not a demo or a sample dataset. It is a pre-made structural skeleton for a specific knowledge domain - everything that governs how knowledge is organized, ingested, and queried, without any of the actual content.

When you install Synthadoc with a domain template, you get six structural components in one operation:

1. Query routing table (ROUTING.md)

This is the map that tells the query engine which branches of your wiki to search based on the nature of the question. A finance/investment template routes "capital structure questions" to pages about debt financing and covenants, while routing "valuation questions" to financial models and comparable companies. A compliance template routes "regulatory requirement questions" to the regulatory obligations register, separate from the controls and audit findings that address them.

Writing this routing from scratch requires understanding how queries in that domain actually decompose - what the natural question categories are and which page types hold the answers. That is domain knowledge most developers building a knowledge system do not have, and it shows up as poor retrieval quality until someone with domain expertise intervenes.

2. Domain-tuned agent guidelines

Each template ships with a CLAUDE.md, AGENTS.md, and GEMINI.md in the wiki root. These are the standard files that AI coding assistants — Claude Code, Gemini CLI, GitHub Copilot Agents — read automatically when they are active in a directory. The domain guidelines from the template are injected into each file, so any AI tool you already use becomes domain-aware the moment it opens the wiki.

Here is what the clinical healthcare template puts in those files:

Cite clinical guidelines by issuing body, title, year, and recommendation strength (Grade A/B/C or Level 1/2/3). Flag drug dosages with the approved indication, route, weight-based formula if applicable, and key contraindications. Note evidence quality for every clinical claim: RCT, meta-analysis, cohort study, expert consensus, or case report. Never store identifiable patient data in wiki pages — all examples must be de-identified or synthetic.

Compare that to the compliance template:

Map every compliance obligation to the specific regulation, rule, or contractual requirement that creates it. Track compliance controls with the control owner, testing frequency, and last test date and result. Document exceptions and risk acceptances with approver, rationale, and expiry date. Distinguish between legal requirements (non-negotiable) and internal policy requirements (adjustable). Note jurisdiction and regulated entity for every obligation — compliance applies entity-by-entity.

These are not generic instructions to "be accurate and cite your sources." They reflect how practitioners in each field think about quality. When a compliance analyst has Claude Code running in their wiki directory and asks it to help write a page, draft an ingest command, or interpret a lint warning, Claude Code reads CLAUDE.md and already knows that regulatory citations need jurisdiction-level specificity, that control owners must be named, and that internal policy requirements are distinct from legal ones. The analyst gets a coding assistant that understands the domain's standards — without configuring anything.

The same files also include the full Synthadoc CLI reference, page schema, lifecycle commands, and MCP tool list, so the AI assistant always knows how to operate the wiki correctly for that domain.

3. Scaffold stub pages

Each template ships with 8–12 stub pages covering the core knowledge areas of that domain. For finance/investment, these include pages for companies, deals, financial models, and sectors. For a DevOps template, you get pages for infrastructure, incidents, pipelines, and runbooks.

These pages are not populated with content — they are empty frames with the right titles, frontmatter, and a scaffold zone marker that tells the system where auto-generated content can live versus where your own edits are protected.

The scaffold zone mechanic is worth explaining: every scaffold page contains an HTML comment  that divides the page into a preserved zone (above the marker, where you write permanent content) and a generated zone (below it, refreshed by the weekly scaffold job). This means the structural skeleton gets maintained automatically as your wiki grows, without ever overwriting work you have done by hand.

4. Blank intake forms (template-*.md)

The raw_sources/ subfolders in each template install contain blank intake forms for the document types common to that domain. A finance/investment install includes forms for company profiles, deal memos, financial models, and due diligence checklists. A pharmaceutical template includes forms for clinical trial summaries, regulatory submission packages, and drug safety reports.

These are structured markdown templates with pre-defined fields that mirror what practitioners actually record for each document type. An investment banking associate filling in a deal memo form is prompted for the deal thesis, target return, capital structure, and key risks — the same fields they would populate in any professional deal memo, now wired directly into the knowledge base.

5. Pre-validated seed sources (seeds.md)

Every template includes a seeds.md file that lives in the wiki root after installation. This file contains curated ingest commands for public-domain reference sources specific to that domain — all checked for accessibility, domain relevance, and compliance with the domain's own quality standards before the template was released.

For finance/investment, the seed sources include the SEC's investor education materials and the Federal Reserve's H.15 interest rate releases. For banking, they include the FDIC's regulations and the OCC's publications index. For healthcare/clinical, they include clinical guideline registries and evidence-based medicine references.

The intent is to give the wiki real domain context before the team starts adding proprietary content. A query about LBO mechanics should have authoritative reference material to draw on, not just a blank slate.

6. Scheduled maintenance jobs

A template install also pre-registers two recurring jobs: a weekly lint run (Sunday 2:00 AM) and a weekly scaffold job (Sunday 3:00 AM). The lint job validates every page in the wiki against the domain guidelines — checking for citation presence, orphan links, and internal contradictions — then promotes clean draft pages to active status automatically. The scaffold job refreshes the stub pages and index with new LLM-generated summaries of your current content.

Neither job requires manual intervention once the wiki is running.

Template Library: 30 Domains, 9 Categories

Synthadoc ships 30 domain templates organized across 9 categories. The full library is shown below.

┌─────────────────────────────────────────────────────────────────────────┐
│                    SYNTHADOC DOMAIN TEMPLATE LIBRARY                    │
├──────────────────┬──────────────────────────────────────────────────────┤
│  FINANCE (4)     │  Investment · Mortgage · Banking · Accounting        │
├──────────────────┼──────────────────────────────────────────────────────┤
│  TECHNOLOGY (4)  │  Software Dev · DevOps · AI/ML · Data Engineering    │
├──────────────────┼──────────────────────────────────────────────────────┤
│  HEALTHCARE (3)  │  Clinical · Pharmaceutical · Public Health           │
├──────────────────┼──────────────────────────────────────────────────────┤
│  LEGAL (3)       │  Legal Ops · Compliance · IP Management              │
├──────────────────┼──────────────────────────────────────────────────────┤
│  RESEARCH (3)    │  Academic · Market Research · Science Lab            │
├──────────────────┼──────────────────────────────────────────────────────┤
│  OPERATIONS (3)  │  Facility Mgmt · Manufacturing & QC · Supply Chain   │
├──────────────────┼──────────────────────────────────────────────────────┤
│  REAL ESTATE (3) │  Development · Investment · Property Management      │
├──────────────────┼──────────────────────────────────────────────────────┤
│  EDUCATION (3)   │  Personal Learning · Course Design · Corp. Training  │
├──────────────────┼──────────────────────────────────────────────────────┤
│  BUSINESS (4)    │  Project Mgmt · Product Mgmt · HR & People ·         │
│                  │  Marketing                                           │
└──────────────────┴──────────────────────────────────────────────────────┘

The categories were not chosen arbitrarily. The selection reflects two criteria: domains where knowledge is both high-stakes (wrong answers have real consequences) and naturally document-heavy (the source material already exists, it is just not queryable). Finance, healthcare, and legal are the clearest examples — these fields produce enormous volumes of structured documents whose content practitioners need to recall accurately under time pressure. Technology operations and research are the next tier, where the cost of an engineer not knowing the current incident runbook or a researcher duplicating a failed experiment is concrete and measurable.

How the guidelines were designed

Each set of agent guidelines was written from the conventions and standards of the professional community, not from first principles. The investment banking guidelines are grounded in how analysts actually distinguish between management guidance, analyst consensus, and proprietary estimates — a distinction that matters for compliance reasons, not just accuracy. The clinical guidelines encode evidence grading scales (Grade A/B/C, Level 1/2/3) that clinical practitioners use daily. The compliance guidelines map obligations to the specific regulations that create them, which is how compliance officers structure their work to survive an audit.

The seed sources were validated for two properties: accessibility (the URL resolves and returns parseable content) and domain appropriateness (the content meets the quality bar defined in the template's own guidelines). A seed URL that returns a 404, requires authentication, or produces content below the domain's evidence standards is not included. The seeds are regenerated automatically on each release by a validation script that re-checks every URL and re-runs the domain guidelines against the returned content.

Building Your Domain Wiki: From Install to First Query

Getting a domain-template wiki to the point where it can answer real questions takes less than an hour for most domains.

Step 1: Install with a template

synthadoc templates list          # browse all 30 options
synthadoc install my-wiki --target ~/wikis --template finance/investment
synthadoc serve my-wiki

The install command creates a standard wiki, then applies the template: routing table, agent guidelines, stub pages, intake forms, and seeds. staging_policy is set to all on template installs — every ingested page goes to a candidates queue for your review before it enters the live wiki.

Step 2: Read seeds.md

Open seeds.md in the installed wiki. This is your starting checklist: the seed ingest commands at the top give you authoritative reference material in one copy-paste operation; the topic hints below them point you toward additional sources specific to your situation.

# From seeds.md for finance/investment:
synthadoc ingest "https://www.investor.gov/introduction-investing" -w my-wiki
synthadoc ingest "https://www.federalreserve.gov/releases/h15/" -w my-wiki

Step 3: Add your own sources

Place your documents in raw_sources/ using whatever subfolder structure makes sense for your domain. The intake forms in each subfolder show you what fields the ingest agent expects for each document type. Copy a form, rename it (drop the template- prefix), fill it in, then ingest it.

If you prefer to fill everything in first and ingest in one shot, that works too:

# All files in raw_sources/, excluding template-*.md blanks automatically
synthadoc ingest raw_sources/ --batch -w my-wiki

Step 4: Review candidates

After ingesting, open the Obsidian plugin and run Synthadoc: Candidates: review candidate pages... from the Command Palette. The modal lists every staged page with its slug, colour-coded confidence badge (high / medium / low), and ingest timestamp — promote what passes your bar, discard what does not.

Step 5: Run lint

synthadoc lint run -w my-wiki

Lint validates every page against the domain guidelines, checks citation presence, and flags orphan links and contradictions. Clean draft pages are promoted to active status automatically. After lint, your wiki is queryable.

What Happens After the Wiki Is Built

Once your domain wiki is active, you stop thinking about configuration entirely. The agentic workflows built into Synthadoc handle maintenance automatically, and the web UI guides you toward the next action without you having to ask.

After every query or lint run, the web UI reads the response and surfaces a pre-filled prompt for the most important next step: stale pages detected → "Re-ingest these pages"; re-ingest just completed → "Run lint to promote them"; contradicted pages found → "Run the contradiction resolver"; orphan pages or broken wikilinks present → the relevant workflow queued and ready. You click, confirm, and the workflow runs. The hint engine also adapts the suggested queries shown at the start of each session to your wiki's current health state — a wiki with unresolved contradictions gets different starting prompts than one that is clean. Most users find they do not need to remember any maintenance commands at all.

Contradiction resolution — when two pages in your wiki assert conflicting claims, the contradiction resolver workflow identifies the conflict, retrieves the original source documents, and proposes a resolution strategy. For a compliance wiki, this means conflicting regulatory interpretations are surfaced and queued for an analyst to adjudicate, not silently left in the knowledge base. The workflow runs interactively from both the web UI and the CLI.

Orphan management — the lint workflow detects pages that exist but are not linked from anywhere in the wiki, then the orphan resolver workflow proposes where to link them. In a knowledge base that grows through continuous ingest, orphan pages are inevitable; having them surfaced and resolved automatically keeps the knowledge graph connected.

Re-ingest on source updates — when a source document is updated, the re-ingest workflow can refresh the wiki page derived from it, comparing the new content against the old and proposing what changed. For domains like compliance (where regulatory updates are frequent) and clinical medicine (where guideline updates are routine), this means the wiki stays current with the underlying source of truth rather than drifting.

Broken wikilink repair — as the wiki grows and pages are renamed or restructured, internal wikilinks can break. The broken wikilinks workflow scans all active pages, identifies links pointing to non-existent slugs, and proposes repairs — renaming the target, creating a stub, or removing the dead link. It runs from the web UI and the CLI and emits a per-page fix summary.

Citation integrity — the citation faithfulness audit checks whether the claims in each wiki page are actually supported by the source documents it cites. Pages that have drifted from their sources — because the source was updated or the summary overreached — are flagged so they can be re-ingested with current content. For regulated domains, this is the difference between a knowledge base you can trust and one you merely hope is accurate.

Sensitive data handling — the sanitizer strips personally identifiable and confidential content from source documents at ingest time, before any text reaches the LLM or the wiki. If sensitive content is later discovered to have made it through, synthadoc retract removes the affected source from the knowledge base and rolls back every wiki page that cited it, and no manual cleanup required.

Scheduled lint and scaffold — the weekly jobs registered at install time keep running in the background. Lint promotes new draft pages and flags quality issues; scaffold updates the index and stub pages to reflect the current state of the wiki. For most wikis, the only manual intervention required is reviewing the contradiction resolver queue when it surfaces something.

The goal is that after the first few days of populating your wiki, the agentic layer handles the maintenance work that would otherwise require a dedicated knowledge engineer.

Under the Hood: Template Architecture

For readers who want to understand how the template system is built, the architecture is straightforward.

Each template is a folder under synthadoc/templates/<category>/<domain>/ containing seven components: description.txt, guidelines.md, routing.md, seeds.md, wiki/purpose.md, wiki/index.md, and at least two stub pages. The agent skill files (AGENTS.md, CLAUDE.md, GEMINI.md) are not stored in the template directory — they are generated at install time by combining the template's guidelines.md with the standard skill file boilerplate. This means improvements to the boilerplate propagate to all 30 templates without any template file changes.

The install command applies a delta-patch: it creates a standard wiki first, then overlays the template components. This keeps the install logic simple and ensures that structural improvements to the base wiki (new fields, new default settings) automatically benefit template installs.

A completeness test gates every new template contribution. A template that is missing any of the required files, or whose stub pages lack valid frontmatter, will fail the test and cannot be merged. This prevents the template library from accumulating half-finished entries.

Templates are discoverable automatically — no registration required. synthadoc templates list reads the templates directory and builds the listing from the description.txt files. Adding a new template is a file creation, not a registration process.

Quick Reference

Browse the template library: synthadoc templates list
Full install instructions and all 30 templates: /templates/README.md in the installed package
Sync template-managed files after an upgrade: synthadoc templates sync -w <wiki>
Release notes (v1.3.3): rtag

Synthadoc is an open-source LLM-powered knowledge base system. The domain template library is included in every install - no additional packages required.

Designing SAP Integrations for Hospitals in Venezuela: What Actually Makes Sense

Wed, 17 Jun 2026 08:31:26 +0000

In most hospital IT conversations in Venezuela, SAP shows up as a kind of magic word:

“If we put SAP in, inventory, billing, purchases and HR will finally be under control.”

SAP has been a de‑facto standard ERP for banking, retail and manufacturing for decades. It’s powerful, battle‑tested and, when designed well, can indeed tame a lot of operational chaos in healthcare.

But in a real hospital environment, especially in Venezuela and Latin America, there are two hard questions:

When does SAP actually make sense for a clinic or hospital?
How do you integrate it with clinical systems (HIS, LIS, EHR) without breaking everything?

This post is my attempt to answer those questions from a software engineering and architecture point of view, not from a vendor deck.

I’ll focus on:

What SAP really does in a hospital (and what it doesn’t do).
The core mismatch: patient‑centric vs transaction‑centric systems.
Three real‑world integration models I keep seeing.
The special case of the lab: LIS ↔ SAP.
When SAP is overkill and lighter ERPs make more sense.

What SAP actually does in a hospital

First clarification: SAP is not a Hospital Information System (HIS) in the usual Latin American sense.

Out of the box it does not:

Manage beds and wards.
Act as the main UI for doctors’ daily work.
Store detailed clinical notes or exam findings as an EMR.

What it does extremely well is everything around the clinical core, but not clinical itself:

Finance and accounting: contracts with insurers, invoicing, revenue by service line, bank reconciliation, tax reporting.
Materials and inventory (SAP MM): pharmacy stock, surgical supplies, lab reagents, consumables, lot and expiry tracking.
Procurement and vendors: purchase orders, tenders, supplier evaluation, pharmaceutical lot traceability.
HR and payroll (SAP HCM / SuccessFactors): medical and admin staff, shift planning, leave, payroll.
Asset and equipment maintenance (SAP PM): preventive maintenance plans, calibration and breakdown history for biomedical devices.

Hospitals and large clinics in Venezuela (or the ones thinking about SAP) usually got to a point where:

pharmacy stock is in Excel,
accounting is in a standalone system,
purchases run through email,
and nothing talks to anything else.

At that point, SAP (or any serious ERP) becomes attractive.

The core problem: SAP doesn’t know the patient exists

Technically, this is the main design challenge:

Hospitals live in the world of patients and encounters. SAP lives in the world of transactions and documents.

A typical HIS/LIS/EHR organizes everything around:

patients, visits, diagnoses (ICD‑10), orders, lab results, imaging, etc.

The central entity is the person and their episode of care.

SAP organizes everything around:

purchase orders, inventory movements, accounting documents, HR events.

The central entity is the transaction.

Example:

A physician orders a blood test → the HIS/LIS stores the clinical order.
The lab processes the sample → the result gets into the EHR.
Up to this point, SAP knows nothing.

But:

that same sample consumed reagents from specific lots,
has a unit cost per test,
and should hit a given department’s budget or a cost center, and
may need to be billed to an insurer under a specific contract.

Here, SAP must come into play. Which means HIS/LIS and SAP need to talk to each other.

Three integration models you actually see in the wild

In Venezuela and LatAm you’ll see these three over and over (not just in healthcare):

File‑based integration (most common, most brittle)
Classic pattern:

HIS or LIS exports a daily file (CSV, Excel, maybe XML) with:

procedures done,
materials consumed,
patients/insurers to bill.

An operator or script imports that into SAP as:

accounting documents,
inventory movements,
billing batches.

Pros:

Simple to understand and implement.
Can be done in weeks.
No heavy middleware required.

Cons:

Data arrives late (daily/weekly batches).
Any change in file format breaks the integration.
Error tracing is painful: you often discover issues at month‑end when numbers don’t match.

For small clinics with low volume, this can be “good enough”.
For anything larger, it tends to become a “temporary solution” that turns permanent and fragile.

Middleware & events (the sane default in 2026)
Here you put an integration layer between clinical systems and SAP:

Something like SAP Integration Suite, MuleSoft, WSO2, Apache Camel, or a custom event bus.
HIS/LIS publishes events such as:

**- “procedure X completed for patient Y, consumed these materials”,

“lab order Z billed to insurer K”.**
The middleware transforms those into IDocs/BAPIs/REST calls for SAP.

If you’re already thinking in HL7 v2 / FHIR on the clinical side, the middleware can also translate:

from clinical standards (HL7/FHIR messages)
to SAP structures (IDoc schemas, BAPI payloads).

Pros:

Near‑real‑time data.
Less human glue work.
Centralized logging, retries, monitoring.

Cons:

You now own an integration platform (licensing, infra, skills).
You need an integration architect who understands both SAP and healthcare systems.

In a Venezuelan context, this usually means:

either a capable in‑house team,
or a vendor that really knows both SAP and hospital IT (not just one side).

SAP Healthcare verticals (rare in Venezuela, big in large systems)
SAP has built industry solutions for healthcare such as SAP for Healthcare (IS‑H) and S/4HANA Healthcare components that cover patient management, clinical coding, integration with EMR, etc.

Reality in LatAm/Venezuela:

They’re mostly used by very large hospital groups or public systems, often with international funding.
They require highly specialized consultants with global‑market rates.
License + project cost is way beyond what most local institutions can afford.

So in practice you’ll usually see:

standard SAP ERP / S/4HANA for finance, logistics, HR,
integrated with third‑party HIS/LIS/EHR,
not the full “end‑to‑end SAP hospital” stack.

The lab case: LIS ↔ SAP is where things get interesting
The clinical lab is almost always the most sensitive integration point.

You have at least three very different flows:

Clinical flow (LIS):
Orders, samples, tests, validation, results, delivery to the physician.
Reagents & inventory flow (SAP MM / LIMS):
What reagents were used, from which lots, expiry dates, cost per test, remaining stock.
Billing flow (SAP FI/SD):
Which tests were performed, for which patient, under which contract, at what price.

A very common mistake is trying to make SAP drive the entire lab logic. It’s not designed to:

handle test panels,
manage QC curves,
apply analytical validation rules.

That’s what a proper LIS or LIMS is for.

A reasonable architecture looks like:

LIS → SAP MM

consumption of reagents per test,
stock updates,
lot + expiry tracking.

LIS → SAP FI/SD

billing records or pre‑invoices per test / panel,
mapping to patients and insurers.

SAP MM → LIS

confirmations of reagent receipts,
lot info, vendor data, pricing,
min/max stock alerts.

When this works, you stop having:

“ghost stock” in the lab,
expired reagents because no one saw the numbers,
billing that doesn’t match what was actually done.

When SAP actually makes sense (and when it doesn’t)
Four questions I’d ask before recommending SAP to a hospital in Venezuela:

Is your core problem financial/operational or clinical?
If the pain is:

“We don’t know what we really spend in pharmacy”,
“Monthly closes are a nightmare”,
“Purchases are chaos”,
then SAP/ERP is attacking the right layer.

If the pain is:

“Doctors can’t see full patient history”,
“Lab loses results”, then you need to fix HIS/LIS/EHR first, not buy SAP.

Do you have enough scale?
SAP economics work better when you have:

high transaction volume,
multiple sites,
real logistical complexity.

For a small clinic (say <50 beds) or a low‑volume lab, often a lighter ERP or a specialized hospital ERP will have a better cost/benefit ratio.

Can you realistically maintain it?
You’ll need:

SAP Basis / admin,
functional consultants,
developers for integrations.

In Venezuela and LatAm this talent exists, but it’s expensive and has high churn. That has to be part of the business case, not an afterthought.

Is your current HIS/LIS integrable?
If your HIS/LIS vendor can’t show:

a documented API,
a test environment,
and some real‑world integrations,

getting it to talk to SAP will be painful and fragile.

In many Venezuelan hospitals, the first step before SAP is replacing or modernizing the HIS/LIS that has no real API.

Alternatives: when a lighter ERP is better
SAP is not the only way to solve hospital back‑office problems:

Odoo with healthcare modules: open‑source, with hospital management apps (patients, appointments, pharmacy, billing, etc.) that can be customized heavily.
LatAm hospital ERPs: regional products that ship with financial + clinical modules integrated, at lower license/consulting cost than SAP.
SAP Business One: often used by medium‑sized healthcare institutions for finance, inventory and purchasing, integrated with third‑party HIS.

The real decision is not “SAP or nothing”, but:

which operational problem you’re solving,
what size/complexity you have,
and what architecture you can realistically support in the next 5–10 years.

Closing thoughts
In hospitals, SAP is not a magic clinical system and it’s not a villain either.

It’s a very strong tool for one specific layer: financial, logistical and HR complexity at scale. When properly integrated with HIS/LIS/EHR, it gives you:

pharmacy and lab stock that actually reconciles,
billing that reflects the real clinical activity,
purchasing aligned with real consumption,
and a clear picture for management.

When dropped in without integration strategy, change management or clear ownership, it becomes an expensive parallel universe that lives next to the usual spreadsheets.

The difference is not the software. It’s the architecture and the decisions made before the first line of code or customizing.

If you’re working on hospital IT, SAP, or clinical integrations in LatAm and facing similar problems, I’d love to hear your experience.

The original long‑form article (in Spanish, with Venezuela‑specific context) is here:
https://codebymelendez.com/insights/sap-hospitales-integracion-laboratorios-venezuela

Your IDP needs DDD

Tue, 13 Jan 2026 12:14:52 +0000

It has been more than two decades since Eric Evans published his book on domain-driven design (DDD). The idea was to create software designed after the business domain, using the same language and mental models people used outside of the software team.

We don’t talk about domain-driven design much these days. But as George Santayana said: “Those who cannot remember the past are condemned to repeat it.”

As Platform Engineering grows into a movement at scale, we need to revisit the past and apply some lessons from domain-driven design to our internal developer platforms (IDPs). Otherwise, we continually step on rakes to learn why they shouldn’t be left on the lawn.

There’s a host of interesting interconnected ideas in domain-driven design, but one that resonates with Platform Engineering is the concept of a core domain.

What core domains are

When you build software, there are several areas where your innovation, opinions, and solutions create unique value for your organization. You also need many things that don’t add much value, but your software isn’t viable without them.

Let’s use a pizza restaurant as an example. If you sell pizza, you want to make it easy for customers to choose what they want to eat and have it delivered. To complete the process, you need to look up their address and take a payment.

Core domains are the areas where you want to do something different that will give you a competitive edge. For your pizza company, that might be how you present the menu, collect customizations, and offer deals and rewards.

Non-core domains, also called generic domains, are areas where innovation and differentiation make little difference, or where doing things differently may even be undesirable. Customers expect that looking up their address and paying will work like elsewhere. They don’t want you to be innovative here, as it makes it harder to use.

So, core domains are something unique or special to your organization. It’s essential to your business’s existence, and where you should invest the most. This is something you want to do so well that it’s hard for your competitors to copy.

The problem of generic domains

When you spend time on generic domains, you direct time, attention, energy, and investment away from the areas that impact your organization most. Generic domains have limited value because they don’t benefit from doing something different or unique. The pizza company will never create such an excellent payment flow that you’d choose their offering over a competitor who offers better customization.

Generic domains can be just as complex as your core domains, which means they can consume large amounts of investment. Suppose there’s a commercial provider of an offering in your generic domain space. In that case, they’ll be treating it as a core domain and innovating the space, which puts additional pressure on you to invest to avoid falling behind user expectations.

Organizations that avoid the generic domain trap can outpace their competitors as they spend more time working on features that will make them stand out.

How to tame generic domains

There’s an easy way to avoid the generic domain trap. Domain-driven design provides a pattern for managing them, which recognizes the asymmetry in the value gained by investment in core domains versus generic domains.

Instead of reducing costs on paper, the goal is to minimize the real cost of working on generic domains: Lost value.

Press enter or click to view image in full size

You should work through this list from the top and choose the earliest exit available.

Off-the-shelf: Look for existing software or services that address the generic domain. In particular, look to use:
Commercial products and software-as-a-service offerings where the provider treats it as a core domain. Their innovation and support will ensure the generic domain doesn’t become an anchor dragging you back.
Open source tools that are robust and maintained, and where the overheads of adopting and updating them are low.
Isolation: Where you have to build custom code for a generic domain, encapsulate and isolate it. Placing it behind a well-defined interface minimizes the impact on your core domain and lets you switch it out if an off-the-shelf solution emerges later.
Outsourcing: While outsourcing your core domain can cause problems, outsourcing generic domains helps control the cost and distraction of the work. You can define the interface and have an outsourced team focus on the implementation details.
Minimalism: When no other option is available, create a simple minimalist solution that meets the immediate need. Don’t over-engineer the generic domain or add features you don’t need. You can be reluctant to iterate the solution and keep your eyes and ears open for when someone creates a software product or service you can use to replace it.

Analyzing build versus buy

Platform Teams who want to create the most significant force multiplier for the developers they serve need to protect their focus on fitting the tools to the organization. To do that, they need to identify and eliminate areas where their skills are wasted.

A crucial part of this optimization process is performing a solid build versus buy analysis, which should factor in the initial development cost, ongoing maintenance and support costs, and the opportunity cost of diverting resources away from the core domains.

Returning to the pizza restaurant, offloading the address lookup to a vendor that commonly provides this feature will mean users are familiar with how it works. The vendor will dedicate more attention to improving the user experience of their tool, and when the vendor introduces innovations, they appear commonly enough that users accept them.

Similarly, you’d want to offload payments to a fast and secure payment provider. Hence, it works like other sites and keeps pace with developments like 3D secure, tokenization, card security codes, multi-factor authorization, and biometrics. These industry innovations would have forced the developers to revisit this generic domain many times just to keep pace with the baseline.

Why this is crucial for Platform Engineering

Domain-driven design (DDD) tells us to optimize our development efforts where they will have the most impact on the organization’s success. You shouldn’t over-invest in non-core domains, as they have limited business value and drain resources. Building custom solutions for non-core domains brings unnecessary complexity and maintenance burden, and for what? To build something that you could have bought or outsourced.

The software industry is about to re-learn the lessons that led to the discovery of domain-driven design. Industry-wide, we are dedicating thousands of developers to building the same thing. Not a simple minimalist solution to fill a gap left by commercial products, software-as-a-service, or open source software, but a million giant platforms that are out of date before they’ve been pushed to production.

Internal developer platforms sink unless platform teams can shift weight down to underlying tools. By transferring ballast to commercial products or open source tools, the platform team can get back to agility and create simple, minimal solutions that handle real gaps in toolchains caused by truly bespoke needs.

And it’s these very needs that are missed with behemoth platforms. An organization that needed to go an extra two miles on security may adopt Platform Engineering to tailor a truly robust solution to their security needs. As that platform grows and accumulates additional custom features, the focus on security is lost, and the investment is wasted building and maintaining code that doesn’t solve a unique need for the organization.

But it’s not all doom and gloom for Platform Engineers. Commercial and open source tools can rescue them from this inevitability by providing features that make it easy to shift the weight down and keep the platform light enough to float.

Float on our Platform Hub

That’s where Platform Hub comes in. By adding features platform teams need, like process templates, project templates, and policies, platform teams can transfer the effort down to Octopus and lighten their platform by removing thousands of lines of bespoke templating code.

Platform Teams can get back to focusing on the unique needs that make their platform vital to their organization. They will benefit from our innovative mechanisms for template management and policies, which go well beyond the attack of the template clones and the synchronization conflicts that platform teams report with their bespoke solutions.

Happy deployments!

Systems As Mirrors

Sun, 12 Oct 2025 08:26:19 +0000

There’s something quietly unsettling about Conway’s Law. Most people who’ve worked in software long enough can sense its truth. What unsettles is what it reveals when you sit with it.

The law definition, in its original form, is:

Organizations which design systems (in the broad sense used here) are constrained to produce designs which are copies of the communication structures of these organizations.

— Melvin E. Conway, How Do Committees Invent?

At first, it seems structural. Org charts become system diagrams. Split your teams by department, and the system splits the same way. But over time, the reflection deepens. The system doesn’t only mirror who talks to whom — it starts echoing what’s understood, and what’s avoided.

The most confusing systems I’ve seen don’t reflect complexity. They reflect ambiguity.

You see it in familiar places. One service checks a user’s admin flag. Another checks something else entirely. A third overrides both. A field like “approved” means one thing to scoring, another to compliance, and something looser to product. The code bends around uncertainty. But what it adapts to isn’t complexity — it’s a missing decision.

This gets worse when teams try to support everything. A lending flow starts with a clean path. Then you add freelancers, students, returning users. You don’t create new flows. You add flags: hasPayslip, isStudent, incomeSource. Logic branches. Models fork. Scenarios pile up.

Each rule makes sense in isolation. But together, they blur the center. “ApplicationApproved” starts meaning different things depending on the path taken. Eventually, no one can say what it means — only how it behaves under certain conditions.

The system still works. But its meaning doesn’t.

This is where outcome-driven modeling helps. Jobs To Be Done is one approach. It shifts the focus from who the user is to what they’re trying to accomplish. It asks what outcome they’re hiring the system to deliver — and what tradeoffs they’re willing to make.

A persona tells you the user is a freelancer who prefers mobile and has irregular income. The job tells you: access a short-term loan using recent invoices. Suddenly, the model sharpens. Income is about pattern, not payslips. Risk is about volatility. Rejection isn’t the fallback — manual review is.

When you model from outcome, the system knows what it's trying to do.

This is also where domain boundaries matter. Domain-Driven Design introduces the idea of bounded contexts: each part of the system defines its own meaning. Duplication isn’t always a mistake — it’s often how clarity is preserved. Reuse works best when meaning aligns.

Take the classic User model. In KYC, it means identity: documents, name, status. In Scoring, it means applicant: income, employment, credit history. In Auth, it means account: credentials, sessions, MFA. Reusing the ID is fine. Reusing the model leads to something brittle: dozens of nullable fields, conflicting assumptions, tangled dependencies.

Some say duplication is always bad. But that’s a narrow view. It depends on what’s being repeated. Echoing confusion spreads it. But repeating meaning reinforces clarity. Duplication isn’t the enemy — imprecision is.

Once each model speaks a single truth, everything downstream improves. The backend is easier to debug. The frontend becomes more predictable. Changes get safer. Teams stop negotiating the meaning of basic terms and start delivering again.

And that brings us back to the mirror.

Conway’s Law tells us systems mirror their makers. But reflections go further than structure. They echo our indecision, our shortcuts, the choices we didn’t make.

So the real question is:
If every system is a mirror — what part of ourselves are we willing to see?

The Essence of Development: Unravelling the Complexities to Build High-End Applications

Thu, 17 Jul 2025 20:48:00 +0000

As developers, we dive daily into a sea of lines of code, features, and challenges. But before any technological choice, there is a fundamental truth that guides the success of any application, especially those built for established businesses: the clear distinction between business complexity and technical complexity.

The Two Faces of Complexity

Business complexity resides in the rules, processes, and nuances of the very domain in which we operate. It would exist even without a single line of code. Think of the intricate tax regulations of an e-commerce site or the credit approval process of a financial institution. This is the essence, the "why" of our work.

Technical complexity, on the other hand, is what we, as developers, introduce with tools, frameworks, architectures, and implementation decisions. While necessary to bring the solution to life, it should serve the business, not the other way around.

From Distinction to Powerful Architectures

When we cultivate the ability to clearly perceive and map this difference, something magical happens: we elevate our application to a new level. By focusing on accurately modelling the business, isolating it from purely technical concerns, we open the doors to Clean Architecture and Hexagonal Architecture. These approaches allow us to build systems that are more maintainable, testable, and adaptable to business changes, as the core of the application—the business logic—remains cohesive and independent of external layers.

Deepening the Solution with Domain-Driven Design

And if the challenge is to build a robust system for a complex, large-scale business, Domain-Driven Design (DDD) becomes a powerful ally. By immersing ourselves in the domain, in the language of business experts, and translating it into a rich, cohesive model, we build software that truly solves business problems in an aligned and evolving manner.

Conclusion: Build for the Business First

In short, the journey to building high-level applications begins with a careful look at the nature of the complexity we face. By honouring the distinction between business and technology, we pave the way for solid architectures and, consequently, for the success of the product and the business it serves. Remember: understanding the core business is the first step to building solutions that truly make a difference.