Architecture
Technical decisions and architecture overview
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)
│ 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: 12 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/server (SDK v2) | 12 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 |