Sysbot Technologies

Technical reference architecture · v1.0

AI-Era Website Architecture: Technical Reference Architecture v1.0

Sysbot’s technical reference architecture for AI-era websites: one content store, a human site, an agent surface, a catalog-constrained generative layer and an edge policy, with the security model, request flows, measurement framework and platform contracts.

Status
Draft for engineering review
Date
Builds on
Research Study v1.1
Author
Logesh Chandran

Purpose and scope

This document is the engineering blueprint for Sysbot's AI-era website platform. Every prototype in the research study's roadmap is built against it, and any deviation is recorded as an architecture decision, not made silently.

What it governs. The components, their boundaries, the data contracts between them, the security model, the external interfaces (HTML, REST, MCP, feeds, manifests), the generative UI catalog contract and the measurement framework. It fixes the shape of the system and the rules each part obeys.

What it does not govern. Visual design, copy, individual customer configurations, pricing, and the internal implementation of any component so long as its contract holds. Those belong to the prototypes and to later product work.

Relationship to the study. The research study, Websites for the AI Era, established five shifts and a dual-audience architecture in outline. This document turns that outline into contracts. Where the study left an open question, this document picks a default and records it in the open decisions at the end.

Thesis carried over. A website is a business interface served from one content store to several kinds of client: people, search engines, AI assistants and autonomous agents. It is not a backend for agents. The architecture therefore has one canonical business content store, several surfaces, supporting services that own their operational data explicitly, and one policy layer in front of all of them.

Audience. Sysbot engineers building the prototypes, and reviewers checking a prototype against the blueprint. It assumes familiarity with Next.js, TypeScript, HTTP APIs and the Model Context Protocol (MCP).

Status. Version 1.0, Draft for Engineering Review, dated 30 Oct 2026. This is a reference architecture, not yet the implementation baseline. The engineering review of 30 Oct 2026 found contract-level gaps in six areas; this draft resolves them, and the section Review changes at the end records where. It freezes as the implementation baseline once the Architecture Contract Pack (JSON Schemas, TypeScript interfaces, operation definitions, event schemas, security policy contracts and the first decision records) has been built from it without a contradiction. It remains a living document: each prototype that completes either confirms a section or amends it.

Architecture at a glance

Four kinds of client enter through one edge, reach one of three surfaces, and every surface calls the same three services over typed contracts to reach one store. Two trust boundaries matter: the platform boundary at the edge, and the private boundary below the surfaces, behind which nothing accepts a public request.

Component view: four kinds of client reach one store through one edge, three surfaces and three services
Component view: four kinds of client reach one store through one edge, three surfaces and three services

Dependencies point down only. A surface never reads the database, never defines an operation and never decides authorisation; it renders, projects or composes what the services return. Customer back-office systems and the model provider sit outside the drawing: the first attach to the operations service through adapters, the second to the generative layer through an adapter, so neither ever faces a public surface.

Design principles

Ten rules apply to every component and every prototype. A pull request that breaks one needs an architecture decision record explaining why.

  1. One canonical store, many surfaces. Every business fact a client can see or act on lives once, in the content store, under a typed schema. Supporting services own their operational data (transactional records, security records, session state, measurement events) explicitly, as the data classes under Content store list. No surface holds content of its own, and no surface or service becomes an independent source of truth; a surface renders.
  2. Dual audience by default. Every page and every operation is designed for a person and for an agent at the same time: semantic HTML and a typed contract for the same thing, never a separate "AI version".
  3. Semantic first. Semantic HTML, labelled controls and WCAG 2.2 AA are the baseline, not a compliance pass at the end. Accessible structure is a common foundation for assistive technology and many browser agents, though it does not by itself guarantee successful agent interaction.
  4. Expose operations, not screens. Business capabilities are defined once as typed operations with schemas, then exposed over REST, MCP and, later, WebMCP. Agents call operations; they do not drive forms.
  5. Authentication, authorisation and consent are three layers. Knowing who a caller is never implies what it may do. Every operation carries an authorisation rule and, where it touches a person's data or money, a consent requirement.
  6. Composition, not generation. The generative layer selects and arranges components from an approved catalog. It never emits production HTML, JavaScript, SQL or configuration.
  7. Fail to the conventional interface. When generation is slow, costly, uncertain or unavailable, the traditional page serves the request. The fallback is always present and always complete.
  8. Treat all external text as untrusted input. Page content, user submissions, assistant messages and tool results are data. No component passes them to a model or an operation as instructions.
  9. Measure every surface against the same store. Human visits, agent sessions, citations and conversions are events in one model, attributable to the same content and the same operations.
  10. Own and export. The store, the schemas and the measurement data are Sysbot's and the customer's, exportable in open formats at any time. No component may hold data that cannot be exported.

Component boundaries

Eight components make up the platform. Each owns one thing, exposes it through a named contract, and has an explicit list of what it must never do. Dependencies point downward only: surfaces depend on services, services on the store, nothing depends on a surface.

Component Owns Exposes Depends on Must never
Edge policy Traffic classification, bot identity verification, crawler signals, rate limits, Markdown negotiation, violations log Headers to downstream (client class, verified agent id), robots.txt, Content Signals, the violations log Nothing internal; runs at the CDN Hold content; make authorisation decisions beyond allow, block or challenge
Content store Entities, schemas, versions, provenance, media and Content Credentials Typed read and write APIs, change events, export Database, object storage Render anything; know which surface is asking
Operations service Business operations (search, availability, quote, later order) as typed functions with authorisation and consent rules Operation registry: one definition each for REST, MCP and WebMCP to project Content store, customer back-office integrations (ERP, inventory, booking) Trust caller-supplied identity; call a model
Human site Rendering of pages from the store, navigation, forms, JSON-LD, accessibility HTML, Markdown on request, sitemap, feeds Content store (read), operations service (for forms) Hold content; call back-office systems directly; embed generated code
Agent gateway REST API and MCP server projecting the operation registry; product feed; commerce manifests OpenAPI document, MCP tools and resources, feed and manifest files Operations service, security model Define an operation of its own; bypass authorisation
Generative layer Component catalog, composition protocol, conversation state, model calls, caching, cost budget Composition responses (catalog-constrained JSON) rendered by the human site; conversation endpoint Operations service (as tools), content store (read), model provider Emit code or markup; call back-office systems; store personal data beyond the session
Security model Identity providers, authorisation rules, consent records, secrets, audit log Decision API used by operations service and gateway; consent capture UI used by the human site Edge headers, identity providers Be bypassed by any path; be implemented twice
Measurement Event schema, collection, bot classification join, attribution, citation probe, dashboards Event ingestion, dashboards, exports Edge headers, every surface (emits events), content store (joins on entity ids) Change behaviour of any surface; store raw personal data longer than policy allows

