# PACT Entity CLI - Architecture This document describes the technical architecture, design patterns, and implementation details of the PACT Entity CLI system. ## Table of Contents - [System Overview](#system-overview) - [Architecture Patterns](#architecture-patterns) - [Core Components](#core-components) - [Data Layer](#data-layer) - [Command Processing](#command-processing) - [AI Integration](#ai-integration) - [Vector Analysis Engine](#vector-analysis-engine) - [Security Model](#security-model) - [Performance Considerations](#performance-considerations) - [Extensibility](#extensibility) ## System Overview PACT Entity CLI is built as a modular, TypeScript-based command-line application that provides comprehensive entity compliance management capabilities. The architecture follows established CLI design patterns with modern extensions for AI integration and vector analysis. ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ PACT Entity CLI │ ├─────────────────────────────────────────────────────────────┤ │ CLI Interface Layer (Commander.js) │ ├─────────────────────────────────────────────────────────────┤ │ Command Layer │ │ ┌───────────┬───────────┬───────────┬─────────────────┐ │ │ │ create │ update │ search │ fuse │ │ │ │ score │ timeline │ link │ (advanced) │ │ │ │ export │ status │ │ │ │ │ └───────────┴───────────┴───────────┴─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Business Logic Layer │ │ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │ │ │ Entity │ Compliance │ Relationship│ Vector │ │ │ │ Management │ Scoring │ Analysis │ Analysis │ │ │ └─────────────┴─────────────┴─────────────┴─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Utility Layer │ │ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │ │ │ Config │ Logger │ Proof │ Banner │ │ │ │ Manager │ System │ Generator │ Display │ │ │ └─────────────┴─────────────┴─────────────┴─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Integration Layer │ │ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │ │ │ Supabase │ AI │ Vector │ File │ │ │ │ Database │ Service │Mathematics │ System │ │ │ └─────────────┴─────────────┴─────────────┴─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ External Services │ │ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │ │ │ PostgreSQL │ OpenAI │ pgvector │ Local │ │ │ │ (Supabase) │ GPT-4 │ Engine │ Storage │ │ │ └─────────────┴─────────────┴─────────────┴─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## Architecture Patterns ### 1. Command Pattern Each CLI command is implemented as a self-contained module following the Command pattern: ```typescript interface Command { action: (options: CommandOptions) => Promise; description: string; options: CommandOption[]; } ``` **Benefits:** - Encapsulation of command logic - Easy testing and mocking - Consistent error handling - Uniform option processing ### 2. Strategy Pattern The system uses Strategy pattern for different operational modes: ```typescript interface OutputStrategy { format(data: any): string; } class JSONOutputStrategy implements OutputStrategy { format(data: any): string { return JSON.stringify(data, null, 2); } } class TableOutputStrategy implements OutputStrategy { format(data: any): string { // Format as table } } ``` ### 3. Factory Pattern Entity creation uses Factory pattern for different entity types: ```typescript class EntityFactory { static create(type: string, data: any): Entity { switch (type) { case 'individual': return new IndividualEntity(data); case 'organization': return new OrganizationEntity(data); case 'wallet': return new WalletEntity(data); } } } ``` ### 4. Observer Pattern Event-driven architecture for compliance monitoring: ```typescript interface ComplianceObserver { onScoreChange(entity: Entity, oldScore: number, newScore: number): void; onStatusChange(entity: Entity, field: string, oldValue: any, newValue: any): void; } ``` ## Core Components ### 1. CLI Interface Layer **Technology:** Commander.js **Responsibility:** Command parsing, option validation, help generation ```typescript // cli.ts const program = new Command(); program .name('pact-entity') .description('PACT Entity CLI - Manage digital twin compliance profiles') .version(packageJson.version) .hook('preAction', async (thisCommand) => { // Global setup: config loading, logger initialization }); ``` **Key Features:** - Automatic help generation - Option type validation - Global option inheritance - Pre/post action hooks ### 2. Command Layer Each command is implemented as a separate module with consistent structure: ```typescript // commands/create.ts export const create = { action: async (options: CreateOptions) => { try { // Input validation validateCreateOptions(options); // Business logic execution const entity = await entityService.create(options); // Output formatting outputManager.display(entity, options); // Proof generation (if requested) if (options.proof) { const proof = generateProof(entity); console.log(`Proof: ${proof}`); } } catch (error) { handleError(error, options); } } }; ``` **Command Structure:** - Input validation - Business logic execution - Output formatting - Error handling - Proof generation ### 3. Business Logic Layer #### Entity Management Service ```typescript class EntityService { async create(data: EntityCreateData): Promise { // Generate unique ID const id = this.generateEntityId(); // Create entity with defaults const entity = new Entity({ id, ...data, complianceScore: 0.5, kycStatus: 'pending', amlStatus: 'pending', created: new Date().toISOString() }); // Persist to storage await this.repository.save(entity); // Trigger events this.eventEmitter.emit('entity.created', entity); return entity; } } ``` #### Compliance Scoring Engine ```typescript class ComplianceScorer { calculateScore(entity: Entity): ComplianceScore { const weights = { kyc: 0.3, aml: 0.3, transaction: 0.2, behavior: 0.2 }; const scores = { kyc: this.calculateKYCScore(entity), aml: this.calculateAMLScore(entity), transaction: this.calculateTransactionScore(entity), behavior: this.calculateBehaviorScore(entity) }; const overall = Object.entries(scores) .reduce((sum, [key, score]) => sum + score * weights[key], 0); return { overall: Math.round(overall * 100), components: scores, weights, trend: this.calculateTrend(entity), riskLevel: this.assessRiskLevel(overall) }; } } ``` ### 4. Utility Layer #### Configuration Manager ```typescript class ConfigManager { private config: Config | null = null; private readonly configPath: string; constructor(configPath?: string) { this.configPath = configPath || this.getDefaultConfigPath(); } async loadConfig(): Promise { if (this.config) return this.config; // Try loading from file if (await fs.pathExists(this.configPath)) { this.config = await fs.readJson(this.configPath); } else { this.config = this.getDefaultConfig(); } // Override with environment variables this.config = { ...this.config, apiEndpoint: process.env.PACT_API_ENDPOINT || this.config.apiEndpoint, logLevel: process.env.PACT_LOG_LEVEL || this.config.logLevel }; return this.config; } } ``` #### Logger System ```typescript class Logger { private config: any; debug(message: string, ...args: any[]): void { if (this.shouldLog('debug')) { console.log(chalk.gray(`[DEBUG] ${message}`), ...args); } } private shouldLog(level: string): boolean { const levels = ['debug', 'info', 'warn', 'error']; const configLevel = this.config.logLevel || 'info'; return levels.indexOf(level) >= levels.indexOf(configLevel); } } ``` ## Data Layer ### 1. Repository Pattern ```typescript interface EntityRepository { save(entity: Entity): Promise; findById(id: string): Promise; findByType(type: string): Promise; update(id: string, updates: Partial): Promise; delete(id: string): Promise; } ``` ### 2. Database Integration **Supabase Integration:** ```typescript class SupabaseEntityRepository implements EntityRepository { private client: SupabaseClient; constructor() { this.client = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY! ); } async save(entity: Entity): Promise { const { error } = await this.client .from('entities') .insert(entity); if (error) throw new DatabaseError(error.message); } } ``` **Local Storage Fallback:** ```typescript class LocalEntityRepository implements EntityRepository { private readonly dataPath: string; async save(entity: Entity): Promise { const filePath = path.join(this.dataPath, `${entity.id}.json`); await fs.writeJson(filePath, entity, { spaces: 2 }); } } ``` ### 3. Data Models ```typescript class Entity { constructor( public id: string, public type: EntityType, public name: string, public complianceScore: number, public kycStatus: KYCStatus, public amlStatus: AMLStatus, public riskScore: number, public metadata: Record, public created: string, public updated: string ) {} updateCompliance(updates: ComplianceUpdate): void { if (updates.kycStatus) this.kycStatus = updates.kycStatus; if (updates.amlStatus) this.amlStatus = updates.amlStatus; if (updates.riskScore !== undefined) this.riskScore = updates.riskScore; this.updated = new Date().toISOString(); } } ``` ## Command Processing ### 1. Command Lifecycle ``` User Input → Parsing → Validation → Execution → Output → Cleanup ↓ ↓ ↓ ↓ ↓ ↓ Raw Args → Options → Validated → Business → Format → Exit Object Data Logic Data ``` ### 2. Input Validation ```typescript class InputValidator { static validateEntityId(id: string): void { if (!id || typeof id !== 'string') { throw new ValidationError('Entity ID is required'); } if (!/^[a-zA-Z0-9.-]+$/.test(id)) { throw new ValidationError('Invalid entity ID format'); } } static validateScore(score: any): number { const numScore = parseFloat(score); if (isNaN(numScore) || numScore < 0 || numScore > 1) { throw new ValidationError('Score must be between 0 and 1'); } return numScore; } } ``` ### 3. Error Handling Strategy ```typescript class ErrorHandler { static handle(error: Error, options: CommandOptions): void { if (error instanceof ValidationError) { console.error(chalk.red('Validation Error:'), error.message); process.exit(4); } else if (error instanceof DatabaseError) { console.error(chalk.red('Database Error:'), error.message); if (options.debug) console.error(error.stack); process.exit(3); } else { console.error(chalk.red('Error:'), error.message); if (options.debug) console.error(error.stack); process.exit(1); } } } ``` ## AI Integration ### 1. AI Service Architecture ```typescript interface AIService { analyzeCompliance(entity: Entity, vector: ComplianceVector): Promise; generateRecommendations(entity: Entity): Promise; detectAnomalies(entityGroup: Entity[]): Promise; } class OpenAIService implements AIService { private client: OpenAI; async analyzeCompliance(entity: Entity, vector: ComplianceVector): Promise { const prompt = this.buildAnalysisPrompt(entity, vector); const response = await this.client.chat.completions.create({ model: 'gpt-4', messages: [{ role: 'user', content: prompt }], temperature: 0.3, max_tokens: 2000 }); return this.parseAnalysisResponse(response.choices[0].message.content); } } ``` ### 2. AI Analysis Pipeline ``` Entity Data → Vector Generation → Context Building → AI Analysis → Result Parsing ↓ ↓ ↓ ↓ ↓ Profile → 8D Vector → Structured → GPT-4 → Structured Data Creation Prompt Analysis Insights ``` ### 3. AI Prompt Engineering ```typescript class PromptBuilder { buildAnalysisPrompt(entity: Entity, vector: ComplianceVector): string { return ` Analyze the following entity compliance profile: Entity Information: - ID: ${entity.id} - Type: ${entity.type} - Name: ${entity.name} - Overall Score: ${entity.complianceScore}/100 Compliance Vector (8-dimensional): - KYC Score: ${vector.dimensions.kyc_score} - Risk Score: ${vector.dimensions.avg_risk} - Sanctions Flag: ${vector.dimensions.sanctions_flag} - QR Events: ${vector.dimensions.qr_events} - High Value TX: ${vector.dimensions.high_value_tx} - Contract Exposure: ${vector.dimensions.contract_exposure} - Token Diversity: ${vector.dimensions.token_diversity} - Anomaly Frequency: ${vector.dimensions.anomaly_frequency} Please provide: 1. Risk assessment (LOW/MEDIUM/HIGH) 2. Key strengths and weaknesses 3. Behavioral insights 4. Regulatory compliance status 5. Specific recommendations for improvement Format your response as structured analysis with clear sections. `; } } ``` ## Vector Analysis Engine ### 1. Vector Mathematics ```typescript class VectorMath { static cosineSimilarity(vectorA: number[], vectorB: number[]): number { const dotProduct = vectorA.reduce((sum, val, i) => sum + val * vectorB[i], 0); const magnitudeA = Math.sqrt(vectorA.reduce((sum, val) => sum + val * val, 0)); const magnitudeB = Math.sqrt(vectorB.reduce((sum, val) => sum + val * val, 0)); return dotProduct / (magnitudeA * magnitudeB); } static euclideanDistance(vectorA: number[], vectorB: number[]): number { return Math.sqrt( vectorA.reduce((sum, val, i) => sum + Math.pow(val - vectorB[i], 2), 0) ); } static magnitude(vector: number[]): number { return Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0)); } } ``` ### 2. Entity Relationship Detection ```typescript class RelationshipDetector { async findRelatedEntities(targetEntity: Entity, threshold = 0.85): Promise { const targetVector = await this.generateVector(targetEntity); const allEntities = await this.entityRepository.findAll(); const relationships: RelatedEntity[] = []; for (const entity of allEntities) { if (entity.id === targetEntity.id) continue; const entityVector = await this.generateVector(entity); const similarity = VectorMath.cosineSimilarity(targetVector.vector, entityVector.vector); if (similarity >= threshold) { const sharedTraits = this.analyzeSharedTraits(targetEntity, entity); relationships.push({ entity, similarity, sharedTraits, relationshipType: this.inferRelationshipType(sharedTraits) }); } } return relationships.sort((a, b) => b.similarity - a.similarity); } } ``` ### 3. Vector Database Integration ```typescript class VectorDatabase { async store(entityId: string, vector: number[]): Promise { await this.supabase .from('entity_vectors') .upsert({ entity_id: entityId, vector: vector, created_at: new Date().toISOString() }); } async findSimilar(vector: number[], limit = 10): Promise { // Using pgvector similarity search const { data } = await this.supabase.rpc('find_similar_vectors', { query_vector: vector, similarity_threshold: 0.8, match_count: limit }); return data; } } ``` ## Security Model ### 1. Input Sanitization ```typescript class SecurityValidator { static sanitizeInput(input: string): string { // Remove potentially dangerous characters return input.replace(/[<>'"&]/g, ''); } static validateJSONInput(input: string): any { try { const parsed = JSON.parse(input); // Prevent prototype pollution if (this.hasPrototypePollution(parsed)) { throw new SecurityError('Invalid JSON structure'); } return parsed; } catch (error) { throw new ValidationError('Invalid JSON format'); } } } ``` ### 2. Cryptographic Proofs ```typescript class ProofGenerator { generate(data: any): string { const timestamp = new Date().toISOString(); const payload = { ...data, timestamp, nonce: crypto.randomBytes(16).toString('hex') }; const hash = crypto .createHash('sha256') .update(JSON.stringify(payload)) .digest('hex'); return `pact-proof-${hash.substring(0, 16)}`; } verify(proof: string, originalData: any): boolean { // Verification logic return true; // Simplified } } ``` ### 3. Environment Protection ```typescript class EnvironmentManager { static loadSecurely(): void { // Load environment variables dotenv.config(); // Validate required variables const required = ['SUPABASE_URL', 'SUPABASE_ANON_KEY']; const missing = required.filter(key => !process.env[key]); if (missing.length > 0) { throw new ConfigurationError(`Missing environment variables: ${missing.join(', ')}`); } // Mask sensitive data in logs this.maskSensitiveData(); } } ``` ## Performance Considerations ### 1. Caching Strategy ```typescript class CacheManager { private cache = new Map(); get(key: string): T | null { const entry = this.cache.get(key); if (!entry || entry.expires < Date.now()) { this.cache.delete(key); return null; } return entry.data; } set(key: string, data: T, ttl = 300000): void { // 5 minutes default this.cache.set(key, { data, expires: Date.now() + ttl }); } } ``` ### 2. Lazy Loading ```typescript class LazyLoader { private static instances = new Map(); static async getService(serviceName: string, factory: () => Promise): Promise { if (!this.instances.has(serviceName)) { this.instances.set(serviceName, await factory()); } return this.instances.get(serviceName); } } ``` ### 3. Batch Processing ```typescript class BatchProcessor { async processEntities(entities: Entity[], batchSize = 10): Promise { for (let i = 0; i < entities.length; i += batchSize) { const batch = entities.slice(i, i + batchSize); await Promise.all( batch.map(entity => this.processEntity(entity)) ); // Small delay to prevent overwhelming the system await new Promise(resolve => setTimeout(resolve, 100)); } } } ``` ## Extensibility ### 1. Plugin Architecture ```typescript interface Plugin { name: string; version: string; initialize(cli: CLIInstance): void; commands?: Command[]; hooks?: Hook[]; } class PluginManager { private plugins: Plugin[] = []; register(plugin: Plugin): void { this.plugins.push(plugin); plugin.initialize(this.cli); } async loadPlugins(pluginDir: string): Promise { const pluginFiles = await fs.readdir(pluginDir); for (const file of pluginFiles) { if (file.endsWith('.plugin.js')) { const plugin = await import(path.join(pluginDir, file)); this.register(plugin.default); } } } } ``` ### 2. Custom Commands ```typescript // Example plugin export default { name: 'custom-analytics', version: '1.0.0', initialize(cli: CLIInstance): void { cli.addCommand('analytics', { description: 'Advanced analytics for entities', action: async (options) => { // Custom analytics logic } }); } }; ``` ### 3. Hook System ```typescript interface Hook { event: string; handler: (data: any) => Promise; } class HookManager { private hooks = new Map(); register(hook: Hook): void { if (!this.hooks.has(hook.event)) { this.hooks.set(hook.event, []); } this.hooks.get(hook.event)!.push(hook); } async emit(event: string, data: any): Promise { const eventHooks = this.hooks.get(event) || []; await Promise.all( eventHooks.map(hook => hook.handler(data)) ); } } ``` --- This architecture documentation provides a comprehensive overview of the PACT Entity CLI system design, enabling developers to understand, maintain, and extend the codebase effectively.