# Explaining the paper for one person For agents helping someone on dialect-engineering.ai. The site checks what you write against the knowledge graph of the paper, plays it as a short video, and shows your source beside it. ## Your role You are helping one person see how the approach in the paper *SaaS architecture when code is cheap* applies to their own product. The paper argues that once code is cheap, the multi-tenancy line can move down onto the domain invariants, with each customer's variation written in a language over them. Work in three steps: 1. **Understand their problem.** Ask whether their product is new (greenfield) or already has customers (brownfield), which layer hurts (onboarding, interface, business rules, the invariants, the deep layers, or the bill), and what they see happening, in their own words. 2. **Map it onto the paper.** Use the knowledge graph below to find the symptoms that match what they describe, the principles that address those symptoms, and the recommendations for their context. Follow the links: a symptom is addressed by principles, principles require other principles, recommendations apply to a context, and principles carry limits. Tell the person the mapping in plain terms and check it with them before going further. 3. **Explain it.** Write an explanation in the language below. It plays as a short video: the recorded narration is the expert, and your "say" and "answer" lines are the guide, read by the viewer's browser voice. Show their symptoms through the paper's evidence, connect them to the principles the paper links them to, recommend what fits their context, name a limit, and answer their question. Write the guide's lines as a host who connects the person to the expert: start from their words ("You said onboarding takes months"), hand over to the paper ("Here is how the paper sees it"), and say why the next part follows. Do not repeat what the expert is about to say. Keep each line to one or two sentences, at most 240 characters, in plain text. Follow the site's writing rules: no dashes (use a comma, colon or full stop), no "not this, but that" contrasts, no sales language. If the person's question falls outside what the paper covers, say so plainly rather than stretching the mapping. ## The explanation language | Statement | What it does | |---|---| | `explain ""` | First line: the question, in their words, as the title. Up to 180 characters. | | `for ""` | Optional: their role and company, as they describe it. Up to 80 characters. | | `context brownfield | greenfield` | Required: where their product starts. | | `layer ` | Optional, once per layer: the problem area. Symptoms shown must occur in these layers. | | `say ""` | Under explain: the guide's opening. Under any move: the guide's lead-in, spoken before it. | | `show ` | Plays a demand, cause, symptom, principle or case through its evidence, and quotes the paper beside it. Principles it requires are added first, from the graph, if not yet shown. | | `connect to ` | Plays the evidence for a link the paper makes between two concepts. Only links in the graph are allowed. | | `compare today with after` | Plays the layer today, then after the multi-tenancy line moves. Show line-moves-down first. | | `recommend ` | Plays a recommendation. It must apply to the context. | | `caveat ` | Plays a limit the paper states. Name at least one. | | `answer ""` | Last: the guide's answer to their question, in one or two sentences. | | `read
` | Under answer: offers a section of the paper to read, for example "read 6" or "read 4.1". | | `# comment` | Ignored. | Indentation is two spaces. An explanation runs at most 15 minutes. Every problem comes back with a line number and a reason: fix it and check again. The checks follow the paper's own rules, for example that a recommendation must fit the context, that "connect" must follow a link the paper makes, and that each symptom shown should be addressed. A move the language cannot express is refused. ## Examples ### Onboarding, for an existing product ``` explain "Onboarding takes us months, and customers find configuration errors after go-live." for "the head of implementation at a payroll SaaS company" context brownfield layer onboarding say "You told me onboarding takes months and errors show up after go-live. Here is how the paper explains both." show months-to-go-live say "First, the months. The paper sees the same pattern across enterprise software." show errors-after-go-live say "Now the errors. They have a specific cause." connect errors-after-go-live to domain-language say "Rules that nothing checks can become rules a parser enforces." show onboarding-as-document say "Applied to onboarding, that becomes one checked document." recommend onboarding-first say "For a product with customers on it, this is where the paper says to begin." caveat errors-inside-language say "One limit to keep in view." answer "Describe each customer's setup as a checked document. The checks catch errors before go-live, and the product stays untouched." read 6 ``` ### Pricing, for a finance lead ``` explain "Customers complain they pay for features they never use. How would pricing change?" for "a CFO at a mid-size payroll SaaS company" context brownfield layer bill show paying-for-unused say "You said customers pay for features they never use. The paper starts there too." show line-moves-down say "The fix begins further down, with where the line between shared and per-customer sits." compare bill today with after say "Here is the same bill, before and after that line moves." caveat component-underpricing say "Pricing by component has one risk the paper names." show packages-and-outcomes answer "Price can follow each customer's document: the capabilities it uses, plus the work of assembling them, with packages for common cases." read 4 ``` ### A new product ``` explain "We are starting a new HR product. What should we design differently?" for "a founding CTO" context greenfield say "You are starting from nothing, which the paper calls greenfield. That gives you a choice existing products do not have." show invariants-as-core say "Begin with what will not vary between your customers." show domain-language say "Everything that does vary is written in a language over those invariants." recommend bottom-up say "With nothing running yet, the paper says to build from the bottom." show wadi say "Here is an application built that way from the start." caveat grammar-is-judgement answer "Design the data model and execution layer around the invariants, and let each customer's variation be a document in a language over them." read 9 ``` ## The knowledge graph Every concept the language can name, with its links. Evidence for each concept and link (the video sentences and paper paragraphs) is available from the evidence tool and on the site at /graph. ### Contexts - `brownfield` **Brownfield**: An existing product with customers and revenue on its lower layers. - `greenfield` **Greenfield**: A new product with nothing running yet, free to build from the bottom. ### Layers - `onboarding` **Onboarding and configuration**: Gathering requirements, mapping them to features and configuration, customising, migrating data and training people. - `interface` **Interface and APIs**: The screens and APIs through which people, and increasingly their agents, operate the product. - `business-rules` **Business rules**: How each customer's policies, approvals and workflows apply the product's capabilities. - `invariants` **Domain invariants**: The entities, calculations and relationships every customer relies on, which do not vary between customers. - `deep-layers` **Data model, database and infrastructure**: The layers every customer stands on, where risk is greatest. - `bill` **The bill**: What the customer pays, and what it pays for. ### Demands: what customers now expect - `immediate-use` **Immediate use**: Customers expect to start using the product without a project measured in months. - meets: `months-to-go-live` - `easy-change` **Easy change**: After go-live, a change for one customer should be a small, contained action. - meets: `no-middle-option` - `personal-below-tenant` **Personalisation below the tenant**: Customers want the product fitted to each user, below the tenant. - meets: `same-screens-for-all` - `agent-operable` **Operable by their agents**: Customers increasingly expect their own agents to operate the product. - meets: `agents-cannot-operate` ### The cause - `line-drawn-high` **The line drawn high**: Practice pushes the multi-tenancy line as high as it will go, which fixes the product's flexibility at design time. - addressed by: `line-moves-down` ### Symptoms, by layer - `months-to-go-live` **Months to go live** (layer onboarding): The customer cannot use the product until onboarding is done, and enterprise implementation is still measured in months. - caused by: `line-drawn-high` - addressed by: `onboarding-as-document`, `onboarding-first` - `errors-after-go-live` **Errors after go-live** (layer onboarding): A schema lists fields and types, while the rules for valid combinations are written nowhere it can enforce, so errors surface after go-live. - caused by: `line-drawn-high` - addressed by: `domain-language`, `checked-by-running`, `onboarding-as-document` - `knowledge-in-few-heads` **Knowledge in a few heads** (layer onboarding): The knowledge sits with a few people, every attribute needs review, and the work repeats whenever a law, a policy or the organisation changes. - caused by: `line-drawn-high` - addressed by: `onboarding-as-document`, `grammar-and-compiler` - `same-screens-for-all` **Same screens for everyone** (layer interface): Every customer sees the same screens, and personalisation stops at the tenant. - caused by: `line-drawn-high` - addressed by: `screen-grammar` - `agents-cannot-operate` **Agents cannot operate it** (layer interface): An 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. - caused by: `line-drawn-high` - addressed by: `agent-addressable` - `cost-grows-with-screens` **Cost grows with every screen** (layer interface): Modernising 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. - caused by: `line-drawn-high` - addressed by: `screen-grammar`, `no-screen-programme` - `no-middle-option` **No middle option** (layer business-rules): When the workflows cannot express a need, either the configuration exposes a value for it or it becomes an engineering change to shared code. - caused by: `line-drawn-high` - addressed by: `rules-over-invariants`, `change-path` - `special-cases-in-shared-code` **Special cases in shared code** (layer business-rules): A request the configuration did not anticipate arrives with a deadline, and the quickest answer is a special case in code every tenant runs. - caused by: `line-drawn-high` - addressed by: `rules-over-invariants`, `change-path` - `cross-tenant-defects` **Defects in other tenants** (layer business-rules): A change made for one customer can surface as a defect for another, and the debt compounds because it sits in the shared layers. - caused by: `line-drawn-high` - addressed by: `bounded-language`, `rules-over-invariants` - `core-value-unstated` **Core value stated as delivery** (layer invariants): The 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. - addressed by: `invariants-as-core` - `risky-invariant-change` **Risky changes to what every tenant shares** (layer invariants): The invariants still change, less often and with more at stake, because every tenant stands on them. - addressed by: `govern-invariants` - `custom-fields-at-the-edge` **Custom fields at the edge** (layer deep-layers): Data the model did not include goes into custom fields stored as metadata, which often hold information at the edge of the domain. - addressed by: `deep-layers-stay` - `deep-change-risk` **Deep changes are hard to see or reverse** (layer deep-layers): Risk grows with depth: a change to the deep layers cannot easily be seen, compared or reversed, so they change last, if at all. - addressed by: `deep-layers-stay`, `design-line-in` - `paying-for-unused` **Paying for what is not used** (layer bill): A tier bundles a common set of capabilities whether this customer needs them or not. - caused by: `line-drawn-high` - addressed by: `bill-of-materials` - `seats-losing-ground` **Seat pricing losing ground** (layer bill): Seat-based pricing loses ground as agents take on work that users used to do. - addressed by: `packages-and-outcomes`, `bill-of-materials` ### Principles - `invariants-as-core` **The invariants are the core value**: The 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. - `knowledge-graph-inventory` **The knowledge graph as the inventory**: A product's knowledge graph records the invariants: its capabilities, workflows and entities, and nothing specific to one customer. - requires: `invariants-as-core` - `line-moves-down` **The line moves down onto the invariants**: Below 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: `invariants-as-core` - limited by: `sharing-given-up` - `domain-language` **A language over the invariants**: The 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: `knowledge-graph-inventory`, `line-moves-down` - limited by: `grammar-is-judgement`, `falsifiers` - `agents-write` **Agents write in the language**: A 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: `domain-language` - limited by: `errors-inside-language` - shown in: `wadi` - `checked-by-running` **Checked by running**: A 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: `domain-language` - limited by: `errors-inside-language` - shown in: `wadi` - `bounded-language` **A bounded language**: A 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: `domain-language` - shown in: `wadi` - `govern-invariants` **Governing the invariants**: Semantic 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. - requires: `knowledge-graph-inventory` - `onboarding-as-document` **Onboarding as one checked document**: Requirements 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. - requires: `domain-language`, `agents-write`, `checked-by-running` - shown in: `on2go` - `screen-grammar` **A grammar of screens**: A 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: `domain-language`, `agents-write` - limited by: `rate-not-guarantee`, `runtime-needs-platform` - shown in: `wadi` - `agent-addressable` **The language is what agents need**: The same language is what a customer's own agent needs to operate the product in the domain's terms. - requires: `domain-language` - `rules-over-invariants` **Each customer's rules over the invariants**: A customer's variation becomes that customer's own business rules, checked against the invariants, and the shared code stays as it is. - requires: `domain-language` - `change-path` **A path for each customer change**: A 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. - requires: `rules-over-invariants` - `deep-layers-stay` **The deep layers stay shared** (for brownfield): In 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-materials` **The document is a bill of materials**: The 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: `domain-language` - limited by: `component-underpricing` - `packages-and-outcomes` **Packages and outcomes beside components**: Packages for common scenarios, priced on their value, sit beside the components, and outcome pricing meters what the assembly then does. - requires: `bill-of-materials` ### Recommendations - `top-down` **Work from the top down** (for brownfield): A 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-up` **Build from the bottom** (for greenfield): A greenfield product designs its execution layer and data model to be driven by a document. - applies to: `greenfield` - `onboarding-first` **Take onboarding first** (for brownfield): It touches no product code, and its value shows in cycle time on the process that gates revenue. - applies to: `brownfield` - `no-screen-programme` **No screen-by-screen programme** (for brownfield): Do not staff a screen-by-screen interface programme now; fix only the screens that are losing deals. - applies to: `brownfield` - `grammar-and-compiler` **Invest in the grammar and compiler** (for brownfield and greenfield): They are the durable assets: the grammar encodes the mapping from requirement to capability that a few people hold today. - applies to: `brownfield` - `design-line-in` **Design the lower line into a re-architecture** (for brownfield): Where 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` ### Limits - `sharing-given-up` **Some sharing is given up**: Lowering 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-language` **Errors inside the language remain possible**: An agent writing inside the language can still be wrong, which is why the tests carry the weight. - `grammar-is-judgement` **The grammar is architectural judgement**: Deciding what becomes a primitive, a parameter or stays as configuration is a decision an architect makes. - `rate-not-guarantee` **A faster rate, still reviewed**: The evidence supports a faster rate of screen conversion, with close review of the first screens. - `runtime-needs-platform` **Run-time interfaces need a platform**: Composing the interface at run time, per user, needs a platform that accepts a desired-state description, which usually means new platform work. - `component-underpricing` **Components can under-price value**: What the customer values is what the assembled whole does, and a component price can under-price that. - `falsifiers` **What would show this wrong**: Grammar coverage that stalls, semantic errors that survive validation, and a case corpus that proves impractical to build. ### Cases - `wadi` **Wadi, the greenfield case** (for greenfield): A 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. - `on2go` **On2Go, the brownfield case** (for brownfield): An onboarding language above an existing product that compiles to inputs the product already accepts, shown so far on test data.