Architecture

This document captures the key technical decisions for Guardrail-Sim, including alternatives considered and rationale for choices made.

Overview

Guardrail-Sim is a two-layer system:

┌─────────────────────────────────────────────────────────────┐
│                   SIMULATION ENGINE (Node.js)          [PLANNED]
│  Synthetic Orders │ Buyer Personas │ Negotiation Loop        │
│  LLM-as-Adversary │ Result Logging │ Margin Calculation      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    POLICY ENGINE (Deterministic)      [COMPLETE]
│  json-rules-engine │ Margin Floors │ Volume Tiers            │
│  Escalation Triggers │ Customer Segment Rules                │
│                                                              │
│  Exposed via MCP Server: 5 tools for AI agent integration   │
└─────────────────────────────────────────────────────────────┘

Key Decisions

Decision	Choice	Rationale
Policy logic	Deterministic (json-rules-engine)	LLMs should never touch pricing math. Predictable, auditable, testable.
LLM role	Adversarial buyer simulation only	LLM generates realistic negotiation attempts; policy engine decides outcomes.
Integration	MCP server	Production AI agents can call `evaluate_policy()` at runtime.
UCP alignment	Universal Commerce Protocol	Standard error codes and response formats for agentic commerce.
Data	Synthetic orders	No dependency on real merchant data. Demonstrable without NDA concerns.

Decision Records

For detailed architectural decisions, see the ADR section:

ADR-001: Policy Engine Library - Why json-rules-engine
ADR-002: UCP Alignment - Universal Commerce Protocol integration

Stack

Layer	Technology	Rationale
Policy Engine	Node.js + json-rules-engine	Battle-tested rules engine; JS ecosystem consistency
UCP Types	TypeScript	Type-safe UCP integration for agentic commerce
Insights	TypeScript	Policy health checks and recommendations
MCP Server	TypeScript + @modelcontextprotocol/sdk	5 tools for AI agent integration
Simulation Runner	Node.js + OpenAI API	LLM for buyer persona simulation; Batch API for cost efficiency
Database	PostgreSQL (Supabase)	Relational for structured simulation results; free tier sufficient
Documentation	Next.js 15 + Fumadocs	Interactive docs site with policy playground

Architecture

Architecture

Overview

Key Decisions

Decision Records

Stack

On this page