Architecture Blueprint (Schema)

This page is the public architectural map of Adaptive Experience Architecture. It defines how the core components connect, how customer interactions are validated, and how responsibilities are divided.

In Plain English: When an AI assistant helps a shopper, it shouldn't be an unconstrained chatbot making up answers. This blueprint shows the scaffolding that wraps around the AI: checking real store databases, executing a strict 4-step loop (Interpret → Act → Verify → Remember), and using specialized quality checks to prevent mistakes.

Formula · Six layers · The loop · Agent coordination · Decision layer · Agentic workflows · Team roles · Journeys · Stack

The Core Formula

Adaptive Experience = Shared Understanding + Domain Services + Outer Harness.

• Shared Understanding: The session's live digital notepad. It captures what the customer wants (the recipient, occasion, budget, and card message) in a structured format both the shopper and the store can inspect.
• Domain Services: The authoritative backend systems. They validate stock in the cooler, calculate delivery fees, charge cards, and create real orders.
• The Outer Harness: The automated safety net. It wraps around both the conversational AI and the databases to ensure transactions are reliable and honest.

The Golden Rule: AI may interpret customer intent, but domain services always make the decisions. Status claims require empirical proof. Formal IDs (FR/ADR) already exist in docs/; this page does not invent them.

The Six Layers

The outer harness wraps around domain services and shared understanding across six functional layers:

1. Guides (Playbooks & Rules): Explicit instructions and guardrails loaded before work starts, defining what actions are permitted and who owns which surface.
2. Sensors (Smoke Alarms): Automated tests and checks that observe state and detect errors before customers encounter them.
3. Loop (Execution Cycle): The repeatable pattern for every transaction: interpret intent, take an action, verify the result, and remember the agreed state.
4. Memory (Persistent Context): Structured storage that keeps customer selections, carts, and occasions intact across page reloads without amnesia.
5. Permissions (Access Control): Strict security controls ensuring only authorized services can modify inventory, process funds, or touch code.
6. Observability (Hard Evidence): Real-time telemetry and telemetry dashboards. If a claim has not been tested, it remains labeled Unknown.

The Execution Loop

Every interaction between a customer and the system follows a disciplined 4-step cycle:

Agent coordination (Harness / Loop / Graph)

Path B / Lily's Florist remains the product case study on this site. This section is about how AEA agents and the Outer Harness operate when work is multi-step or multi-role — vocabulary adopted via Keep Learning from an external agent-OS article (0xwhrrari, 2026-09-03). It is not a product endorsement of any vendor Bot feature, and it invents no FR/NFR IDs. Status until Pages probe: Documented.

External writing often names three control layers around a model: Harness (environment), Loop (improvement), Graph (coordination), plus an approval boundary. AEA already owns those jobs inside the six Outer Harness layers — this map makes the correspondence explicit:

Adopted thin vocabulary (see Glossary):

1. Autonomy ladder (0–4) — Observe → Prepare → Execute-with-approval → Schedule-or-trigger → Coordinate-specialists; promote by evidence, demote on degradation.
2. Approval by reversibility — finish reversible work; park send / publish / purchase / delete / production / legal.
3. Handoff packet — compact from / to / objective / artifacts / decisions / constraints / open_questions / next_gate (not full transcripts).
4. Account connection ≠ role authority — plumbing is not permission.
5. Independent checker — builder ≠ verifier (same spirit as MRC vs implementer).

Multi-agent work is a graph: specialists own lanes; a coordinator owns intake, routing, and escalation; handoff packets pass ownership. Do not grow the graph for spectacle — add a specialist when context noise, weak self-review, or divergent permissions create a real bottleneck.

Decision layer (typed judgments)

Path B / Lily's Florist remains the product case study. This subsection adopts thin vocabulary from external decision-model writing (Codila, 2026-09-18; related public TypeSafe System One / Jev framing) via Keep Learning — not an endorsement, not a Path B runtime dependency, and not runtime code in this docs change. Status until Pages probe: Documented. Implementation, if ever warranted, is separate GitLab issues (1 finding → 1 issue).

Thinking vs deciding vs executing

Adopted thin vocabulary (see Glossary):

