Complete remaining todos: MT103 mapping, version management, logging, config, FX rates, tests, docs
- 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
This commit is contained in:
defiQUG
259
docs/ARCHITECTURE.md
Normal file
259
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user