@birhaus/compliance

Regulatory compliance and audit trail components for BIRHAUS design system

Comprehensive React components for regulatory compliance, audit trails, and privacy management with built-in support for SEPRELAD, GDPR, and Spanish-first documentation.

🚀 Features

• 🏛️ SEPRELAD Compliance - Paraguay financial reporting automation
• 🔒 GDPR Privacy Controls - European privacy regulation support
• 📋 Audit Trails - Complete action logging and timeline visualization
• 🇪🇸 Spanish-First - Primary Spanish interface with regulatory terminology
• 📊 Regulatory Reports - Automated compliance report generation
• 🔍 Privacy Management - User consent and data protection tools
• ♿ Accessibility - WCAG AA+ compliant components
• ⚡ Real-time Monitoring - Live compliance violation detection
• 📱 Responsive - Mobile-optimized compliance interfaces

📦 Installation

npm install @birhaus/compliance

# Peer dependencies
npm install react react-dom @birhaus/tokens @birhaus/primitives @birhaus/provider

🎯 Quick Start

import { 
  BirhausAuditTrail,
  BirhausPrivacyManager, 
  BirhausSEPRELADDashboard 
} from '@birhaus/compliance'

function ComplianceDashboard() {
  return (
    <div>
      {/* SEPRELAD Financial Compliance */}
      <BirhausSEPRELADDashboard
        transactions={transactionData}
        showAlerts={true}
        autoReport={true}
        locale="es-PY"
      />
      
      {/* Audit Trail Visualization */}
      <BirhausAuditTrail
        events={auditEvents}
        showFilters={true}
        titleEs="Registro de Actividades"
        exportFormats={['pdf', 'csv']}
      />
      
      {/* Privacy & GDPR Controls */}
      <BirhausPrivacyManager
        userConsents={userConsentData}
        showGDPRControls={true}
        allowDataExport={true}
        privacyPolicy="/privacy-policy"
      />
    </div>
  )
}

📋 Components

| Component | Purpose | Compliance Standards | |-----------|---------|---------------------| | BirhausSEPRELADDashboard | Paraguay financial reporting | SEPRELAD, Anti-Money Laundering | | BirhausAuditTrail | Action logging & timeline | SOX, ISO 27001, Audit Standards | | BirhausPrivacyManager | GDPR privacy controls | GDPR, CCPA, Data Protection | | BirhausComplianceChecklist | Regulatory requirement tracking | Custom compliance frameworks | | BirhausRegulatoryReport | Automated report generation | Multiple regulatory standards |

🏛️ SEPRELAD Dashboard

Complete Paraguay financial compliance automation:

import { BirhausSEPRELADDashboard } from '@birhaus/compliance'

function FinancialCompliance() {
  const transactions = [
    {
      id: '1',
      monto: 15000, // USD - triggers SEPRELAD reporting
      moneda: 'USD',
      tipo: 'transferencia',
      fecha: new Date(),
      origen: 'Juan Pérez',
      destino: 'María González',
      documentoIdentidad: '1.234.567'
    }
  ]

  return (
    <BirhausSEPRELADDashboard
      transactions={transactions}
      
      // Automatic threshold monitoring
      thresholdUSD={10000} // SEPRELAD threshold
      autoReport={true}    // Generate reports automatically
      
      // Real-time alerts
      showAlerts={true}
      alertTypes={['threshold', 'suspicious', 'incomplete']}
      
      // Spanish-first reporting
      reportLanguage="es"
      includeSpanishSummary={true}
      
      // Export capabilities
      showExport={true}
      exportFormats={['pdf', 'excel', 'csv']}
      
      // Audit integration
      onComplianceEvent={(event) => {
        console.log('SEPRELAD event:', event)
        // Log to audit trail
      }}
    />
  )
}

SEPRELAD Features

• ✅ Threshold Monitoring - Automatic USD conversion and reporting
• ✅ Suspicious Activity Detection - Pattern analysis for unusual transactions
• ✅ Document Validation - CI, RUC, and passport verification
• ✅ Report Generation - Official SEPRELAD format reports
• ✅ Spanish Documentation - All reports in Spanish as required
• ✅ Real-time Alerts - Immediate notification of reportable events

