brownfieldAn existing product with customers and revenue on its lower layers.
The knowledge graph
The knowledge graph of the paper
59 concepts and 77 links, each tied to the sentences of the video and the paragraphs of the paper that support it. Agents use it to map the paper's approach onto a person's own problem.
The same graph drives the explanations: an agent maps a person's problem onto these concepts, and every link it draws must be one listed here.
Symptoms and what addresses them
Contexts · 2
Where the product starts.
greenfieldA new product with nothing running yet, free to build from the bottom.
is the path for Build from the bottom
Layers · 6
The stack, top to bottom, with the scene that shows each today and after the line moves.
onboardingtoday: scene 5 · after: scene 19Gathering requirements, mapping them to features and configuration, customising, migrating data and training people.
interfacetoday: scene 6 · after: scene 20The screens and APIs through which people, and increasingly their agents, operate the product.
business-rulestoday: scene 7 · after: scene 21How each customer's policies, approvals and workflows apply the product's capabilities.
invariantstoday: scene 8 · after: scene 11The entities, calculations and relationships every customer relies on, which do not vary between customers.
deep-layerstoday: scene 9 · after: scene 22The layers every customer stands on, where risk is greatest.
billtoday: scene 10 · after: scene 23What the customer pays, and what it pays for.
Demands · 4
What customers now expect.
immediate-useCustomers expect to start using the product without a project measured in months.
meets Months to go live
easy-changeAfter go-live, a change for one customer should be a small, contained action.
meets No middle option
personal-below-tenantCustomers want the product fitted to each user, below the tenant.
agent-operableCustomers increasingly expect their own agents to operate the product.
meets Agents cannot operate it
Cause · 1
What the symptoms trace back to.
line-drawn-highPractice pushes the multi-tenancy line as high as it will go, which fixes the product's flexibility at design time.
is addressed by The line moves down onto the invariants
causes Months to go live, Errors after go-live, Knowledge in a few heads, Same screens for everyone, Agents cannot operate it, Cost grows with every screen, No middle option, Special cases in shared code, Defects in other tenants, Paying for what is not used
Symptoms · 15
What a provider sees today, by layer.
months-to-go-liveThe customer cannot use the product until onboarding is done, and enterprise implementation is still measured in months.
is caused by The line drawn high
is addressed by Onboarding as one checked document, Take onboarding first
is met by Immediate use
occurs in Onboarding and configuration
errors-after-go-liveA schema lists fields and types, while the rules for valid combinations are written nowhere it can enforce, so errors surface after go-live.
is caused by The line drawn high
is addressed by A language over the invariants, Checked by running, Onboarding as one checked document
occurs in Onboarding and configuration
knowledge-in-few-headsThe knowledge sits with a few people, every attribute needs review, and the work repeats whenever a law, a policy or the organisation changes.
is caused by The line drawn high
is addressed by Onboarding as one checked document, Invest in the grammar and compiler
occurs in Onboarding and configuration
same-screens-for-allEvery customer sees the same screens, and personalisation stops at the tenant.
is caused by The line drawn high
is addressed by A grammar of screens
is met by Personalisation below the tenant
occurs in Interface and APIs
agents-cannot-operateAn API bypasses the screens, but an agent still has to learn the product's rules from somewhere else, and a product that needs a person clicking through menus is one their agents cannot use.
is caused by The line drawn high
is addressed by The language is what agents need
is met by Operable by their agents
occurs in Interface and APIs
cost-grows-with-screensModernising means wireframe, build and review, one screen at a time; agents make each screen faster, and the cost still grows with the number of screens.
is caused by The line drawn high
is addressed by A grammar of screens, No screen-by-screen programme
occurs in Interface and APIs
no-middle-optionWhen the workflows cannot express a need, either the configuration exposes a value for it or it becomes an engineering change to shared code.
is caused by The line drawn high
is addressed by Each customer's rules over the invariants, A path for each customer change
is met by Easy change
occurs in Business rules
special-cases-in-shared-codeA request the configuration did not anticipate arrives with a deadline, and the quickest answer is a special case in code every tenant runs.
is caused by The line drawn high
is addressed by Each customer's rules over the invariants, A path for each customer change
occurs in Business rules
cross-tenant-defectsA change made for one customer can surface as a defect for another, and the debt compounds because it sits in the shared layers.
is caused by The line drawn high
is addressed by A bounded language, Each customer's rules over the invariants
occurs in Business rules
core-value-unstatedThe value proposition is stated in terms of delivery, which is cheap to replicate once code is cheap, while the product's encoded understanding of its domain goes unstated.
is addressed by The invariants are the core value
occurs in Domain invariants
risky-invariant-changeThe invariants still change, less often and with more at stake, because every tenant stands on them.
is addressed by Governing the invariants
occurs in Domain invariants
custom-fields-at-the-edgeData the model did not include goes into custom fields stored as metadata, which often hold information at the edge of the domain.
is addressed by The deep layers stay shared
occurs in Data model, database and infrastructure
deep-change-riskRisk grows with depth: a change to the deep layers cannot easily be seen, compared or reversed, so they change last, if at all.
is addressed by The deep layers stay shared, Design the lower line into a re-architecture
occurs in Data model, database and infrastructure
paying-for-unusedA tier bundles a common set of capabilities whether this customer needs them or not.
is caused by The line drawn high
is addressed by The document is a bill of materials
occurs in The bill
seats-losing-groundSeat-based pricing loses ground as agents take on work that users used to do.
is addressed by Packages and outcomes beside components, The document is a bill of materials
occurs in The bill
Principles · 16
The parts of the approach.
invariants-as-coreThe domain invariants are where correctness is decided and what the revenue depends on, so the architecture needs a layer that holds them, with everything that varies built on top.
addresses Core value stated as delivery
is required by The line moves down onto the invariants, The knowledge graph as the inventory
knowledge-graph-inventoryA product's knowledge graph records the invariants: its capabilities, workflows and entities, and nothing specific to one customer.
requires The invariants are the core value
is required by A language over the invariants, Governing the invariants
line-moves-downBelow the line, shared: the invariants, a compiler for the language, the data platform and the infrastructure. Above it, per customer: onboarding, the interface and each customer's business rules.
requires The invariants are the core value
is limited by Some sharing is given up
addresses The line drawn high
is required by A language over the invariants
domain-languageThe invariants are its vocabulary, and its grammar says how business rules may combine them: which parts may vary, what values they admit, and which combinations are legal.
requires The knowledge graph as the inventory, The line moves down onto the invariants
is limited by The grammar is architectural judgement, What would show this wrong
addresses Errors after go-live
is required by Agents write in the language, Checked by running, A bounded language, Onboarding as one checked document, A grammar of screens, The language is what agents need, Each customer's rules over the invariants, The document is a bill of materials
agents-writeA domain expert states the intent in plain language, and an agent writes it in the domain's own vocabulary; the grammar splits one long step into two shorter ones.
requires A language over the invariants
is limited by Errors inside the language remain possible
is shown in Wadi, the greenfield case
is required by Onboarding as one checked document, A grammar of screens
checked-by-runningA validator rejects anything malformed with a location and a reason, functional tests run against a case corpus, and the compiler turns the result into something the expert can see.
requires A language over the invariants
is limited by Errors inside the language remain possible
is shown in Wadi, the greenfield case
addresses Errors after go-live
is required by Onboarding as one checked document
bounded-languageA request the language cannot express is refused, and an agent working in it cannot add an API, a table or a code path, so the shared layers stay out of its reach.
requires A language over the invariants
is shown in Wadi, the greenfield case
addresses Defects in other tenants
govern-invariantsSemantic engineering governs changes below the line: agents trace every change through the graph and report its impact before code is written, and a change merges only when checks against the graph pass.
onboarding-as-documentRequirements are stated in the domain's vocabulary and written as a document that is checked before anything is applied, drives the migration, and compiles to inputs the product already accepts.
screen-grammarA screen becomes a document checked against the domain's rules, so a tenant's or a user's layout is a variation the agent can write; a fixed cost, then a falling cost per screen.
requires A language over the invariants, Agents write in the language
is limited by A faster rate, still reviewed, Run-time interfaces need a platform
is shown in Wadi, the greenfield case
addresses Same screens for everyone, Cost grows with every screen
agent-addressableThe same language is what a customer's own agent needs to operate the product in the domain's terms.
requires A language over the invariants
addresses Agents cannot operate it
rules-over-invariantsA customer's variation becomes that customer's own business rules, checked against the invariants, and the shared code stays as it is.
requires A language over the invariants
addresses No middle option, Special cases in shared code, Defects in other tenants
is required by A path for each customer change
change-pathA change goes first into that customer's own document; where the language cannot express it, into a plugin scoped to that customer, generalised once the need recurs.
deep-layers-staybrownfieldIn a brownfield product the data model, database and infrastructure stay shared and unchanged, out of reach of an agent working in the language; needs that reach them are handled case by case.
bill-of-materialsThe customer's document lists the capabilities it uses and how they are put together, so the price can follow it: each capability used, plus the work of assembling them.
requires A language over the invariants
is limited by Components can under-price value
addresses Paying for what is not used, Seat pricing losing ground
is required by Packages and outcomes beside components
packages-and-outcomesPackages for common scenarios, priced on their value, sit beside the components, and outcome pricing meters what the assembly then does.
requires The document is a bill of materials
addresses Seat pricing losing ground
Recommendations · 6
What to do, by context.
top-downbrownfieldA brownfield product follows the customer's journey: onboarding first, then the interface, then the business rules, later or not at all.
applies to Brownfield
bottom-upgreenfieldA greenfield product designs its execution layer and data model to be driven by a document.
applies to Greenfield
onboarding-firstbrownfieldIt touches no product code, and its value shows in cycle time on the process that gates revenue.
applies to Brownfield
addresses Months to go live
no-screen-programmebrownfieldDo not staff a screen-by-screen interface programme now; fix only the screens that are losing deals.
applies to Brownfield
addresses Cost grows with every screen
grammar-and-compilerbrownfield, greenfieldThey are the durable assets: the grammar encodes the mapping from requirement to capability that a few people hold today.
applies to Brownfield
addresses Knowledge in a few heads
design-line-inbrownfieldWhere a company already plans to rebuild the layer that applies configuration, that rebuild is the place to design the lower line in.
applies to Brownfield
addresses Deep changes are hard to see or reverse
Limits · 7
What the paper says the approach does not guarantee.
sharing-given-upLowering the line gives up some of the sharing that justified the original design, affordable only once the per-customer part is cheap to produce.
errors-inside-languageAn agent writing inside the language can still be wrong, which is why the tests carry the weight.
grammar-is-judgementDeciding what becomes a primitive, a parameter or stays as configuration is a decision an architect makes.
rate-not-guaranteeThe evidence supports a faster rate of screen conversion, with close review of the first screens.
limits A grammar of screens
runtime-needs-platformComposing the interface at run time, per user, needs a platform that accepts a desired-state description, which usually means new platform work.
limits A grammar of screens
component-underpricingWhat the customer values is what the assembled whole does, and a component price can under-price that.
falsifiersGrammar coverage that stalls, semantic errors that survive validation, and a case corpus that proves impractical to build.
Cases · 2
The two applications.
wadigreenfieldA house-design application built around its language: an agent writes the documents, and the controls are generated from them. Its case corpus has not been built.
on2gobrownfieldAn onboarding language above an existing product that compiles to inputs the product already accepts, shown so far on test data.