The Front Door — a Solution in the wild
In plain language
The public intake on matterandgas.com is not a contact form. It is a Solution running on the platform — the same substrate, prompt versions, gateway, ledger and cost accounting a client's Solution uses. A visitor describes their business; the Solution reasons about it in the open, forming a working model of the opportunity beside the conversation, judges fit honestly in words, and, if the visitor asks to be contacted, records a lead that is guaranteed to reach a person. It is included here because you can try it.
The mechanism
Streaming transport. A guest turn arrives through an authenticated
public mutation to the front-door-turn function, which does the fast
control-plane work — session lifecycle, a pending marker, a minted stream
token — and returns immediately. The model wait leaves the request path
and streams through the front-door-stream-relay, which calls the same
capability stream gateway of our API — the same one a client's own
software calls. The visitor sees
the answer arrive as a streamed prefix; the platform records one run, one
cost record and one ledger row at finalisation, exactly as for any streamed
run (ADR-0024).
The presentation contract. The Solution's prompt emits a validated envelope — prose for the visitor, presentation directives (open a panel, update the working model) and state updates — under the conversation component's fail-closed vocabulary; the client is a pure renderer of that envelope. Structured emission is gateway-enforced where the model supports it (ADR-0039).
The working model. As the visitor talks, the platform maintains an
opportunity model beside the conversation: a headline, the current state,
the frictions, the leverage points, the possible system, what is still
unknown, and a fit judgment with its rationale. Fit is one of three words —
strong, unresolved, poor — never a number. A poor fit is said plainly,
with an alternative; the platform does not sell into a bad fit.
Prompt versions are governed content. The Front Door's prompts are
published by a registered governed operation (prompt.republish,
front-door-seed) with dry-run, a plan hash, approval and a ledger entry;
the operation refuses ambiguous targets. Changing how the intake speaks is
a promotion, not an edit.
The lead, guaranteed to reach a person. Submission is a conditional
write (record acceptance). A DynamoDB Streams consumer,
front-door-lead-notify, makes at least one notification attempt and is
redelivered by the stream until the provider accepts; provider acceptance
(an SES message id) is stored as evidence. Delivery itself is not claimed —
a bounce after acceptance is outside this function's knowledge — and the
distinction is written into the code's header. Duplicates are possible and
disclosed: every alert carries the stable lead id in subject and body so a
second copy is recognisable as the same lead. Transient provider errors
(throttles) are retried rather than treated as permanent, so a lead is
never stranded on a recoverable condition.
Bounded automatic recovery. The stream grant for the notify function was shipped as a corrective with a test that asserts the grant on the stream ARN in both source and the synthesised template — the class of defect that only bites in deployment, pinned so it cannot recur.
Design notes
- Why a Solution and not a form. The intake is the platform's own first-party consumer; it proves the contract and the streaming lane with organic traffic, and every lesson from it — structured output at the gateway, prose deduplication, presentation vocabulary — hardened the platform for client Solutions.
- Why fit in words. A number implies a precision the judgment does not have; three words with a rationale is honest and actionable.
- Why "at least once" with disclosed duplicates. For an operator lead alert, a recognisable duplicate is a far smaller cost than a lost lead.
Sources
matterandgas-com/app/page.tsx,app/_front-door/,app/_front-door-alt/— the client.matterandgas-com/amplify/functions/front-door-turn/,front-door-stream-relay/,front-door-submit/,front-door-lead-notify/handler.ts.matterandgas-com/infra/scripts/front-door-prompts.ts,_lib/operations/front-door-seed.ts.matterandgas-com/tests/unit/frontdoor-lead-notify-infra.test.ts.