brazil-swift-ops/docs/ARCHITECTURE.md

Architecture Documentation

Overview

The Brazil SWIFT Operations Platform is a regulator-grade software system for processing SWIFT international payments and foreign exchange transactions in compliance with Brazilian regulations.

System Architecture

Monorepo Structure

The project uses a monorepo architecture with pnpm workspaces and Turborepo for build orchestration:

brazil-swift-ops/
├── apps/
│   └── web/              # React web application
├── packages/
│   ├── types/            # Shared TypeScript types
│   ├── utils/            # Shared utilities
│   ├── rules-engine/     # Brazil regulatory rules engine
│   ├── iso20022/         # ISO 20022 message handling
│   ├── treasury/         # Treasury management
│   └── audit/            # Audit logging and reporting
└── docs/                 # Documentation

Package Dependencies

web
├── types
├── utils
├── rules-engine
│   ├── types
│   └── utils
├── iso20022
│   ├── types
│   └── utils
├── treasury
│   ├── types
│   └── utils
└── audit
    ├── types
    └── utils

Core Components

1. Rules Engine (@brazil-swift-ops/rules-engine)

The rules engine evaluates transactions against Brazilian regulatory requirements:

• Threshold Check: USD 10,000 reporting requirement
• Documentation Check: CPF/CNPJ validation, purpose of payment
• FX Contract Check: Validates FX contract linkage
• IOF Calculation: Calculates IOF tax based on transaction direction
• AML Check: Detects structuring patterns (rolling window analysis)

Decision Flow:

1. Evaluate all rules
2. Aggregate results
3. Determine overall decision (Allow/Hold/Escalate)
4. Assign severity level

2. ISO 20022 Message Handling (@brazil-swift-ops/iso20022)

Supports three ISO 20022 message types:

• pacs.008: FIToFICustomerCreditTransfer
• pacs.009: FinancialInstitutionCreditTransfer
• pain.001: CustomerCreditTransferInitiation

Features:

• Message creation from transactions
• Message validation
• XML/JSON export
• MT103 mapping (SWIFT legacy format)

3. Treasury Management (@brazil-swift-ops/treasury)

Manages treasury accounts and subledgers:

• Account Store: Parent treasury accounts
• Subledger Accounts: Child accounts linked to parent
• Posting Engine: Deterministic balance updates
• Transfer System: Inter-subledger transfers
• Reporting: Subledger-level reporting

4. Audit System (@brazil-swift-ops/audit)

Immutable audit logging:

• Audit Logger: Creates audit logs for all transactions
• BCB Reports: Generates Banco Central do Brasil reports
• Retention Policies: Configurable data retention
• Version Tracking: Rule set version governance

5. Utilities (@brazil-swift-ops/utils)

Shared utilities:

• Currency Conversion: FX rate handling
• Validation: CPF/CNPJ validation
• Date Utilities: Rolling windows, retention calculations
• E&O Uplift: Errors & Omissions calculation (10%)
• Error Handling: User-friendly error messages
• Logging: Structured JSON logging
• Configuration: Environment-based config management
• Version Management: Centralized version tracking

Data Flow

Transaction Processing Flow

1. User submits transaction
   ↓
2. Input validation
   ↓
3. Rules engine evaluation
   ├── Threshold check
   ├── Documentation check
   ├── FX contract check
   ├── IOF calculation
   └── AML check
   ↓
4. Decision (Allow/Hold/Escalate)
   ↓
5. ISO 20022 message creation (if allowed)
   ↓
6. Treasury posting (if allowed)
   ↓
7. Audit logging
   ↓
8. BCB reporting (if required)

Batch Processing Flow

1. User submits batch of transactions
   ↓
2. Validate all transactions
   ↓
3. Evaluate rules for each transaction
   ↓
4. Aggregate batch-level E&O uplift
   ↓
5. Generate batch-level report
   ↓
6. Create ISO 20022 batch message (pain.001)
   ↓
7. Audit logging for batch

Technology Stack

Frontend

• React 18: UI framework
• TypeScript: Type safety
• Tailwind CSS: Styling
• Vite: Build tool
• React Router: Routing
• Zustand: State management

Backend (Packages)

• TypeScript: Type safety
• Turborepo: Monorepo build orchestration
• pnpm: Package manager

Testing

• Vitest: Unit and integration tests
• Playwright: E2E tests (planned)

Regulatory Compliance

Brazilian Regulations

1. USD 10,000 Reporting Threshold: Per-transaction reporting to BCB
2. CPF/CNPJ Validation: Required for all parties
3. Purpose of Payment: Mandatory field
4. IOF Tax: Calculated based on transaction direction
5. FX Contract Linkage: Required for FX transactions
6. AML Structuring Detection: 30-day rolling window

Audit Requirements

• Immutable audit logs
• 7-year retention (configurable)
• BCB-compliant report generation
• Rule version tracking

Security Considerations

Current Implementation

• Input validation and sanitization
• Error handling without exposing internals
• Type-safe data structures

Planned Enhancements

• Authentication and authorization
• Data encryption at rest and in transit
• API security (rate limiting, authentication)
• XSS protection

Performance Considerations

Current Implementation

• In-memory stores (for development)
• Efficient rule evaluation
• Batch processing support

Planned Enhancements

• Database persistence
• Caching layer (FX rates, rule results)
• Parallel batch processing
• Frontend optimization (code splitting, lazy loading)

Deployment Architecture

Development

• Local development with Vite dev server
• In-memory data stores
• Hot module replacement

Production (Planned)

• Containerized deployment (Docker)
• Database persistence (PostgreSQL)
• Log aggregation (ELK stack or similar)
• Monitoring and alerting (Prometheus, Grafana)

Extension Points

Adding New Rules

1. Create rule function in packages/rules-engine/src/
2. Add rule result type in packages/types/src/regulatory.ts
3. Register in orchestrator
4. Update UI to display rule results

Adding New Message Types

1. Define message type in packages/types/src/iso20022.ts
2. Create message builder in packages/iso20022/src/
3. Add validation function
4. Update exporter if needed

Adding New Treasury Features

1. Extend account types in packages/types/src/treasury.ts
2. Add business logic in packages/treasury/src/
3. Update UI components

Future Enhancements

See RECOMMENDATIONS.md for detailed roadmap including:

• Database persistence
• Real-time FX rates
• Comprehensive testing
• Security features
• Performance optimizations
• Documentation