Reference architectures

Three worked examples of TapPass deployed against real customer stacks. Buyers should see themselves in at least one of these. Each example shows: their stack, runtime selection per surface, coverage achieved, and what it costs.

These are the concrete answer to "what does TapPass look like for our environment?" Generic architecture lives elsewhere; this is the partner-facing rendition.

How to read

Each scenario walks through:

The customer's stack — what they actually run today
The runtime selections — which TapPass runtime maps to each surface
Coverage achieved — concrete answer to "what governance do we get?"
What it costs — Runtime / Control / Intelligence pricing
Compliance posture — what packs they apply
The 30-day rollout — how they actually deploy

Three scenarios:

Scenario A — Mid-market fintech, full coverage. Claude Code on laptops + LangChain in K8s + Custom Python in CI.
Scenario B — SMB with mixed stack, partial coverage. Cursor on laptops + n8n workflows + OpenAI Assistants in production.
Scenario C — Healthcare on-prem, regulated, airgapped. Custom Python agents on internal Kubernetes, no SaaS.

Scenario A — Mid-market fintech, full coverage

Customer profile: 200 engineers. SOC 2 + on track for ISO 42001. CTO told CISO to enable Claude Code by end of quarter, safely. CISO wants the same governance posture across all surfaces.

Their stack today

Surface	What they run
Developer laptops	Claude Code (200 installs); Cursor (~30 power users)
CI / build agents	Claude Code in headless mode (3 Linux build hosts)
Production	LangChain agents on EKS (12 services, mostly customer-support and refund flows)
Data analytics	Custom Python agents running ad-hoc; SQL against Snowflake

Runtime selections

Surface	Runtime	Coverage
Dev laptops (Claude Code)	`claude-code-laptop`	5/5
Dev laptops (Cursor)	`cursor-laptop` (Q3 ship)	3/5
CI build hosts	`claude-code-server`	5/5
Production LangChain on K8s	`langchain-react` deployed via OpenShell on K8s	5/5
Data analytics Python	`langchain-react` (custom Python via `tappass-agent` SDK)	5/5

Coverage achieved

                       Gateway   MCP   Codemode   Harness   Kernel
Claude Code laptops      ✓       ✓     partial      ✓         ✓
Cursor laptops           ✓       partial   ✗      partial     ✗
Claude Code CI           ✓       ✓        ✓         ✓         ✓ (OpenShell)
LangChain K8s            ✓       ✓        ✓         ✓         ✓ (OpenShell on K8s)
Custom Python agents     ✓       ✓        ✓         ✓         ✓

Headline: 4 of 5 surfaces achieve full 5/5 coverage. Cursor laptops are the partial-coverage outlier — and that gap closes as Cursor's own surface evolves.

Compliance posture

Two packs applied at org floor:

OWASP LLM Top 10 — coverage of LLM01-10 (LLM03 and LLM09 explicitly out-of-scope)
SOC 2 mapping — every Rego rule tagged for SOC 2 CC6.1 / CC6.6 / CC7.2

Project-level additions: payment processing project layers in PCI-DSS scope pack (planned Q1 2027 but operator-authored equivalent in the meantime).

Cost shape

Product	Cost
Runtime	$0 (open-core)
Control	per governed agent / month × ~250 active agents
Intelligence	not yet (2027 add-on)
On-prem	not needed (SaaS Control plane)

30-day rollout

Week	What happens
1	MDM post-install hook on every laptop. `pip install tappass; tappass configure --enrollment-token`. Shim `claude` and `cursor`. Developers notice nothing.
2	Open Control dashboard. Apply OWASP LLM Top 10 pack at org level. Author SOC 2 mapping. Flip on shadow mode for 7 days.
3	Review shadow-mode telemetry. Three false positives, one true positive. Tighten policy. Promote to enforced.
4	Push enforced policy via SSE to all surfaces. All 5 surfaces report applied policy_version 1017 within 5 seconds. SOC 2 auditor visit week 6 — clean close.

What this customer sees in the dashboard

Per-surface trace timelines (5 contiguous spans per call: gateway → mcp → codemode → harness → kernel where applicable)
Per-policy because-trail for every rule (which compliance pack contributed it, which cascade level introduced it)
Per-sandbox status (active / offline / drift)
Audit export to SOC 2 CC6.1 PDF on request