1. Decision layer — named surface separate from generative text.
2. Typed decision (Choice · Score · Gate) — constrained answer shapes; Gate ≈ stop/continue / yes-no probability (external “Noul”).
3. Rebuild option menu — Choice options from current worker/tool/state.
4. Cost per decision — $/completed decision or task, not only $/MTok; vendor demos ≠ AEA evidence.
5. Parallel independent typed questions — when state is shared, fan-out independent judgments (same spirit as Graph: parallelize only independent work).
6. Keep irreversible park list from agent-OS adopt (#441): send / publish / purchase / delete / production / legal.
7. Model-tier Choice (2026-09-21 Keep Learning) — Choice of model tier before spend (Cost Guardian); external ModelRouterMiddleware spirit (LangChain harness-with-Jev). Documented pattern — not Live middleware.
8. AutoMode pre-tool Gate (2026-09-21) — Gate before side-effecting tools; maps to #441 park list; external AutoModeMiddleware spirit. Documented pattern — not Live SDK.
9. Holmberg recipe families (Documented map only; full pack = open #472): second-brain classify/dedupe; content anti-slop/voice Gate; post Score vs history; SEO draft vs SERP Score (Holmberg).

Outer Harness Decision Layer map (Archify) — generate vs decide vs execute (Documented aid — not Live; not a Path B runtime map).

• Open full page after Pages publish: /archify/decision-layer.html (alias of outer-harness-decision-layer.architecture.html) · also /archify/outer-harness-decision-layer.architecture.html · source HTML · IR JSON · README

Explicit rejects: install Jev/TypeSafe as AEA Path B runtime; claim Browser Use $0.0039 (or similar) as AEA evidence; weaken Probe / Honesty / Unknown; invent FR/NFR; claim Live before Pages probe; treat LangChain Typesafe middleware as Path B dependency.

Agentic workflows (Anthropic map)

Path B / Lily's Florist remains the product case study. This subsection maps Anthropic Building effective agents (Dec 2024; X summary pointer slash1sol) onto AEA Outer Harness via Keep Learning (#460–#463) — not an Anthropic endorsement, not a cookbook install, not Path B shop UI, and not runtime code in this docs change. Status until Pages probe: Documented. Does not absorb #441 / #446 flags by being newer.

Workflow vs Agent vs Augmented LLM

Five composable workflows → AEA

Principles that fit AEA honesty

1. Environment ground truth each step → Sensors + Probe / Honesty / Unknown.
2. Measured complexity → When Not to Grow the Harness + cost per decision; prefer simple composable patterns over heavy frameworks.
3. ACI → Guides document tools clearly; Permissions bound what tools may do.

Explicit rejects: install Anthropic/LangChain/etc. agent frameworks as Path B runtime from this learning alone; claim florist UI “is” orchestrator-workers; Live claim before Pages probe; weaken Unknown; invent FR/NFR IDs.

See Glossary — Agentic workflows.

Team Roles and Responsibilities

To keep engineering rigorous, AEA divides responsibilities across 14 specialized lenses (hats) grouped into 5 functions:

• Discovery (3 lenses): UX Designer, Customer Journey Specialist, Support Coordinator.
• Strategy & Delivery (2 lenses): Product Owner, Project Manager.
• Safety & Quality (4 lenses): AppSec Auditor, Cost Guardian, Performance Guardian, Coherence Guardian.
• Builders (3 lenses): Senior Software Engineer, AI Engineer, DevSecOps Platform.
• Governance & Memory (2 lenses): Merge Request Coordinator (MRC), Knowledge Guardian.

Work flows through 3 executable jobs: implement, verify, and merge. To prevent conflicts of interest, the engineer or AI that writes code is never the one who merges it. Only the independent Merge Request Coordinator merges.

Honesty, Knowledge, and Antifragility

• Claims Require Proof: In software, words like verified, shipped, and complete are easy to say. AEA treats them as claims that must be backed by automated test output or physical device probes. A closed ticket or a merged code change is not proof that a feature works on real screens.
• Knowledge First: The project's memory lives in version-controlled repository history and Second Brain notes—not in ephemeral chat windows that disappear when closed.
• Systemic Antifragility: If an error happens twice, it signals a missing automated test or architectural gate—not a need for more discipline or pep talks.

Tested Customer Journeys

We test the live reference shop at aea.artof.link against 4 named customer scenarios:

• J1 Urgent Sam: Same-day rose delivery with rapid checkout.
• J2 Planner Sarah: Advance birthday scheduling with custom card messages, satin ribbon, and vase selection.
• J3 Loyal Alex: Returning shopper whose cart and preferences persist across browser reloads.
• J4 Tracker Chris: Order lookup, delivery tracking, and direct escalation to the florist team.

Related Documentation

• System Stack — How the cloud servers, message bus, and mobile clients connect.
• Path B Case Study — Watch the 30-second recordings of all 4 customer journeys.
• Comparison & Visual Guide — The 5-floor building model and industry comparison.
• Architecture Glossary — Plain-English definitions of terms and concepts.
• Framework Home — Return to the overview.