# PACT Rule - Architecture Guide This document provides a comprehensive overview of the PACT Rule architecture, explaining its design principles, component interactions, and implementation details for regulatory compliance rule management. ## Table of Contents - [Overview](#overview) - [System Architecture](#system-architecture) - [Core Components](#core-components) - [Rule Engine](#rule-engine) - [Compilation Pipeline](#compilation-pipeline) - [AI Integration](#ai-integration) - [Validation Framework](#validation-framework) - [Deployment System](#deployment-system) - [Data Flow](#data-flow) - [Security Architecture](#security-architecture) - [Performance Optimization](#performance-optimization) - [Extension Points](#extension-points) ## Overview PACT Rule is designed as a modular, extensible system for managing regulatory compliance rules. The architecture emphasizes separation of concerns, enabling independent evolution of rule definition, compilation, testing, and deployment components. ### Design Principles 1. **Declarative Rules**: Rules are defined declaratively in human-readable formats 2. **Compilation Safety**: Strict validation and type checking during compilation 3. **Deployment Agnostic**: Support for multiple deployment targets 4. **AI-Enhanced**: Leverage AI for rule generation and analysis 5. **Audit Trail**: Comprehensive logging and cryptographic proofs ## System Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ PACT Rule CLI │ ├─────────────────────────────────────────────────────────────────────┤ │ Presentation Layer │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ Banner │ │ CLI │ │ Logger │ │ Output │ │ │ │ Display │ │ Parser │ │ System │ │ Formatter │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────────────┤ │ Command Layer │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ Compile │ │ Test │ │ Deploy │ │ Validate │ │ │ │ Command │ │ Command │ │ Command │ │ Command │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ List │ │ Status │ │ Expand │ │ Diff │ │ │ │ Command │ │ Command │ │ Command │ │ Command │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ │ ┌────────────────────────────────────────────────────────────────┐│ │ │ NL2Rule Command ││ │ └────────────────────────────────────────────────────────────────┘│ ├─────────────────────────────────────────────────────────────────────┤ │ Core Services │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ Rule │ │ Rule │ │ Validation │ │ AI │ │ │ │ Engine │ │ Compiler │ │ Framework │ │ Service │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ Deployment │ │ Test │ │ Proof │ │ Config │ │ │ │ Manager │ │ Runner │ │ Generator │ │ Manager │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────────────┤ │ Storage Layer │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ │ │ Rule │ │ Compiled │ │ Test │ │ Deployment │ │ │ │Definitions │ │ Rules │ │ Results │ │ Records │ │ │ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` ## Core Components ### Rule Parser Handles parsing of rule definitions from various formats: ```typescript class RuleParser { private parsers: Map = new Map(); constructor() { this.registerParser('yaml', new YamlParser()); this.registerParser('json', new JsonParser()); } async parse(filePath: string): Promise { const extension = path.extname(filePath).toLowerCase(); const parser = this.getParser(extension); const content = await fs.readFile(filePath, 'utf8'); const rawRule = parser.parse(content); return this.normalizeRule(rawRule); } private normalizeRule(raw: any): RuleDefinition { return { name: raw.name || raw.rule_id, version: raw.version || '1.0.0', description: raw.description, conditions: this.normalizeConditions(raw.conditions || raw.if), actions: this.normalizeActions(raw.actions || raw.then), metadata: raw.metadata || {} }; } } ``` ### Rule Validator Validates rules against schema and business logic: ```typescript class RuleValidator { private ajv: Ajv; private schema: any; constructor() { this.ajv = new Ajv({ allErrors: true }); addFormats(this.ajv); this.loadSchema(); } async validate(rule: RuleDefinition): Promise { const result: ValidationResult = { valid: true, errors: [], warnings: [] }; // Schema validation const schemaValid = this.validateSchema(rule); if (!schemaValid.valid) { result.valid = false; result.errors.push(...schemaValid.errors); } // Logic validation const logicValid = this.validateLogic(rule); if (!logicValid.valid) { result.valid = false; result.errors.push(...logicValid.errors); } // Best practice checks const practices = this.checkBestPractices(rule); result.warnings.push(...practices.warnings); return result; } private validateLogic(rule: RuleDefinition): ValidationResult { const errors: ValidationError[] = []; // Check for conflicting conditions const conflicts = this.findConflictingConditions(rule.conditions); if (conflicts.length > 0) { errors.push({ path: '/conditions', message: 'Conflicting conditions detected', details: conflicts }); } // Check for unreachable actions const unreachable = this.findUnreachableActions(rule); if (unreachable.length > 0) { errors.push({ path: '/actions', message: 'Unreachable actions detected', details: unreachable }); } return { valid: errors.length === 0, errors }; } } ``` ## Rule Engine ### Execution Engine Core rule execution logic: ```typescript class RuleEngine { private compiledRules: Map = new Map(); async loadRule(rulePath: string): Promise { const compiled = await fs.readJson(rulePath); this.compiledRules.set(compiled.name, compiled); } evaluate(ruleName: string, data: any): EvaluationResult { const rule = this.compiledRules.get(ruleName); if (!rule) { throw new Error(`Rule not found: ${ruleName}`); } const context = new EvaluationContext(data); const conditionResults = this.evaluateConditions(rule.conditions, context); if (conditionResults.allMatch) { const actions = this.executeActions(rule.actions, context); return { matched: true, ruleName, conditions: conditionResults.details, actions: actions, timestamp: new Date().toISOString() }; } return { matched: false, ruleName, conditions: conditionResults.details, timestamp: new Date().toISOString() }; } private evaluateConditions( conditions: CompiledCondition[], context: EvaluationContext ): ConditionResults { const results = conditions.map(condition => ({ field: condition.field, operator: condition.operator, expected: condition.value, actual: context.getValue(condition.field), matched: this.evaluateCondition(condition, context) })); return { allMatch: results.every(r => r.matched), details: results }; } } ``` ### Condition Evaluator Handles different types of condition evaluations: ```typescript class ConditionEvaluator { private operators: Map = new Map(); constructor() { this.registerOperator('=', (a, b) => a === b); this.registerOperator('!=', (a, b) => a !== b); this.registerOperator('>', (a, b) => Number(a) > Number(b)); this.registerOperator('<', (a, b) => Number(a) < Number(b)); this.registerOperator('>=', (a, b) => Number(a) >= Number(b)); this.registerOperator('<=', (a, b) => Number(a) <= Number(b)); this.registerOperator('in', (a, b) => Array.isArray(b) && b.includes(a)); this.registerOperator('contains', (a, b) => String(a).includes(String(b))); this.registerOperator('matches', (a, b) => new RegExp(b).test(String(a))); } evaluate(condition: Condition, value: any): boolean { const operator = this.operators.get(condition.operator); if (!operator) { throw new Error(`Unknown operator: ${condition.operator}`); } return operator(value, condition.value); } } ``` ## Compilation Pipeline ### Rule Compiler Transforms rule definitions into executable format: ```typescript class RuleCompiler { private optimizer: RuleOptimizer; constructor() { this.optimizer = new RuleOptimizer(); } async compile( definition: RuleDefinition, options: CompileOptions ): Promise { // Phase 1: Validation const validation = await this.validate(definition); if (!validation.valid) { throw new CompilationError('Validation failed', validation.errors); } // Phase 2: Transformation const transformed = this.transform(definition); // Phase 3: Optimization const optimized = options.optimize ? this.optimizer.optimize(transformed) : transformed; // Phase 4: Code Generation const compiled = this.generateCode(optimized); // Phase 5: Verification this.verify(compiled); return compiled; } private transform(definition: RuleDefinition): IntermediateRule { return { ...definition, conditions: definition.conditions.map(c => this.transformCondition(c)), actions: definition.actions.map(a => this.transformAction(a)) }; } private generateCode(rule: IntermediateRule): CompiledRule { const compiledConditions = rule.conditions.map(condition => ({ ...condition, compiled: this.compileCondition(condition) })); const compiledActions = rule.actions.map(action => ({ ...action, compiled: this.compileAction(action) })); const compiled = { ...rule, conditions: compiledConditions, actions: compiledActions, metadata: { ...rule.metadata, compiledAt: new Date().toISOString(), compiler: 'pact-rule@1.0.0' }, hash: '' }; compiled.hash = this.calculateHash(compiled); return compiled; } } ``` ### Rule Optimizer Optimizes compiled rules for performance: ```typescript class RuleOptimizer { optimize(rule: IntermediateRule): IntermediateRule { return { ...rule, conditions: this.optimizeConditions(rule.conditions), actions: this.optimizeActions(rule.actions) }; } private optimizeConditions(conditions: Condition[]): Condition[] { // Sort conditions by evaluation cost const sorted = this.sortByEvaluationCost(conditions); // Merge similar conditions const merged = this.mergeSimilarConditions(sorted); // Remove redundant conditions const deduplicated = this.removeRedundantConditions(merged); return deduplicated; } private sortByEvaluationCost(conditions: Condition[]): Condition[] { return conditions.sort((a, b) => { const costA = this.estimateEvaluationCost(a); const costB = this.estimateEvaluationCost(b); return costA - costB; }); } private estimateEvaluationCost(condition: Condition): number { const costs = { '=': 1, '!=': 1, '>': 2, '<': 2, 'in': 5, 'contains': 10, 'matches': 20 }; return costs[condition.operator] || 10; } } ``` ## AI Integration ### AI Service Handles AI-powered rule generation and analysis: ```typescript class AIService { private openai: OpenAI; constructor() { this.openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); } async generateRuleFromNaturalLanguage( prompt: string, options: AIOptions ): Promise { const systemPrompt = this.buildSystemPrompt(); const userPrompt = this.enhanceUserPrompt(prompt); const response = await this.openai.chat.completions.create({ model: options.model || 'gpt-4', messages: [ { role: 'system', content: systemPrompt }, { role: 'user', content: userPrompt } ], temperature: options.temperature || 0.3, response_format: { type: 'json_object' } }); const ruleContent = response.choices[0].message.content; return this.parseAndValidateRule(ruleContent); } private buildSystemPrompt(): string { return `You are a regulatory compliance expert creating executable rules. Generate rules following this schema: { "rule_id": "rule.XXX", "title": "Descriptive title", "description": "Detailed description", "category": "transaction-monitoring|identity-verification|sanctions-screening|risk-assessment", "severity": "low|medium|high", "version": "1.0.0", "created": "YYYY-MM-DD", "if": { // Conditions as key-value pairs }, "then": { "action": "block|flag|notify|require", "risk_score": 0-100, "reason": "Human-readable reason", "notification": { "channel": "compliance-team", "priority": "low|medium|high" } } }`; } async analyzeRule(rule: RuleDefinition): Promise { const prompt = this.buildAnalysisPrompt(rule); const response = await this.openai.chat.completions.create({ model: 'gpt-4', messages: [ { role: 'system', content: 'You are a compliance expert analyzing rules.' }, { role: 'user', content: prompt } ] }); return this.parseAnalysis(response.choices[0].message.content); } } ``` ### Natural Language Processor Processes natural language rule descriptions: ```typescript class NaturalLanguageProcessor { private intents: IntentMapping[] = [ { patterns: [/block.*transactions?.*over.*\$?(\d+)/i], intent: 'transaction-limit', extractor: (match) => ({ amount: parseInt(match[1]) }) }, { patterns: [/flag.*high.?velocity/i, /monitor.*rapid.*transactions?/i], intent: 'velocity-check', extractor: () => ({ type: 'velocity' }) }, { patterns: [/sanction.*screen/i, /block.*sanction/i], intent: 'sanctions-check', extractor: () => ({ type: 'sanctions' }) } ]; extractIntent(prompt: string): IntentResult { for (const mapping of this.intents) { for (const pattern of mapping.patterns) { const match = prompt.match(pattern); if (match) { return { intent: mapping.intent, parameters: mapping.extractor(match), confidence: 0.8 }; } } } return { intent: 'unknown', parameters: {}, confidence: 0.2 }; } enhancePrompt(prompt: string, intent: IntentResult): string { const templates = { 'transaction-limit': `Create a rule that blocks transactions over $${intent.parameters.amount} for users without enhanced KYC verification`, 'velocity-check': 'Create a rule that flags accounts with unusually high transaction velocity', 'sanctions-check': 'Create a rule that blocks any transaction involving sanctioned entities' }; return templates[intent.intent] || prompt; } } ``` ## Validation Framework ### Schema Validator JSON Schema-based validation: ```typescript class SchemaValidator { private schemas: Map = new Map(); private ajv: Ajv; constructor() { this.ajv = new Ajv({ allErrors: true, verbose: true, strict: false }); addFormats(this.ajv); this.loadSchemas(); } async validateRule(rule: any, schemaName: string = 'rule'): Promise { const schema = this.schemas.get(schemaName); if (!schema) { throw new Error(`Schema not found: ${schemaName}`); } const validate = this.ajv.compile(schema); const valid = validate(rule); if (!valid) { return { valid: false, errors: this.formatErrors(validate.errors) }; } return { valid: true, errors: [] }; } private formatErrors(errors: ErrorObject[]): ValidationError[] { return errors.map(error => ({ path: error.instancePath || '/', message: error.message || 'Validation error', keyword: error.keyword, params: error.params, schemaPath: error.schemaPath })); } } ``` ### Logic Validator Validates rule logic and detects issues: ```typescript class LogicValidator { validateRuleLogic(rule: RuleDefinition): LogicValidationResult { const issues: LogicIssue[] = []; // Check for always-true conditions const alwaysTrue = this.findAlwaysTrueConditions(rule.conditions); if (alwaysTrue.length > 0) { issues.push({ type: 'always-true', severity: 'warning', message: 'Condition is always true', details: alwaysTrue }); } // Check for never-true conditions const neverTrue = this.findNeverTrueConditions(rule.conditions); if (neverTrue.length > 0) { issues.push({ type: 'never-true', severity: 'error', message: 'Condition can never be true', details: neverTrue }); } // Check for contradictory conditions const contradictions = this.findContradictions(rule.conditions); if (contradictions.length > 0) { issues.push({ type: 'contradiction', severity: 'error', message: 'Contradictory conditions found', details: contradictions }); } return { valid: issues.filter(i => i.severity === 'error').length === 0, issues }; } private findContradictions(conditions: Condition[]): Contradiction[] { const contradictions: Contradiction[] = []; for (let i = 0; i < conditions.length; i++) { for (let j = i + 1; j < conditions.length; j++) { if (this.areContradictory(conditions[i], conditions[j])) { contradictions.push({ condition1: conditions[i], condition2: conditions[j], reason: 'Mutually exclusive conditions' }); } } } return contradictions; } } ``` ## Deployment System ### Deployment Manager Handles rule deployment to various targets: ```typescript class DeploymentManager { private deployers: Map = new Map(); constructor() { this.registerDeployer('blockchain', new BlockchainDeployer()); this.registerDeployer('api', new APIDeployer()); this.registerDeployer('file', new FileDeployer()); } async deploy( rule: CompiledRule, target: DeploymentTarget ): Promise { const deployer = this.deployers.get(target.type); if (!deployer) { throw new Error(`Unknown deployment target: ${target.type}`); } // Pre-deployment validation await this.validateDeployment(rule, target); // Deploy const result = await deployer.deploy(rule, target); // Post-deployment verification await this.verifyDeployment(result); // Record deployment await this.recordDeployment(rule, target, result); return result; } private async validateDeployment( rule: CompiledRule, target: DeploymentTarget ): Promise { // Check if rule is already deployed const existing = await this.checkExistingDeployment(rule.name, target); if (existing && !target.options.overwrite) { throw new Error(`Rule ${rule.name} already deployed to ${target.network}`); } // Validate target configuration if (!target.config || !target.config.endpoint) { throw new Error('Invalid deployment target configuration'); } } } ``` ### Blockchain Deployer Deploys rules to blockchain: ```typescript class BlockchainDeployer implements Deployer { async deploy( rule: CompiledRule, target: DeploymentTarget ): Promise { const contract = this.generateSmartContract(rule); const compiled = await this.compileContract(contract); // Estimate gas const gasEstimate = await this.estimateGas(compiled, target); // Deploy contract const receipt = await this.deployContract( compiled, target, gasEstimate ); return { success: true, transactionHash: receipt.transactionHash, contractAddress: receipt.contractAddress, blockNumber: receipt.blockNumber, gasUsed: receipt.gasUsed, network: target.network, timestamp: new Date().toISOString() }; } private generateSmartContract(rule: CompiledRule): string { return ` pragma solidity ^0.8.0; contract ${rule.name.replace(/-/g, '_')} { string public constant RULE_NAME = "${rule.name}"; string public constant RULE_VERSION = "${rule.version}"; bytes32 public constant RULE_HASH = 0x${rule.hash}; struct EvaluationResult { bool matched; string action; uint256 riskScore; string reason; } function evaluate(bytes calldata data) external pure returns (EvaluationResult memory) { // Generated evaluation logic ${this.generateEvaluationLogic(rule)} } }`; } } ``` ## Data Flow ### Request Processing Flow ``` User Input → CLI Parser → Command Router → Command Handler ↓ Rule Parser ↓ Rule Validator ↓ Rule Compiler ↓ Output Generator → User Output ``` ### Rule Evaluation Flow ``` Test Data → Rule Engine → Condition Evaluator → Action Executor ↓ ↓ Context Builder Result Formatter ↓ ↓ Data Accessor Test Report ``` ## Security Architecture ### Authentication & Authorization ```typescript class SecurityManager { private keyManager: KeyManager; private accessControl: AccessControl; async authenticateDeployment( target: DeploymentTarget ): Promise { if (target.type === 'blockchain') { return this.authenticateBlockchain(target); } else if (target.type === 'api') { return this.authenticateAPI(target); } throw new Error(`Unsupported target type: ${target.type}`); } private async authenticateBlockchain( target: DeploymentTarget ): Promise { const privateKey = await this.keyManager.getPrivateKey(target.network); const account = this.deriveAccount(privateKey); return { type: 'blockchain', account, signer: this.createSigner(privateKey) }; } private async authenticateAPI( target: DeploymentTarget ): Promise { const apiKey = process.env.PACT_API_KEY; if (!apiKey) { throw new Error('PACT_API_KEY not configured'); } return { type: 'api', apiKey, headers: { 'Authorization': `Bearer ${apiKey}`, 'X-Rule-Deployer': 'pact-rule-cli' } }; } } ``` ### Cryptographic Operations ```typescript class CryptoService { generateProof(operation: string, data: any): string { const payload = { operation, data, timestamp: new Date().toISOString(), nonce: crypto.randomBytes(16).toString('hex') }; const hash = crypto .createHash('sha256') .update(JSON.stringify(payload)) .digest('hex'); return `pact-proof-${hash.substring(0, 16)}`; } calculateRuleHash(rule: CompiledRule): string { const content = { name: rule.name, version: rule.version, conditions: rule.conditions.map(c => c.compiled), actions: rule.actions.map(a => a.compiled) }; return crypto .createHash('sha256') .update(JSON.stringify(content)) .digest('hex'); } signDeployment(deployment: any, privateKey: string): string { const sign = crypto.createSign('SHA256'); sign.update(JSON.stringify(deployment)); return sign.sign(privateKey, 'hex'); } } ``` ## Performance Optimization ### Caching Strategy ```typescript class CacheManager { private compiledRuleCache: LRUCache; private validationCache: LRUCache; constructor() { this.compiledRuleCache = new LRUCache({ max: 100, ttl: 1000 * 60 * 60 // 1 hour }); this.validationCache = new LRUCache({ max: 200, ttl: 1000 * 60 * 30 // 30 minutes }); } async getCompiledRule( rulePath: string, compile: () => Promise ): Promise { const cacheKey = await this.generateCacheKey(rulePath); const cached = this.compiledRuleCache.get(cacheKey); if (cached) { return cached; } const compiled = await compile(); this.compiledRuleCache.set(cacheKey, compiled); return compiled; } private async generateCacheKey(rulePath: string): Promise { const stats = await fs.stat(rulePath); return `${rulePath}:${stats.mtime.getTime()}`; } } ``` ### Parallel Processing ```typescript class ParallelProcessor { async validateAllRules( rulePaths: string[], options: ValidationOptions ): Promise { const batchSize = options.parallel || 5; const results: ValidationResult[] = []; for (let i = 0; i < rulePaths.length; i += batchSize) { const batch = rulePaths.slice(i, i + batchSize); const batchResults = await Promise.all( batch.map(path => this.validateRule(path, options)) ); results.push(...batchResults); } return this.summarizeResults(results); } async deployMultipleRules( rules: CompiledRule[], target: DeploymentTarget ): Promise { const deployments = await Promise.allSettled( rules.map(rule => this.deployRule(rule, target)) ); return { total: deployments.length, successful: deployments.filter(d => d.status === 'fulfilled').length, failed: deployments.filter(d => d.status === 'rejected').length, results: deployments }; } } ``` ## Extension Points ### Custom Operators Add custom condition operators: ```typescript class OperatorRegistry { private operators: Map = new Map(); registerOperator(definition: OperatorDefinition): void { this.operators.set(definition.name, definition); } } // Usage operatorRegistry.registerOperator({ name: 'geo-within', description: 'Check if location is within geographic boundary', evaluate: (value, boundary) => { const point = parseGeoPoint(value); const polygon = parseGeoPolygon(boundary); return isPointInPolygon(point, polygon); }, compile: (field, boundary) => { return `geoWithin(${field}, ${JSON.stringify(boundary)})`; } }); ``` ### Custom Actions Add custom action types: ```typescript class ActionRegistry { private actions: Map = new Map(); registerAction(definition: ActionDefinition): void { this.actions.set(definition.type, definition); } } // Usage actionRegistry.registerAction({ type: 'quarantine', description: 'Quarantine transaction for manual review', execute: async (params, context) => { await quarantineService.quarantine({ transactionId: context.transaction.id, reason: params.reason, duration: params.duration || '24h', reviewer: params.reviewer || 'compliance-team' }); }, compile: (params) => { return `quarantine(${JSON.stringify(params)})`; } }); ``` ### Plugin System ```typescript interface RulePlugin { name: string; version: string; init(context: PluginContext): void; operators?: OperatorDefinition[]; actions?: ActionDefinition[]; validators?: ValidatorDefinition[]; deployers?: DeployerDefinition[]; } class PluginManager { async loadPlugin(pluginPath: string): Promise { const plugin = await import(pluginPath); if (!this.isValidPlugin(plugin)) { throw new Error('Invalid plugin format'); } const context = this.createContext(); plugin.init(context); // Register plugin components plugin.operators?.forEach(op => this.operatorRegistry.register(op)); plugin.actions?.forEach(action => this.actionRegistry.register(action)); plugin.validators?.forEach(val => this.validatorRegistry.register(val)); plugin.deployers?.forEach(dep => this.deployerRegistry.register(dep)); } } ``` --- This architecture enables PACT Rule to provide a robust, extensible platform for regulatory compliance rule management, with strong validation, AI enhancement, and flexible deployment options.