Scenario B — SMB with mixed stack, partial coverage

Customer profile: 30 employees, growing fast. No CISO. CTO wears the security hat. Has heard prompt-injection horror stories. Wants safety without a 6-month rollout.

Their stack today

Surface	What they run
Developer laptops	Cursor (12 devs); a few use VS Code Copilot
Operations	n8n workflows for everything (~40 active workflows; some call OpenAI for content gen)
Customer-facing	OpenAI Assistants API embedded in their SaaS (1 production assistant)
Internal	A few Python scripts hitting Anthropic for ad-hoc work

Runtime selections

Surface	Runtime	Coverage
Dev laptops (Cursor)	`cursor-laptop` (Q3 ship)	3/5
n8n workflows	`n8n-workflow` (Q4 ship)	1/5 (gateway only)
OpenAI Assistants in production	`openai-assistants`	1/5 (gateway only)
Internal Python scripts	`langchain-react` via `tappass-agent` SDK	5/5

Coverage achieved

                       Gateway   MCP   Codemode   Harness   Kernel
Cursor laptops           ✓       partial   ✗      partial     ✗
n8n workflows            partial    ✗      ✗        ✗         ✗
OpenAI Assistants        ✓        ✗      ✗        ✗         ✗
Python scripts (SDK)     ✓        ✓      ✓        ✓         ✓

Headline: mixed coverage — full on the SDK-direct path, partial-to-minimal on vendor-hosted surfaces. Still much better than nothing. The CISO has a coherent coverage map and knows where the gaps are.

Why this is honest about coverage gaps

The strategy memo's principle: "don't claim coverage we don't have." For this customer:

OpenAI Assistants runs on OpenAI's infrastructure — we cannot enforce the kernel ring there. Pair with OpenAI Enterprise admin tooling for the rest.
n8n workflows are gateway-only governance — we sit between n8n's HTTP node and the LLM provider. The agent's other behavior is outside our reach.
Cursor's harness has limited allow/deny semantics; partial there.

Compliance posture

OWASP LLM Top 10 at org level — gives them a procurement-defensible answer if they pursue SOC 2 in 2027.
No regulated-industry packs (not yet relevant).

Cost shape

Product	Cost
Runtime	$0
Control	per governed agent / month × ~50 agents
Intelligence	not yet
On-prem	not needed

30-day rollout

Week	What happens
1	CTO runs `pipx install tappass-host tappass-agent`. Configures gateway redirect for n8n + OpenAI Assistants.
2	Cursor laptops install runtime. Existing Python scripts migrated to `tappass-agent` SDK.
3	Apply OWASP LLM Top 10 pack. Run probe suite against Python scripts. Fix one prompt-injection issue.
4	Trial period closes. Convert to paid Control plan.

What this customer sees

Honest dashboard: 4/5 ratings vary by surface; gaps marked transparently with rationale.
One audit trail across all surfaces.
Single Policy authored once, applied everywhere it can be applied.

Scenario C — Healthcare on-prem, regulated, airgapped

Customer profile: Regional healthcare SaaS. Processes PHI. HIPAA-regulated. Legal won't approve any SaaS — everything must run in their VPC. Building a customer-facing triage agent. Audit firm specifically asks how they govern agentic PHI access.

Their stack today

Surface	What they run
Triage agent (production)	Custom Python on internal K8s; LangChain ReAct
Internal tools agents	Claude Code on engineer laptops (limited; mostly for data engineers)
EHR integration	Internal MCP server exposing FHIR queries
Test harness	Pre-deployment evaluation in CI before shipping any agent change

Runtime selections

Surface	Runtime	Coverage
Triage agent (production)	`langchain-react` deployed via gVisor on K8s + airgapped Control plane	5/5
Engineer laptops (Claude Code)	`claude-code-laptop` with on-prem TapPass endpoint	5/5
Internal MCP (FHIR)	Registered via `tappass mcp register --name acme-fhir --auth bearer:vault://acme-fhir-token`	n/a (TapPass is broker)

Coverage achieved

                                     Gateway   MCP   Codemode   Harness   Kernel