Boundary rules.

  • A surface reads the store through the store's API, never through the database.
  • An operation is defined exactly once, in the operations service, and projected to REST, MCP and WebMCP by the gateway. The three projections share one schema and one authorisation rule.
  • The generative layer reaches business data only by calling operations as tools, so it inherits their authorisation and never has broader access than a user would.
  • The security model is a single service; the edge, the gateway and the human site call it rather than re-implementing checks.
  • Back-office integrations (ERP, inventory, booking, payments) attach only to the operations service, behind adapters, so a customer's systems never face the public surfaces directly.

Content store and data contracts

The store, with its data model, its exposure contracts, its permission model and its export mechanism, is what Sysbot must own outright; the infrastructure around it is replaceable. It holds every fact a client can see or act on, under a typed schema, with a version history and a provenance record, and it can be exported in full at any time.

Data classes. The platform holds five kinds of data. Only the first is the canonical content store; the others are owned by one named service each, live in their own tables or stores, and are never read by a surface except through their owner's API. All five are tenant-scoped and exportable.

Class Examples Owner Store Export Retention
Business content Organization, Product, Offer, Document, Policy and the other entities Content store Postgres relational core and JSONB; object storage for media Full, in the export bundle Versions kept indefinitely; a customer can request erasure of an entity's history
Transactional records Inquiry with its line items; later Order and Booking Operations service Postgres, own schema Full, tenant-scoped Per contract, default seven years for records with a commercial effect
Security records Consent, delegation tokens, authorisation decisions, audit log Security model Postgres append-only tables; secrets in the secret manager Audit and consent exportable; secrets never Audit per policy, default two years; consent for as long as the data it covers
Operational state Sessions, caches, rate-limit counters, conversation state of the generative layer The surface or service that creates it Edge KV, Redis or in-process; never Postgres Not exported; nothing here is a fact of record Conversation state at most 24 hours; caches by freshness tier
Measurement data Events, attribution, citation observations Measurement service Postgres in v1, ClickHouse planned Full, identity references stripped unless authorised Per policy and regulation, default 13 months at event grain

Tenant context. Multi-tenancy of the deployment is an open decision (ADR-008); tenant isolation is not. Every entity, record, event and cache key carries a tenant id from the first schema version. Every operation executes within a tenant context established at the edge from the deployment or host name and confirmed by the security model, never from a caller-supplied parameter. Every database query is tenant-scoped, enforced by row-level security in Postgres and not only by application code. Every export is tenant-scoped. Cross-tenant access is denied by default, with no operation in v1 permitted to cross it. A deployment that serves one customer still runs with exactly one tenant id, so a later move to shared infrastructure is a hosting change, not a rewrite.

Entity model, v1. Nine entity types cover a business website; each maps to a Schema.org type so the human site can emit JSON-LD and the gateway can emit feeds without translation tables.

Entity Schema.org type Key fields beyond name and description Relationships
Organization Organization, LocalBusiness legal name, contact channels, opening hours, identifiers (tax, registry) has Locations, Offers, Policies
Location Place, PostalAddress geo, address, hours, service area belongs to Organization
Product Product sku, attributes (typed per category), media, availability source has Offers, belongs to Category
Service Service service type, area served, lead time has Offers
Offer Offer, PriceSpecification price, currency, unit, validity window, conditions belongs to Product or Service
Category Thing, ItemList hierarchy, facets groups Products and Services
Document Article, FAQPage, HowTo, WebPage body (structured blocks), author, dates, summary references Products, Services, Policies
Policy Thing with a policy subtype kind (returns, privacy, shipping, warranty), effective date, body belongs to Organization
Inquiry Order-like record with status kind (quote, booking, contact), requester, structured line items (InquiryItem), lifecycle status, consent reference, tenant id references Products, Services; written by operations only

Entities added or deferred. Nine entities are enough for the reference prototype; a reusable business platform needs more. Each entity below is either in the v1 schema package now or explicitly deferred with the prototype that must settle it, so that none is invented ad hoc inside a surface.

Entity Why it matters v1 status
InquiryItem One product or service with quantity, unit and notes inside an Inquiry; typed, not a generic items field In v1, embedded in Inquiry
MediaAsset Image, video and document files with dimensions, variants, Content Credentials and provenance metadata In the contract pack; prototype 1 keeps inline media objects on Product and Document until then
Locale Language and region a published version is written for In v1 as a field on every version, not a separate entity
Person Contacts, authors and business representatives Deferred to prototype 3; requester on Inquiry stays an embedded value until then
FAQ Question and answer pairs as a structured entity rather than only document blocks Deferred; the faq block in Document serves prototypes 1 and 5
Availability Inventory and slot snapshots with an as-of time and source Deferred to prototype 3 with ADR-009; check_availability returns it without storing it until then
Review Customer feedback and social proof with provenance Deferred until a customer needs it
Brand Several brands under one organisation Deferred until a multi-brand customer
Redirect URL changes and migration management Deferred to the first migration of a live site

Locales. Multilingual content is designed into the schema now. An entity has one stable id and one canonical URL per locale; each published version carries a locale, and a read asks for an entity in a locale and falls back to the deployment's default locale when no version exists in the requested one. A translation is never a separate entity, so relationships, ids, events and citations stay the same across languages. Markdown, JSON-LD and feeds are rendered per locale from the same version that renders the HTML.

Schema and typing. Each entity has a JSON Schema and a generated TypeScript type; the schemas are the contract, checked at every write. Attributes on Product are typed per Category through an attribute schema stored with the category, so a garment and a furniture catalog share the entity model and differ only in attributes.

Documents are blocks, not HTML. Document bodies are structured blocks (heading, paragraph, list, table, figure, callout, cited fact) so that the same content renders to HTML for people, to Markdown for agents and to catalog components for the generative layer. A cited-fact block carries a source URL and a date, because citation-shaped content is a product requirement, not a style.

Versioning. Every entity is versioned; reads default to the published version, and a version carries author, timestamp and change reason. Published versions are immutable; corrections create a new version. Change events are emitted on publish for cache invalidation and for the measurement join.

Provenance. Media carries Content Credentials (C2PA) through upload, transformation and delivery; the store rejects a pipeline step that strips them. Generated media and generated text are flagged at the entity level so surfaces can label them as the EU AI Act Article 50 and California law require of deployers.

Identifiers. Every entity has a stable, opaque id and a stable public URL. The id appears in every event the measurement framework records, so a citation, an agent call and a human conversion all join on the same key.

Export. A full export is tenant-scoped: a zip of JSON-LD per entity in every locale, Markdown per document, media with credentials intact, and the schemas. The export must round-trip into a fresh store. This is a release gate, not a feature.

Storage. Postgres is the system of record, with JSONB for typed attributes and a relational core for entities, versions and relationships; object storage for media. Full-text and vector indexes are derived and rebuildable, never the source of truth.

Human site

The human site is a Next.js application that renders pages from the store and submits forms to the operations service. It holds no content and no business logic of its own, and it is built to be read by people, search engines and agents from the same markup.

Rendering. Pages are server-rendered from the store's published versions and cached at the edge, invalidated by store change events. Client-side JavaScript enhances; it never gates content. A page with scripts disabled must still show its content and submit its forms.

