13ee01e749
- Enhanced MT103 mapping with all fields and validation - Implemented version management system - Added structured logging with correlation IDs - Added configuration management from environment variables - Implemented FX rate service with caching and provider abstraction - Added comprehensive unit tests - Created architecture and developer documentation
260 lines
6.8 KiB
Markdown
260 lines
6.8 KiB
Markdown
# 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
|