Triage agent (gVisor on K8s)           ✓       ✓        ✓         ✓         ✓
Claude Code laptops (on-prem)          ✓       ✓     partial      ✓         ✓
EHR integration (registered MCP)       ✓       ✓ (broker enforces ACLs)

Headline: full 5/5 coverage on production. PHI taint tracking enforced via Compiled Policy-level data classification. Internal MCP registered via approved-tool-server-list — every FHIR call goes through TapPass MCP broker.

Why airgapped works

TapPass Control plane runs in customer's VPC (via tappass-platform license server).
Outbound-only Cloudflare Tunnel for license refresh; nothing else leaves.
No customer data ever transits TapPass-managed infrastructure.
Same product surface as SaaS Control — the difference is deployment topology.

Compliance posture

HIPAA pack (planned 2027; operator-authored in the meantime) — PHI-mode detect_pii, access_control_strict, allowed-domain matching for external_messaging.
PHI taint tracking as a first-class Compiled Policy dimension — once an agent reads PHI, its data_class is tainted, and downstream egress is hard-restricted to internal endpoints only.
EU AI Act + OWASP LLM packs at org level (procurement-defensible baseline).
Quarterly HIPAA 164.312 report — operator clicks one button to export.

Cost shape

Product	Cost
Runtime	$0
Control (on-prem)	per governed agent / month × ~15 agents + on-prem surcharge
Intelligence	not applicable (airgapped; tenant-isolated; no cross-customer telemetry by policy)
On-prem deployment cost (compute, ops)	borne by the customer

30-day rollout

Week	What happens
1-2	TapPass Control plane deployed in customer VPC via `tappass-platform`. License token configured.
3	Internal MCP server registered with TapPass MCP broker. Vault-backed credentials for FHIR API.
4	Triage agent moved behind TapPass. Pre-deployment eval runs against PHI-handling probes. Fix two issues. Promote to production. Quarterly HIPAA report rendered for audit firm.

What this customer sees

Audit shows every PHI access with data_class=phi, agent_id, policy_version, denied actions, and full replay traces.
Pre-deployment probes ran 50+ adversarial scenarios against the triage agent before each release. Pass/fail report attached to PR.
Tenant-isolated — no cross-customer telemetry; no Intelligence layer; everything stays in their VPC.

Cross-scenario observations

What's universal across all three

One Policy. Every customer authors one Rego policy (or applies one set of compliance packs); it materializes consistently across all their surfaces.
One audit trail. All governed actions across all surfaces emit to one hash-chained audit log.
One dashboard. All sandboxes / all surfaces / all policies visible in one place (in customer's VPC for healthcare; SaaS for fintech and SMB).

What varies

Coverage depth varies by surface, because what's possible on each ecosystem varies. The fintech achieves 5/5 across most surfaces because they use governable ecosystems. The SMB has gaps because their stack includes vendor-hosted SaaS and HTTP-driven workflows. The healthcare org achieves 5/5 by choosing a governable runtime architecture.
Pricing tier varies by Control adoption. Runtime is free; Control scales with agent count.
Deployment topology varies. SaaS for most; on-prem for regulated.

What this means for sales conversations

Buyer	Map to scenario
Mid-market fintech, financial services, e-commerce	Scenario A
SMB, growth-stage SaaS, design-led teams	Scenario B
Healthcare, public sector, defense, regulated finance	Scenario C

If a prospect's stack doesn't fit one of these cleanly, write a fourth scenario.

How to extend this file

When a partner conversation surfaces a new common stack, add a fourth scenario. Each new scenario should answer the same six questions:

The customer's stack
Runtime selections
Coverage achieved (the matrix)
Compliance posture
Cost shape
30-day rollout

A reference architecture is buyer-facing. The audience is the partner / customer's CTO trying to project TapPass into their environment. Write accordingly.

References

OVERVIEW.md — the 1-pager
COMPATIBILITY-MATRIX.md — per-runtime coverage definitions
PRODUCT-ALIGNMENT.md — which product covers what
STATUS.md — what's shipped vs. concept (relevant when scoring "today" coverage)
Strategy Memo v3 §16-18 — original three scenario walkthroughs (fintech / solo dev / healthcare)