@birhaus/compliance
Version:
BIRHAUS v3.0 Radical Minimalist Compliance Components - Glass morphism regulatory dashboards, audit trails & SEPRELAD compliance with Spanish-first support
689 lines (563 loc) • 18.2 kB
Markdown
# @birhaus/compliance
**Regulatory compliance and audit trail components for BIRHAUS design system**
[](https://badge.fury.io/js/@birhaus%2Fcompliance)
[](https://www.typescriptlang.org/)
[](#spanish-first-design)
[](#seprelad-compliance)
[](#gdpr-compliance)
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
```bash
npm install @birhaus/compliance
# Peer dependencies
npm install react react-dom @birhaus/tokens @birhaus/primitives @birhaus/provider
```
## 🎯 Quick Start
```tsx
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:
```tsx
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
```tsx
// 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: 'compliance@bank.py'
}}
/>
```
## 📋 Audit Trail
Complete audit trail visualization with Spanish-first documentation:
```tsx
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:
```tsx
import { BirhausPrivacyManager } from '@birhaus/compliance'
function PrivacyDashboard() {
const userConsents = [
{
userId: 'user_123',
name: 'María García',
email: 'maria@example.com',
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:
```tsx
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: ['compliance@company.py'],
subject: 'Reporte Mensual SEPRELAD - Agosto 2024'
}}
// Compliance validation
validateBeforeExport={true}
requiredFields={['entityName', 'reportingPeriod', 'transactionSummary']}
/>
)
}
```
## ✅ Compliance Checklist
Track regulatory requirements across multiple frameworks:
```tsx
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:
```tsx
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:
```tsx
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
```tsx
<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:
```tsx
<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
```tsx
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**
```tsx
// 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**
```tsx
// Ensure BirhausProvider is configured
<BirhausProvider
compliance={{
gdpr: true,
cookieConsent: true
}}
>
<App />
</BirhausProvider>
```
**Audit events not displaying**
```tsx
// 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](../../CONTRIBUTING.md).
### 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 🏛️🇪🇸**