// Advanced SEPRELAD Configuration
<BirhausSEPRELADDashboard
  transactions={transactions}
  
  // Advanced monitoring
  suspiciousPatterns={{
    rapidTransfers: { limit: 5, timeframe: '1h' },
    roundNumbers: true,
    structuring: { threshold: 9500 }
  }}
  
  // Regulatory settings
  reportingEntity={{
    name: 'Banco Nacional de Paraguay',
    code: 'BNP001',
    supervisor: 'SEPRELAD'
  }}
  
  // Automatic escalation
  escalationRules={{
    amount: 50000, // USD
    frequency: 10,  // transactions per day
    alertEmail: '[email protected]'
  }}
/>

📋 Audit Trail

Complete audit trail visualization with Spanish-first documentation:

import { BirhausAuditTrail } from '@birhaus/compliance'

function AuditPage() {
  const auditEvents = [
    {
      id: '1',
      timestamp: '2024-08-21T10:30:00Z',
      actor: 'María García',
      actorId: 'user_123',
      action: 'transferencia.creada',
      entity: 'transferencia',
      entityId: 'trans_456',
      details: {
        monto: 500000,
        moneda: 'PYG',
        destino: 'Juan Pérez'
      },
      ipAddress: '192.168.1.100',
      userAgent: 'Mozilla/5.0...',
      status: 'success'
    }
  ]

  return (
    <BirhausAuditTrail
      events={auditEvents}
      
      // Spanish-first interface
      titleEs="Registro de Auditoría"
      titleEn="Audit Trail"
      emptyMessage="No hay actividades registradas"
      
      // Filtering capabilities
      showFilters={true}
      filters={{
        dateRange: true,
        actor: true,
        action: true,
        status: true
      }}
      
      // Search functionality  
      showSearch={true}
      searchFields={['actor', 'action', 'entity']}
      
      // Export options
      showExport={true}
      exportFormats={['pdf', 'csv', 'json']}
      
      // Real-time updates
      realTime={true}
      refreshInterval={30000} // 30 seconds
      
      // Compliance features
      showIntegrityCheck={true}
      signEvents={true} // Digital signatures
    />
  )
}

Audit Trail Features

• 🔍 Search & Filter - Find specific events quickly
• 📊 Timeline View - Chronological event visualization
• 🔐 Integrity Protection - Tamper-evident audit logs
• 📱 Mobile Optimized - Touch-friendly audit review
• ⚡ Real-time Updates - Live event streaming
• 📄 Export Options - Multiple format support

🔒 Privacy Manager

GDPR-compliant privacy controls and user consent management:

import { BirhausPrivacyManager } from '@birhaus/compliance'

function PrivacyDashboard() {
  const userConsents = [
    {
      userId: 'user_123',
      name: 'María García',
      email: '[email protected]',
      consents: {
        marketing: { granted: true, date: '2024-01-15' },
        analytics: { granted: false, date: '2024-01-15' },
        cookies: { granted: true, date: '2024-01-15' }
      },
      dataRequests: [
        {
          type: 'access',
          date: '2024-02-01',
          status: 'completed'
        }
      ]
    }
  ]

  return (
    <BirhausPrivacyManager
      userConsents={userConsents}
      
      // GDPR compliance
      showGDPRControls={true}
      gdprOptions={{
        allowDataAccess: true,
        allowDataPortability: true,
        allowDataDeletion: true,
        allowConsentWithdrawal: true
      }}
      
      // Spanish-first privacy
      privacyLabels={{
        dataAccess: { es: 'Acceso a Datos', en: 'Data Access' },
        dataPortability: { es: 'Portabilidad', en: 'Portability' },
        dataDeletion: { es: 'Eliminación', en: 'Deletion' }
      }}
      
      // Cookie management
      cookieCategories={[
        { key: 'essential', required: true, nameEs: 'Esenciales' },
        { key: 'analytics', required: false, nameEs: 'Analíticas' },
        { key: 'marketing', required: false, nameEs: 'Marketing' }
      ]}
      
      // Privacy policy integration
      privacyPolicyUrl="/politica-privacidad"
      termsOfServiceUrl="/terminos-servicio"
      
      // Audit integration
      onPrivacyEvent={(event) => {
        console.log('Privacy event:', event)
        // Log privacy actions for audit
      }}
    />
  )
}

GDPR Features

• ✅ Consent Management - Granular user consent tracking
• ✅ Data Access Requests - "Right to know" implementation
• ✅ Data Portability - Export user data in standard formats
• ✅ Data Deletion - "Right to be forgotten" automation
• ✅ Cookie Controls - Granular cookie category management
• ✅ Privacy Audit - Complete privacy action logging

📊 Regulatory Reports

Automated compliance report generation:

import { BirhausRegulatoryReport } from '@birhaus/compliance'