Markup rules. Landmarks for header, navigation, main and footer; one h1 per page and a strict heading outline; every form control labelled; every interactive element reachable and operable by keyboard; images with alt text drawn from the store; tables with headers; no content conveyed by colour alone. These are the WCAG 2.2 AA requirements and also what gives browser agents consistent structure to work from, whether they read the accessibility tree, the DOM or screenshots.

Structured data. Every page emits JSON-LD generated from the store's Schema.org mapping, never hand-written: Organization and LocalBusiness on the home page, Product and Offer on product pages, FAQPage and Article on documents, BreadcrumbList everywhere. The JSON-LD and the visible content come from the same entity version, so they cannot disagree.

Page shapes built to close. Each page type leads with the answer or the offer, places the primary action above the fold, and carries dated, cited facts near the top. Informational pages end with a specific next action. This is the citation-shaped content finding turned into templates.

Markdown negotiation. A request with Accept: text/markdown receives a Markdown rendering of the same entity version, with YAML front matter carrying the entity id, type, dates and canonical URL, and with the JSON-LD preserved in a fenced block. Vary: Accept is set. Whether the edge or the site performs the conversion is an open decision; the contract is the same either way.

Forms and hand-offs. Forms submit to operations through the gateway, so a person and an agent submitting a quote request hit the same operation and the same validation. Hand-off steps where an agent must stop, such as login, payment or identity confirmation, are single screens with a stable URL, resumable from the state the agent left.

Conversational layer placement. The generative layer's conversation surface is embedded as a visible, labelled panel with suggested prompts, beside navigation rather than instead of it, and it is disclosed as AI. The page is complete without it.

Performance budgets. All budgets are measured at the 75th percentile. Field data comes first: mobile real-user monitoring from the site itself or the Chrome UX Report where the site has enough traffic. Lab runs use one defined profile, a mid-range Android device class with Lighthouse's mobile CPU throttling, a 4G network of 1.6 Mbps down and 150 ms round trip, and a cold cache. Largest Contentful Paint under 2.0 s; Interaction to Next Paint under 200 ms; initial-route JavaScript under 150 KB as compressed transfer size on a content page, with total JavaScript per page reported but not gated in v1; Markdown rendering under a quarter of the HTML token count for the same page. Budgets are checked in continuous integration on the lab profile, and a page that exceeds them does not ship.

Disclosure and labelling. Generated media and generated text carry a visible label drawn from the entity flag; the conversation panel states that the user is talking to an AI system; the cookie layer defaults to the most privacy-preserving choice and asks once.

Agent surface

The agent surface is a projection, not a system of its own. The operations service defines each business operation once, with a schema and an authorisation rule, and the gateway projects that registry as a REST API, an MCP server and, later, WebMCP tools. All three share one definition, so an agent gets the same behaviour whichever path it takes.

Gateway internals. The gateway is one deployable built as five internal modules that share nothing but the operation registry: a REST adapter, an MCP adapter, a feed generator, a commerce manifest generator, and the registry integration that loads operation definitions, their schemas and their authorisation references. No module holds business logic. A future transport, WebMCP or a new assistant protocol, is a sixth adapter over the same definitions, never a change to an operation.

The operation registry. An operation is a named function with a JSON Schema for input and output, an idempotency rule, an authorisation rule from the security model, a consent requirement, a rate class and a measurement event. Operations are versioned; a breaking change is a new name.

REST conventions. JSON over HTTPS under /api/v1; resource reads are GET and cacheable with ETags; operations are POST to /api/v1/operations/{name}; errors follow RFC 9457 problem details; every response carries the entity ids it drew on, for attribution. An OpenAPI 3.1 document is generated from the registry and published at a well-known path.

API lifecycle. Versioning, deprecation, compatibility and error contracts are stated once under Platform contracts and apply to REST, MCP tools and feeds alike. In short: a breaking change is a new version or a new tool name, a deprecated version serves for 12 months with Deprecation and Sunset headers, and every error is a problem-details document with a stable type and the request's correlation id.

MCP server. One MCP server per deployment, over streamable HTTP per the stateless 2026 specification, with OAuth and client ID metadata documents for authenticated callers and an anonymous tier for public reads. Tools are generated from the registry; resources expose public entities by URL; tool descriptions are written for a model, state side effects plainly, and never contain instructions beyond the tool's purpose. The server advertises a cacheable tool list with a time to live.

The three v1 tools. Prototype 3 ships exactly these, and nothing that moves money or changes an account.

Tool Input Output Side effect Authorisation Consent
search_products query text, optional category and attribute filters, locale, page ranked list of Product summaries with Offer snapshots, entity ids and canonical URLs none public none
check_availability product or service id, optional location, quantity, date window availability status, quantity or slots, lead time, as-of timestamp, source (store or back-office) none; may call a back-office adapter public, rate-limited none
request_quote items with quantities, requester contact, delivery or service details, free-text notes Inquiry id, status, expected response time, a human-readable confirmation URL writes an Inquiry; notifies the business verified caller or validated anonymous with challenge requester consent to be contacted, recorded with the Inquiry

Free-text fields on request_quote are stored as data and shown to staff as untrusted input; they are never forwarded to a model as instructions.

Feeds and manifests. A product feed in the formats Google Merchant Center and the Agentic Commerce Protocol accept, generated from Product and Offer; a Universal Commerce Protocol manifest at /.well-known/ucp describing discovery only, with checkout declared unsupported until a later version. Discovery in assistants, purchase on the site, is the v1 commerce posture.

WebMCP, deferred. When a customer needs in-page tools for a browser agent, the gateway registers the same three operations through the page's model context API behind a feature flag. The schemas, authorisation and events are unchanged; only the transport differs. This ships no earlier than prototype 4 and only on demonstrated demand.

Agent-facing documentation. The OpenAPI document, the MCP tool list and a short human-readable guide at /agents describe how to reach the surface, what identity is accepted and what the rate classes are. llms.txt is not produced; the evidence says nothing reads it.

Security model

The security model is one service with three separate decisions: who is calling, what that caller may do, and whether the person affected has agreed. No surface answers any of the three on its own, and a verified identity never implies permission.