function ComplianceReporting() {
  return (
    <BirhausRegulatoryReport
      reportType="seprelad-monthly"
      
      // Data sources
      transactions={transactionData}
      entities={entityData}
      timeRange={{
        start: new Date('2024-08-01'),
        end: new Date('2024-08-31')
      }}
      
      // Report configuration
      includeGraphs={true}
      includeSummary={true}
      language="es" // Spanish-first reports
      
      // Template customization
      template={{
        logo: '/company-logo.png',
        header: 'Reporte Mensual SEPRELAD',
        footer: 'Documento Confidencial'
      }}
      
      // Export settings
      exportFormats={['pdf', 'excel']}
      autoEmail={{
        recipients: ['[email protected]'],
        subject: 'Reporte Mensual SEPRELAD - Agosto 2024'
      }}
      
      // Compliance validation
      validateBeforeExport={true}
      requiredFields={['entityName', 'reportingPeriod', 'transactionSummary']}
    />
  )
}

✅ Compliance Checklist

Track regulatory requirements across multiple frameworks:

import { BirhausComplianceChecklist } from '@birhaus/compliance'

function ComplianceTracking() {
  const requirements = [
    {
      id: 'seprelad-1',
      framework: 'SEPRELAD',
      requirement: 'Reportar transacciones > $10,000 USD',
      status: 'compliant',
      lastChecked: '2024-08-21',
      evidence: '/docs/seprelad-report-aug-2024.pdf'
    },
    {
      id: 'gdpr-1',
      framework: 'GDPR',
      requirement: 'Política de privacidad actualizada',
      status: 'pending',
      dueDate: '2024-09-01',
      assignee: 'Legal Team'
    }
  ]

  return (
    <BirhausComplianceChecklist
      requirements={requirements}
      
      // Framework filtering
      frameworks={['SEPRELAD', 'GDPR', 'SOX', 'ISO27001']}
      showFrameworkFilter={true}
      
      // Status tracking
      statusTypes={{
        compliant: { color: 'green', labelEs: 'Cumpliendo' },
        pending: { color: 'yellow', labelEs: 'Pendiente' },
        overdue: { color: 'red', labelEs: 'Vencido' }
      }}
      
      // Progress visualization
      showProgressBar={true}
      groupBy="framework"
      
      // Action management
      allowAddRequirement={true}
      allowStatusUpdate={true}
      allowEvidenceUpload={true}
      
      // Notifications
      sendReminders={true}
      reminderDays={[30, 7, 1]} // Days before due date
    />
  )
}

🔐 Data Protection Utilities

Additional utilities for data protection compliance:

import { 
  encryptSensitiveData,
  anonymizeUserData,
  validateDataRetention,
  generatePrivacyReport 
} from '@birhaus/compliance'

// Data encryption for storage
const encryptedData = encryptSensitiveData(userData, {
  algorithm: 'AES-256-GCM',
  keyRotation: true
})

// User data anonymization
const anonymizedData = anonymizeUserData(userData, {
  preserveFields: ['id', 'createdAt'],
  anonymizeFields: ['name', 'email', 'phone'],
  strategy: 'pseudonymization' // or 'randomization'
})

// Data retention compliance
const retentionCheck = validateDataRetention(dataset, {
  retentionPeriod: '7 years',
  category: 'financial',
  regulation: 'SEPRELAD'
})

// Privacy impact assessment
const privacyReport = generatePrivacyReport(dataProcessingActivity, {
  includeRiskAssessment: true,
  includeDataFlow: true,
  language: 'es'
})

🚨 Real-time Monitoring

Set up real-time compliance monitoring:

import { useComplianceMonitor } from '@birhaus/compliance'

function ComplianceMonitor() {
  const {
    violations,
    alerts,
    riskScore,
    subscribe,
    unsubscribe
  } = useComplianceMonitor({
    frameworks: ['SEPRELAD', 'GDPR'],
    realTime: true,
    alertThreshold: 'medium'
  })

  useEffect(() => {
    // Subscribe to compliance events
    const unsubscribeCallback = subscribe('seprelad', (event) => {
      if (event.severity === 'high') {
        // Send immediate alert
        sendAlert('High-risk SEPRELAD violation detected')
      }
    })

    return unsubscribeCallback
  }, [subscribe])

  return (
    <div className="space-y-4">
      {/* Risk Score Display */}
      <div className="p-4 bg-white rounded-lg">
        <h3>Puntuación de Riesgo: {riskScore}/100</h3>
        <div className={`h-2 rounded ${
          riskScore > 70 ? 'bg-red-500' : 
          riskScore > 40 ? 'bg-yellow-500' : 'bg-green-500'
        }`} />
      </div>

      {/* Active Violations */}
      {violations.map(violation => (
        <div key={violation.id} className="p-4 border-l-4 border-red-500">
          <h4>{violation.title}</h4>
          <p>{violation.description}</p>
          <span>Severidad: {violation.severity}</span>
        </div>
      ))}
    </div>
  )
}

🇪🇸 Spanish-First Compliance

All compliance terminology prioritizes Spanish language:

Regulatory Terminology

| Spanish | English | Context | |---------|---------|---------| | Cumplimiento | Compliance | General compliance | | Reporte Regulatorio | Regulatory Report | Official reporting | | Operación Sospechosa | Suspicious Activity | SEPRELAD reporting | | Consentimiento | Consent | GDPR privacy | | Portabilidad de Datos | Data Portability | User rights | | Derecho al Olvido | Right to be Forgotten | Data deletion |

Example Spanish-First Usage

<BirhausSEPRELADDashboard
  titleEs="Panel de Cumplimiento SEPRELAD"
  titleEn="SEPRELAD Compliance Dashboard"
  
  // Spanish regulatory terms
  alerts={{
    threshold: 'Umbral de Reporte Alcanzado',
    suspicious: 'Actividad Sospechosa Detectada',
    incomplete: 'Documentación Incompleta'
  }}
  
  // Spanish report sections
  reportSections={{
    summary: 'Resumen Ejecutivo',
    transactions: 'Transacciones Reportables',
    entities: 'Entidades Involucradas',
    recommendations: 'Recomendaciones'
  }}
/>

📱 Mobile Compliance

Mobile-optimized compliance interfaces:

<BirhausPrivacyManager
  // Mobile-first consent management
  mobileOptimized={true}
  
  // Touch-friendly controls
  touchTargets="large"
  
  // Simplified mobile UI
  mobileLayout={{
    hideSecondaryInfo: true,
    stackControls: true,
    expandableDetails: true
  }}
  
  // Mobile notifications
  pushNotifications={{
    consentUpdates: true,
    privacyRequests: true,
    dataBreaches: true
  }}
/>

🧪 Testing Compliance Components

import { render, screen } from '@testing-library/react'
import { BirhausAuditTrail } from '@birhaus/compliance'
import { complianceTestUtils } from '@birhaus/test-utils'

describe('BirhausAuditTrail', () => {
  it('should display audit events in Spanish', () => {
    render(
      <BirhausAuditTrail
        events={mockAuditEvents}
        titleEs="Registro de Auditoría"
      />
    )
    
    expect(screen.getByText('Registro de Auditoría')).toBeInTheDocument()
  })

  it('should meet SEPRELAD compliance requirements', async () => {
    const { container } = render(
      <BirhausSEPRELADDashboard transactions={mockTransactions} />
    )
    
    const complianceResult = await complianceTestUtils.validateSEPRELAD(container)
    expect(complianceResult.isCompliant).toBe(true)
  })
})

🚀 Performance & Security

• Bundle Size: ~65KB gzipped (including crypto utilities)
• Data Encryption: AES-256-GCM for sensitive data
• Audit Integrity: SHA-256 hashing for tamper detection
• Real-time Processing: WebSocket-based compliance monitoring
• Secure Storage: Encrypted local storage for temporary data

🐛 Troubleshooting

Common Issues

SEPRELAD reports not generating

// Ensure transaction data has required fields
const transaction = {
  monto: 15000,
  moneda: 'USD', // Required for USD conversion
  documentoIdentidad: '1.234.567', // Required for reporting
  tipoDocumento: 'CI' // Required field
}

GDPR consent not saving

// Ensure BirhausProvider is configured
<BirhausProvider 
  compliance={{
    gdpr: true,
    cookieConsent: true
  }}
>
  <App />
</BirhausProvider>

Audit events not displaying

// Check date format for audit events
const auditEvent = {
  timestamp: new Date().toISOString(), // ISO format required
  // ... other fields
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Compliance Standards

When contributing to compliance features:

• Follow SEPRELAD documentation standards
• Implement GDPR requirements completely
• Maintain Spanish-first language priority
• Include comprehensive audit logging
• Add proper security measures

📄 License

MIT © BIRHAUS Team

Cumplimiento regulatorio simplificado con BIRHAUS 🏛️🇪🇸