Layer 1: authentication, who is calling. Callers fall into classes established at the edge and confirmed by the security service: anonymous person, authenticated person (customer account), staff, anonymous agent, signed agent (Web Bot Auth signature verified against a published key directory), authenticated agent (OAuth client acting for a person, with the person's identity bound to the token), and first-party service. Signed-agent verification is treated as early-deployment infrastructure built on an IETF Internet-Draft: it is one input, not a trust anchor.

Layer 2: authorisation, what the caller may do. Every operation in the registry carries a rule expressed over caller class, operation, resource and context (amount, quantity, customer relationship). Rules are data, evaluated by the security service, logged with every decision. The v1 matrix:

Operation Anonymous person or agent Signed agent Authenticated person or agent acting for them Staff
Read public content Allowed Allowed Allowed Allowed
search_products Allowed Allowed Allowed Allowed
check_availability Allowed, rate-limited Allowed, higher rate class Allowed Allowed
request_quote Allowed with challenge and contact validation Allowed with contact validation Allowed Allowed
Create order (v2) Not allowed Not allowed Requires explicit per-order approval by the person Allowed within role
Modify customer account Not allowed Not allowed Restricted to the account holder, step-up authentication Restricted by role, audited
Payment or transfer Not allowed Not allowed Never on identity alone; explicit authorisation per transaction by the account holder through the payment provider Not allowed

Enforcement and failure model. The decision API is a contract, not advice. Every call to it carries the tenant id, caller class and identity reference, operation name and version, resource ids, a correlation id and, for writes, an idempotency key. Every decision returns allow, deny or challenge, the policy version evaluated, an expiry, and any obligations (consent required, step-up authentication required). The rules below are enforced by the gateway and the operations service, and the agent harness tests each one.

  • Fail closed. If the security service is unreachable or exceeds its 250 ms budget, every write operation and every read of private data is refused with a 503 problem-details response and a Retry-After header. Nothing is queued for later execution.
  • Public reads continue. search_products, public entity reads and page rendering follow the published-content policy, which has no per-caller component, under the edge rate limits. This is the only fallback path and the policy names it as such.
  • Cached decisions. A decision may be reused only within its expiry (default 60 s for reads, never for writes) and only for the same tenant, caller, operation, resource and policy version.
  • Policy versioning and propagation. Rules are versioned data. Publishing a new version invalidates every cached decision of the old one within 10 s; the version is logged with each decision and returned to the caller.
  • Tenant isolation. The tenant id is a mandatory attribute of every decision. A request whose tenant context does not match the resource's tenant is denied before any rule is evaluated.
  • Resource ownership. Every operation that names an entity id checks that the entity belongs to the request's tenant and, for private records, to the caller's account or delegation scope. An id outside that scope yields not found, never forbidden, so ids cannot be enumerated.
  • Idempotency and replay. Every write carries an Idempotency-Key scoped to tenant and caller and kept for 24 hours; a repeat returns the first result without re-executing. Signed-agent requests are rejected when the signature timestamp is older than 5 minutes or the nonce has been seen.
  • Correlation. One correlation id is minted at the edge, travels in every call, decision, event and log line, and is returned in every response header, so an audit entry, a measurement event and a trace join on it.

Layer 3: consent, whether the affected person has agreed. Operations that store or use personal data, contact a person, or act on their account carry a consent requirement. Consent is captured on a first-party screen the human site renders, recorded with purpose, timestamp, scope and the regulation it satisfies (GDPR, India's DPDP, others as configured), and referenced by id from the Inquiry or account. An agent cannot grant consent on a person's behalf; it can only bring the person to the consent screen. Withdrawal is an operation like any other.

Agent delegation. An agent acting for a person holds a token scoped to named operations, a resource set and an expiry, issued when the person authorises the agent on a first-party screen. The token's scope is enforced by the authorisation layer; the person can list and revoke delegations.

Prompt-injection and untrusted text. All content the platform renders or receives, including store content authored by customers, user-generated text, assistant messages and tool outputs, is untrusted with respect to any model call. The generative layer uses a fixed system prompt, passes content only as clearly delimited data, restricts tools to the registry, requires confirmation for any side-effecting operation, and renders only catalog components. The human site sanitises user-generated content, strips hidden text and off-screen styling in rendered submissions, and sets a Content Security Policy that blocks inline script. Both sides follow the OWASP Top 10 for LLM applications, in particular prompt injection, excessive agency and improper output handling.

Abuse controls. Rate classes per caller class and operation; cost budgets per session for model calls; anomaly alerts on agent request volume per entity; challenge rather than block for unsigned agents on write operations; a kill switch per operation.

Secrets and keys. Secrets live in the platform's secret manager and never in the repository or the store; back-office adapter credentials are per customer and per adapter; key rotation is scheduled; the MCP server and the OpenAPI document never expose adapter details.

Audit. Every authorisation decision, consent event, delegation, write operation and staff action is written to an append-only audit log with tenant id, correlation id, caller class, identity reference, operation, resource ids, policy version and outcome. The log is exportable and retained per policy.

Residual risks accepted for v1. Bot classification is imperfect and vendor-specific; signed agents are a draft standard; indirect injection against third-party assistants reading the site cannot be prevented by the site, only not amplified. These are recorded, not hidden.

Request flow: an assistant files a quote request

The flow below is the shape every side-effecting operation follows: the edge labels, the gateway validates, the security model decides, the operations service executes, and anything that needs a person's agreement stops and hands off to a first-party screen.

Request flow: an agent can file a quote request, but only the person can grant consent
Request flow: an agent can file a quote request, but only the person can grant consent

Steps 1 to 7 complete without a person: the agent gets an Inquiry id in the state AWAITING_CONSENT and a confirmation URL within one call. The business is not notified and no staff member sees the request until step 10. Steps 8 to 10 cannot be performed by the agent at all: the requester opens the confirmation URL on the human site, proves control of the contact channel, grants consent, and only then does the Inquiry become SUBMITTED and the business notified. The same shape applies to a read operation with steps 5 to 7 only, and to a future order operation with an additional approval screen in place of the consent screen.

Inquiry lifecycle. A quote request is a small transactional workflow, not a form submission. The states are closed, the transitions below are the only ones, and each transition is an audited operation with its own event.

State Entered when Who acts next Leaves to
DRAFT A partial inquiry is saved by the human site's form, or by a future multi-call agent flow; v1 request_quote skips this state The requester or caller completes it, or it expires AWAITING_CONSENT, EXPIRED
AWAITING_CONSENT request_quote has validated and stored the line items and issued a confirmation URL; no notification is sent The requester, on the human site SUBMITTED, EXPIRED, WITHDRAWN
SUBMITTED The requester has proven the contact channel and granted consent; the business is notified; the lead event is emitted Staff ACKNOWLEDGED, REJECTED, WITHDRAWN
ACKNOWLEDGED Staff have opened the request and set an expected response time Staff CLOSED, WITHDRAWN
CLOSED A quote was sent or the request answered or declined; terminal Nobody None
EXPIRED The 72-hour draft or consent window passed; terminal; personal data erased after 30 days Nobody None
WITHDRAWN The requester withdrew through the withdrawal operation; terminal; personal data erased Nobody None
REJECTED Staff rejected the request as spam or out of scope; terminal; counted in abuse metrics Nobody None

Lifecycle rules. A confirmation URL is a single-use bearer capability: a 128-bit random token bound to one Inquiry and one tenant, valid for 72 hours, revoked on use, withdrawal or expiry, and never containing the Inquiry id. It is returned to the agent and also sent to the requester's stated contact channel. Control of the channel is proven when the consent screen is completed from a link or one-time code delivered to that channel (email magic link, or a code by SMS), so an agent that invents a contact address cannot complete the request. A repeat of the same tenant, normalised contact and line items within the 72 hours returns the existing Inquiry rather than creating another, and an Idempotency-Key on the call does the same exactly. A withdrawal operation exists for every non-terminal state. Expired and withdrawn inquiries keep only id, tenant, state and timestamps after erasure, so counts stay right while personal data does not.

Generative UI catalog

The generative layer composes; it does not generate. A model selects and arranges components from an approved catalog and fills their typed slots with data drawn from operations; it never emits HTML, JavaScript, styles or code. This is the production pattern Google's A2UI, Vercel's json-render, Apps in ChatGPT and MCP Apps converged on, and it preserves brand, trust signals and security by construction.

Catalog contract. The catalog is a versioned registry of components, each with a name, a JSON Schema for its props, a list of allowed child components, the data sources it may bind to (operations or entity types), an accessibility contract (roles, labels, keyboard behaviour) and a rendering cost class. The v1 catalog is deliberately small:

Component Purpose Binds to Side effects
Answer A short direct answer with cited facts Document blocks, cited facts none
ProductCard, ProductList Present products with offers search_products results none
ComparisonTable Compare items on attributes Products, attribute schemas none
FeatureMatrix Capabilities by item or plan Products, Services none
PricePanel Offers with conditions and validity Offers none
AvailabilityBadge Stock or slots as of a time check_availability none
CaseStudy A document summary with a link Documents none
FAQ Question and answer pairs FAQ documents none
ActionButton A named next step Operations and routes opens a form or hand-off screen; never performs the operation itself
EscalateToHuman Visible route to a person Contact operations opens a contact or booking flow
Disclosure States that the user is talking to AI and labels generated content Entity flags none

Composition protocol. The model returns a composition document: a tree of catalog component references with props. The protocol is declarative JSON in the style of A2UI or json-render, and the model never talks to React. Every turn passes through one fixed pipeline, and a failure at any stage falls back to the conventional page or a plain Answer component: model output, then a JSON parser that accepts exactly one document, then the schema validator (catalog schemas; unknown components and invalid props rejected), then the composition policy validator, then the renderer in the human site that maps the validated tree to real React components. Streaming is supported component by component, and each streamed component passes the same stages before it renders.

Composition policy. Schema validity is not enough; a valid tree can still be too large, misleading or unsafe. The policy validator is a separate module with its own tests and per-deployment limits. It enforces:

  • Structure. Tree depth at most 4; at most 12 components per turn; at most 2 list or table components per turn.
  • Text. At most 600 characters per text slot and 2,500 per composition; no raw HTML, SVG, CSS, style props or Markdown with embedded HTML anywhere, including inside strings.
  • Navigation. Every URL resolves to a store entity's canonical URL, a registered route or a hand-off screen; external destinations only from a cited-fact source; no javascript:, data: or protocol-relative URLs.
  • Visibility and accessibility. No component may be hidden, collapsed by default, zero-sized or placed off-screen; props that would break a component's accessibility contract (an image without alt text, a button without a label) are rejected.
  • Data binding. Every data-bound prop references an operation result or entity id present in the turn's tool results. A price, availability figure, lead time or date without a source reference is rejected and the turn falls back rather than rendering it.
  • Disclosure. The first composition of a session contains a Disclosure component and no later turn removes it.

A rejection is a composition event carrying the rule that failed, so the dashboard shows which policies bind in practice.

Industry and role composition. A composition policy, not a layout, decides which components and which attribute sets lead for a given industry, role or customer segment. The same catalog serves a garment manufacturer and a furniture maker with different leading components and attributes; the policy is data in the store, editable without a deployment. This is the personalised-composition opportunity from the study, built as configuration from day one.

Guardrails. Fixed system prompt per deployment; tools restricted to the registry and further to read operations unless the person confirms a write; every composition passes schema validation and then the composition policy; every side effect routes through an ActionButton to a first-party screen; outputs that cite facts must cite store entities, and uncited numbers are rejected; a Disclosure component is always present in the first response of a session.

Cost and latency budgets. Per session: a model-cost ceiling set per deployment (v1 default $0.10) and a hard stop with graceful fallback when reached; prompt caching of the system prompt, catalog description and policy prefix; at most two tool round-trips per turn by default. Per turn: first component within 1.5 s, full composition within 5 s at the 75th percentile; a turn that exceeds 8 s falls back. Cost and latency are emitted as events and shown on the measurement dashboard beside conversion.

Model independence. The layer talks to models through one adapter interface with capability flags (tool use, streaming, caching). Switching provider or model is a configuration change and a regression run against a fixed set of composition test prompts, not a code change.

Fallback. The conventional page is always complete without the generative layer. When the layer is unavailable, over budget, fails validation or is declined by the user, the page shows the conventional interface with no loss of function. The fallback path is tested in continuous integration by running the suite with the layer disabled.

Edge policy

The edge classifies every request, verifies agent identity where offered, applies the crawler policy, negotiates Markdown, enforces rate classes and logs violations, then passes a labelled request downstream. It makes allow, block or challenge decisions only; authorisation belongs to the security model.

Internal responsibilities. The edge runs as one Cloudflare deployment but is built as six modules, each with its own contract and tests, so that none grows into the others: traffic classification (the label and its confidence), crawler policy (robots.txt, Content Signals, allow and disallow), request negotiation (Markdown and locale), rate limiting (classes, burst and sustained limits, the kill switch), agent identity verification (Web Bot Auth), and edge event collection (violations, classification and rate events to the measurement service). Monetisation hooks belong to crawler policy and rate limiting together and stay off by default.

Traffic classes. Each request is labelled with one of: human browser, search crawler, training crawler, user-directed agent fetch, autonomous agent, monitoring, unknown bot. Classification uses the CDN's bot management, published user agents and IP ranges from OpenAI, Anthropic, Google and others, Web Bot Auth signatures where present, and behavioural signals. The label and its confidence travel downstream in a request header and into every measurement event. The classes mirror Cloudflare's search, training and agent split because that is the de facto control model, with the explicit caveat that it is one vendor's classification.

Default policy. Search crawlers allowed; training crawlers disallowed by default and allowed per customer decision; user-directed agent fetches allowed, because they serve a person; autonomous agents allowed on read operations and challenged on writes; unknown bots rate-limited and challenged on writes, never blanket-blocked, since a blanket block now costs real visitors. Customers change the defaults in configuration, and the configuration generates every artefact below so they cannot drift apart.

Crawler signals, generated from one configuration.

  • robots.txt with per-bot rules for GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended, CCBot and others, maintained as a list in the store.
  • Content Signals directives (search, ai-input, ai-train) in robots.txt, and an AI Preferences Content-Usage rule and header once the IETF drafts settle, both from the same configuration.
  • Optional Really Simple Licensing terms where a customer wants to state licence or compensation terms.
  • Guidance, not automation, for the Google Search Console opt-out from AI Overviews and AI Mode, since it is a console setting the customer must flip.

Signed agents. Where a request carries a Web Bot Auth signature, the edge verifies it against the agent's published key directory, labels the request as a signed agent with the agent's name, and applies the signed-agent rate class. A verification failure downgrades the request to unknown bot; it does not block.

Violations log. Requests from identified crawlers to disallowed paths, requests that evade declared user agents, and verification failures are logged with agent, path, time and count, and surfaced on the measurement dashboard. The log is evidence for licensing conversations and for deciding whether to escalate a bot to a block.

Markdown for agents. Requests with Accept: text/markdown receive the Markdown rendering described under the human site, with Vary: Accept and the same cache keys. Whether the conversion runs at the edge or in the site is an open decision; the edge owns the negotiation either way.

Monetisation hooks. The edge supports returning HTTP 402 with pricing for designated paths and caller classes, so a customer can take part in pay-per-crawl or pay-per-use schemes when they choose. This is off by default and recorded as an option, not a recommendation, until the economics of agent access are better understood.

Rate classes. Per caller class and operation, with burst and sustained limits, surfaced in response headers; writes are challenged before they are limited; a per-operation kill switch is reachable without a deployment.

What the edge never does. Hold content, make authorisation decisions, run a model, or strip the provenance metadata from media it serves.

Measurement framework

Measurement answers one question for every R&D investment: did it produce business value? It records human visits, agent sessions, assistant citations and conversions as events in one model, joined on entity ids and operation names, so a change in content or in an agent tool can be followed through to leads and customers.

Event model. Every event carries: timestamp, deployment, traffic class and confidence from the edge, caller identity reference (never raw personal data), surface (human site, REST, MCP, WebMCP, generative layer), operation or page, entity ids touched, session id, outcome, and cost where a model was involved. Events are typed and versioned like entities. The v1 event types:

Event Emitted by Key fields
page_view Human site entity ids, referrer class (search, assistant, direct, other), landing or not
markdown_fetch Edge or human site entity ids, agent name if signed
operation_call Gateway operation, surface, caller class, outcome, latency
composition Generative layer components used, tool calls, tokens, cost, latency, fallback or not
lead Operations service Inquiry id, kind, source session, source surface
conversion Operations service or back-office adapter Inquiry or order id, value, first-touch and last-touch sessions
citation_observed Citation probe assistant, query, cited URL and entity id, position, date
crawl_violation Edge agent, path, rule violated
consent Security model purpose, scope, granted or withdrawn

Bot classification join. Every event carries the edge's traffic class, so dashboards separate human, search, training, user-directed agent and autonomous agent activity by default. Agent sessions are counted apart from human sessions; crawl-to-referral and crawl-to-lead ratios are computed per agent operator.

Attribution. Referrer class is derived from referrer, UTM parameters, known assistant link patterns and, for agents, the signed identity or operation path. Because assistants often strip referrers, a session with no referrer that begins on a deep page within minutes of a citation_observed for that page is attributed as assistant-likely, with the confidence recorded. Leads and conversions record first-touch and last-touch sessions and the entity ids involved.

Citation probe. A scheduled job runs a fixed set of queries per deployment against five assistants weekly, records which URLs are cited and in what position, and maps them to entity ids. The query set is versioned so changes in results are not confused with changes in queries. This is the basis for the citation-shaped content experiment and for the AI website intelligence product.

Holdouts. Every prototype ships with a holdout: a share of sessions, pages or entities that do not receive the change. Composition against navigation, citation-shaped against conventional pages, and agent tools against the HTML path are all measured as differences against their holdouts, not as before-and-after.

Dashboards. Four views in v1: discovery (citations, assistant-attributed sessions, search sessions), agents (sessions by operator, operations by tool, crawl-to-lead ratios, violations), experience (composition usage, cost per session, latency, fallbacks) and business (leads, conversions, value by source). Each view can be filtered by entity, so a product manager can ask what a given product earned from assistants.

Privacy. Events hold identity references, not personal data; raw IPs are not stored; retention is per policy and per regulation; exports strip identity references unless the requester is authorised. The measurement store is subject to the same export guarantee as the content store.

Definition of done for a prototype. A prototype is complete when its hypothesis has a measured difference against a holdout, its cost and latency are on the dashboard, and the result is written back into the study as a confirmed, refuted or inconclusive finding.

Platform contracts

The component sections say what each part owns. The contracts below say how every part behaves on the matters that cut across them. The Architecture Contract Pack turns each into a schema, an interface or a test, and a package that breaks one needs a decision record.

Area Contract
API lifecycle REST under /api/v1 and MCP tools are versioned by path and by tool name; a breaking change is a new major version or a new tool name, never a changed one. A deprecated version serves for 12 months with Deprecation and Sunset headers and an entry in the OpenAPI document. Additive changes (new optional fields, new tools) are compatible; removing or retyping a field, tightening validation or changing an authorisation rule is breaking. Errors are RFC 9457 problem details with a stable type URI per error class, the correlation id and, for validation errors, a per-field list.
Tenant isolation Tenant id on every row, event, cache key and export; row-level security in Postgres; tenant context from the deployment or host name, confirmed by the security model; cross-tenant access denied by default. See Tenant context under Content store.
Data lifecycle Retention per data class as the Data classes table states. Erasure requests are honoured within 30 days across the content store, operations, security records and measurement, with the audit log keeping the fact of erasure. Archival is an export to the customer's object storage. Backups are nightly full plus continuous write-ahead, encrypted, kept 35 days.
Reliability Every outbound call has a timeout (store 500 ms, security 250 ms, back-office adapters 3 s, model provider per the turn budget). Retries only on idempotent calls, at most twice with jitter. A circuit breaker per back-office adapter and per model provider opens after 5 failures in 30 s and serves the fallback (cached availability with its as-of time; the conventional page). Recovery is observed by half-open probes, not assumed.
Observability Structured JSON logs, OpenTelemetry traces and metrics from every service; correlation id and tenant id on every log line, span and event; no personal data in logs; one trace from edge to store for every operation call; service-level objectives per surface, with the performance budgets as the human site's.
Search Full-text and vector indexes are derived from published versions and rebuildable from the store on demand. Indexing is triggered by change events and completes within 60 s. Ranking is per tenant and per locale, with the analyser chosen from the version's locale. Results carry entity ids and versions, so a stale hit is detectable.
Caching Cache keys include tenant, locale, surface and Accept. Invalidation by change event for published content, by time to live for business data, never beyond the request for live operational data, as the freshness tiers below state. Stale-while-revalidate only for the static tier.
Webhooks Outbound events to customer systems are signed (HMAC with a per-endpoint secret and a timestamp), delivered at least once with exponential retries over 24 hours, carry an event id for idempotent consumption, and are listed with delivery status per tenant.
Media pipeline Upload to quarantine storage, malware scan, type and dimension validation, transformation into named variants, Content Credentials verified on entry and re-signed after each transformation, then promotion to serving storage. A variant that cannot carry its credentials is not produced.
Disaster recovery Recovery point objective 15 minutes; recovery time objective 4 hours per deployment. A restore from backup into a fresh environment is exercised quarterly and before every major release, and the export round trip is run against the restored store.

Freshness tiers. Availability is not content. A product description can be cached for hours; stock can be wrong within seconds. Every field and every operation result belongs to one tier, and no cache or surface may treat a lower tier as a higher one.

Tier Examples Cache policy Carries
Static published content Descriptions, documents, policies, media, JSON-LD, Markdown Cached at the edge until a change event invalidates it; stale-while-revalidate allowed Entity version
Frequently changing business data Prices and offers, opening hours, lead times, feed files Time to live of 5 minutes or less, set per field; invalidated on publish Version and as-of time
Live operational data Stock and slot availability, order status, rate-limit state Never cached beyond the request, except a 30 s adapter cache that returns its as-of time and source; surfaces display the as-of time As-of time and source

Technology choices and repository layout

The stack is chosen for one team to build six prototypes quickly against one set of contracts, with every choice replaceable behind an interface. Each decision below names the alternative considered and the condition under which the team would switch.

Concern Choice for v1 Alternative considered Switch when
Language TypeScript end to end Python for services Never for v1; one language keeps schemas and types shared
Human site Next.js (App Router), server rendering, React Astro, Remix Next.js is the team's existing stack; revisit only if JavaScript budget cannot be met
Content store Postgres with a relational core and JSONB attributes; Drizzle for schema and migrations; object storage for media A headless CMS (Payload, Sanity) A CMS would own the schema and the export; revisit if authoring UX becomes the bottleneck after prototype 1
Schemas JSON Schema as the source of truth, TypeScript types and Zod validators generated from it Zod-first JSON Schema is what MCP, OpenAPI and the catalog all consume natively
Operations and gateway A Node service exposing REST via a generated OpenAPI 3.1 document and MCP via the official TypeScript SDK tRPC, GraphQL Agents and assistants consume REST and MCP; GraphQL adds a surface agents do not use
Identity OAuth 2.1 with client ID metadata documents for agents; passkeys and magic links for people; a hosted identity provider behind an adapter Rolling our own Never roll our own
Edge Cloudflare: bot management, AI crawl controls, Web Bot Auth verification, Markdown for Agents, WAF, cache Vercel edge, Fastly Cloudflare is where the agent-traffic controls and the signed-agent class already exist
Generative layer Vercel AI SDK for model calls and streaming; json-render or A2UI-style declarative composition; provider adapter with Claude as default model Direct provider SDKs Keep the adapter so that model choice is configuration
Measurement Event ingestion into Postgres (v1) with ClickHouse as the planned warehouse; dashboards in Grafana or a thin internal UI A product-analytics SaaS A SaaS cannot join on entity ids and traffic classes the way the framework requires
Hosting Vercel for the human site; Cloudflare Workers or a container host for the gateway and services; managed Postgres Single container host Split if cold-start latency on the MCP server exceeds budget
Testing Playwright for the human path, an agent harness driving at least three browser agents and one MCP client through the five-task set ten times each and recording completion, incorrect actions, interventions and time, axe-core for accessibility, k6 for rate classes Manual agent testing Never manual; the agent harness is the acceptance test

Environments. Local, preview per pull request, staging with synthetic data and a staging deployment of every surface including the MCP server, and production per customer deployment. The citation probe and the agent harness run against staging and production on schedule.

Repository layout. One monorepo, package per component, so that a contract change is one pull request across all its consumers.

sysbot/
  apps/
    web/            Next.js human site, catalog renderer, consent and hand-off screens
    gateway/        REST and MCP projection of the operation registry, feeds, manifests
    probe/          citation probe and agent harness (scheduled jobs)
    dashboard/      measurement views
  packages/
    schema/         JSON Schemas, generated types and validators, Schema.org mapping
    store/          Postgres access, versioning, provenance, export
    operations/     operation registry, the v1 operations, back-office adapters
    security/       authentication adapters, authorisation rules engine, consent, audit
    catalog/        component catalog definitions, composition protocol, policies
    generative/     model adapter, composition engine, budgets, caching
    edge/           Cloudflare configuration, robots and signals generator, rate classes
    events/         event schemas, emitters, ingestion client
  docs/
    research/       the study (exported)
    architecture/   this document (exported) and decision records

Conventions. Conventional commits; architecture decision records as numbered Markdown files under docs/architecture/decisions; every package exposes its contract as types and schemas and hides its implementation; continuous integration runs type checks, schema compatibility checks, accessibility scans, performance budgets, the fallback suite with the generative layer disabled, and the agent harness on staging.

Licensing and export. Everything generated from the store, including JSON-LD, Markdown, feeds and the OpenAPI document, is the customer's. The repository's own licence is an open decision.

Prototype mapping

Each prototype in the study's roadmap exercises a defined subset of this architecture and leaves behind a component the next one depends on. A prototype may stub a component it does not exercise, but it may not bypass a boundary.

Prototype Exercises Stubs or omits Leaves behind Gate to the next
1. Dual-audience reference site Content store (all nine entities), schema package, human site with JSON-LD and Markdown negotiation, edge in default policy, export Operations beyond a contact form; security model beyond anonymous and staff; generative layer; measurement beyond page views A real reference implementation with catalogue, pricing, FAQs, forms and a round-tripping export At least three browser agents run five predefined tasks ten times each (150 executions) with completion, incorrect-action, human-intervention and execution-time rates reported; completion above 80% and no data-changing incorrect action; accessibility scan clean; Markdown under a quarter of HTML tokens
2. Agent and citation analytics Edge traffic classes and violations log, event package, measurement ingestion, attribution, citation probe, dashboards Operations service; generative layer Dashboards that separate human, search, training and agent traffic and attribute leads; a weekly probe Dashboard live on the reference site and on at least one real Sysbot client site for four weeks
3. Agent surface Operations service with the three v1 operations, gateway (REST and MCP), security model layers 1 to 3 for those operations, feeds and the discovery-only manifest, agent harness WebMCP; any write beyond request_quote; payments A working MCP server and OpenAPI document any assistant can use; the authorisation matrix enforced Task completion and steps per task for tool path versus HTML path; hand-off in one screen; no authorisation bypass found by the harness
4. Catalog-constrained generative UI Catalog package (v1 components), composition protocol, generative engine with budgets and caching, policy-based industry composition, Disclosure and EscalateToHuman, fallback suite Free-form generation; WebMCP unless a customer has asked A conversation panel on the reference site composing from the catalog, with cost and latency on the dashboard Holdout difference on comparison tasks; cost per session under ceiling; median turn under five seconds; fallback suite green
5. Citation-shaped content (parallel with 2) Document blocks including cited facts, page templates built to close, citation probe Everything else Ten matched content pairs, equivalent facts with controlled presentation differences assigned at random, and a measured citation difference Runs for four weeks alongside prototype 2; result written back to the study
6. Policy and compliance kit (on demand) Edge configuration generator, robots and signals, consent capture, Article 50 disclosure, Content Credentials pipeline check New operations or surfaces A configuration-driven kit applied to a paying client site Only started once a customer has asked; applied with no manual steps beyond configuration

Order of construction. The foundation is built before the AI layer, so that every later component lands on contracts that already exist. The order below replaces the earlier one (schema, store, site, edge) and cuts across the prototypes: a prototype may start only when the deliverables it depends on exist. The export round trip is still the first test written.

Phase Deliverable Why in this position
1 Tenant-aware schema package, including the measurement event schema Establishes every contract; retrofitting tenant ids and event identifiers is the most expensive change to make later
2 Content store with versioning, locales and the export round trip Establishes the source of truth
3 Human site with semantic HTML and JSON-LD, edge in default policy Proves the content model against real pages
4 Operations registry and security foundation: decision API, tenant context, fail-closed behaviour, audit Establishes safe business actions before any transport exposes them
5 REST and MCP gateway Exposes the operations
6 Measurement ingestion and citation probe Establishes evidence on the events defined in phase 1
7 Generative UI with the composition policy validator Adds AI composition once the foundation works
8 Edge policy hardening Adds finer traffic controls over the defaults set in phase 3
9 Compliance kit Built when customer demand justifies it

What no prototype may do. Store content outside the store; execute an operation or a query without a tenant context; define an operation outside the registry; implement an authorisation check outside the security model; emit generated markup; ship without a holdout and without events on the dashboard.

Open decisions

Twelve decisions are still open. Each has a default the prototypes will follow until a decision record changes it, and a prototype named as the point at which it must be settled.

Id Decision Default for now Settle by Why it is open
ADR-001 Where Markdown negotiation runs: edge conversion or site rendering Site renders Markdown from blocks; edge negotiates and caches Prototype 1 Edge conversion is cheaper to adopt; site rendering is exact and preserves cited facts
ADR-002 Composition protocol: json-render, A2UI, or a Sysbot schema Settled at prototype 4 (ADR-021): a flat json-render-style document whose props carry entity ids, emitted through a compose tool, with an A2UI export left as an adapter Prototype 4 Both are young; the catalog contract is ours either way
ADR-003 Default model and provider for composition Settled for v1 at prototype 4 (ADR-021): Claude Sonnet 5.5 via the adapter, prompt caching on; cost and latency measured in the prototype 4 report Prototype 4 Cost and latency per turn decide it, measured on the dashboard
ADR-004 Identity provider for people Hosted provider with passkeys behind the security adapter Prototype 3 Build-versus-buy on account features customers may need
ADR-005 Signed-agent trust: how much weight to give a verified signature Settled at prototype 3 (ADR-005): a verified signature admits a write, which stops at awaiting consent; only the person completes it, or a delegation they granted Prototype 3 Web Bot Auth is an Internet-Draft; the directory of agents is self-published
ADR-006 Commerce manifest scope: discovery only, or checkout in v2 Discovery only; checkout on the merchant site After prototype 3 and real agent volume Agentic checkout adoption is negligible as of Oct 2026
ADR-007 Warehouse for measurement: stay on Postgres or move to ClickHouse Postgres until event volume or query latency forces the move Prototype 2 review Depends on real client traffic
ADR-008 Multi-tenancy: one deployment per customer or shared with tenant isolation One deployment per customer for prototypes; tenant context is mandatory either way (ADR-014) Before the first paying AI-ready website Isolation and export are simpler per customer; cost favours shared
ADR-009 Back-office adapter boundary: synchronous calls or a synced replica for availability Synchronous with a cache and an as-of timestamp Prototype 3 Depends on customers' ERP and inventory systems, including OnFleek
ADR-010 Pricing machine access: whether and when to enable HTTP 402 on agent paths Off; log and measure first After the agent economics research gap is addressed No settled evidence on who pays for agent traffic
ADR-011 Consent framework coverage: GDPR and DPDP in v1, others later GDPR and India's DPDP rules modelled; others by configuration Prototype 3 Sysbot's first customers determine the jurisdictions
ADR-012 Repository licence and what, if anything, is open-sourced Proprietary; schema package and catalog contract candidates for open source Before any external contributor Open contracts could attract integrations; the operations and security packages stay closed

How a decision is made. A numbered record under docs/architecture/decisions stating context, options, decision, consequences and the prototype evidence that informed it. A decision changes this document in the same pull request.

Decisions already taken by this document. One store with typed schemas; operations defined once and projected; three separate security layers; composition from a catalog, never generation; the conventional interface as the always-present fallback; events joined on entity ids; full export as a release gate; no llms.txt; no payments in v1. Added by the engineering review of 30 Oct 2026 and recorded as ADR-013 to ADR-018: five data classes with one canonical content store; mandatory tenant context; fail-closed authorisation; the Inquiry lifecycle with first-party consent; a composition policy validator between model and renderer; freshness tiers for cached data. Added by prototype 3 (31 Oct 2026) as ADR-019: operations defined once in a registry and projected to REST and MCP by one invoke pipeline, hosted in the web app until Postgres; and ADR-005 settled as above. Added by prototype 4 (31 Oct 2026) as ADR-021 and ADR-022: the composition protocol (a flat json-render-style document whose props carry entity ids, emitted through a compose tool, with business-tier facts primed as cached prompt prefix), settling ADR-002 and ADR-003; and the generative layer as a first-party signed agent that reads on the visitor's session and writes only by signing a form the visitor sent, which stops at awaiting consent.

Review changes

The engineering review of 30 Oct 2026 kept the architecture and asked for six changes before the document could serve as an implementation baseline. All six are made in this draft.

Change asked for Where it landed
Distinguish the canonical content store from supporting operational data Principle 1 reworded; Data classes and Tenant context under Content store
Define the Inquiry lifecycle and consent hand-off Inquiry lifecycle and Lifecycle rules under Request flow; InquiryItem in the entity model
Make tenant isolation mandatory from day one Tenant context under Content store; Tenant isolation under Platform contracts and Security model; ADR-008 narrowed to the hosting question
Strengthen the security decision and failure model Enforcement and failure model under Security model
Define API, event, caching and data lifecycle contracts New section Platform contracts, with freshness tiers
Add composition policy validation between the model and the renderer Composition protocol pipeline and Composition policy under Generative UI catalog

Also from the review: the edge policy and the agent gateway are split into named internal responsibilities; the performance budgets state their measurement conditions; nine further entities are added or explicitly deferred; multilingual content is in the schema; the order of construction builds the foundation before the AI layer. The next artifact is the Architecture Contract Pack, not another strategy paper: JSON Schemas, TypeScript interfaces, operation definitions, event schemas, security policy contracts and decision records ADR-013 to ADR-018, built from this document.

Research in practice

Building toward this architecture?

We build the pieces of it for clients: content stores, agent surfaces, edge policy, catalog-constrained interfaces. Write with the problem and we reply within one business day.