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
2026-01-23 16:40:06 -08:00
parent 8322c8bf28
commit 13ee01e749
7 changed files with 1195 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -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
--- a/docs/DEVELOPER_GUIDE.md
+++ b/docs/DEVELOPER_GUIDE.md
@@ -0,0 +1,320 @@
+# Developer Guide
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- pnpm >= 8.0.0
+
+### Installation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run type checking
+pnpm type-check
+
+# Run tests
+pnpm test
+```
+
+### Development
+
+```bash
+# Start development server
+pnpm dev
+
+# Build for production
+pnpm build
+```
+
+## Project Structure
+
+### Monorepo Workspaces
+
+- `apps/web`: React web application
+- `packages/types`: Shared TypeScript types
+- `packages/utils`: Shared utilities
+- `packages/rules-engine`: Regulatory rules engine
+- `packages/iso20022`: ISO 20022 message handling
+- `packages/treasury`: Treasury management
+- `packages/audit`: Audit logging
+
+### Adding a New Package
+
+1. Create directory in `packages/`
+2. Add `package.json` with workspace dependencies
+3. Add `tsconfig.json` extending root config
+4. Update root `tsconfig.json` references
+5. Add to `pnpm-workspace.yaml`
+
+### Adding a New App
+
+1. Create directory in `apps/`
+2. Add `package.json` with workspace dependencies
+3. Add `tsconfig.json` extending root config
+4. Update `turbo.json` build pipeline
+
+## Code Style
+
+### TypeScript
+
+- Use strict TypeScript configuration
+- Prefer interfaces over types for public APIs
+- Use explicit return types for exported functions
+- Avoid `any` - use `unknown` if needed
+
+### Naming Conventions
+
+- **Files**: kebab-case (`transaction-store.ts`)
+- **Types/Interfaces**: PascalCase (`Transaction`, `BrazilRegulatoryResult`)
+- **Functions**: camelCase (`evaluateTransaction`)
+- **Constants**: UPPER_SNAKE_CASE (`DEFAULT_CONFIG`)
+- **Classes**: PascalCase (`AuditLogStore`)
+
+### Code Organization
+
+```
+package/
+├── src/
+│   ├── index.ts          # Public API exports
+│   ├── types.ts          # Type definitions (if not in @types package)
+│   ├── core.ts           # Core functionality
+│   ├── utils.ts          # Internal utilities
+│   └── __tests__/        # Test files
+├── package.json
+└── tsconfig.json
+```
+
+## Testing
+
+### Unit Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests for specific package
+cd packages/utils && pnpm test
+```
+
+### Writing Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { myFunction } from '../my-module';
+
+describe('myFunction', () => {
+  it('should do something', () => {
+    const result = myFunction(input);
+    expect(result).toBe(expected);
+  });
+});
+```
+
+### Test Coverage
+
+Target: 80%+ coverage for critical functions
+
+## Building
+
+### Build Process
+
+1. TypeScript compilation (`tsc`)
+2. Package bundling (if needed)
+3. Type declaration generation
+
+### Build Order
+
+Turborepo handles build order automatically based on dependencies:
+1. `types` (no dependencies)
+2. `utils` (depends on `types`)
+3. Other packages (depend on `types` and `utils`)
+4. `web` (depends on all packages)
+
+## Type Safety
+
+### Internal Package Dependencies
+
+Use workspace protocol:
+```json
+{
+  "dependencies": {
+    "@brazil-swift-ops/types": "workspace:*"
+  }
+}
+```
+
+### Type Exports
+
+Export types from `index.ts`:
+```typescript
+export type { Transaction, BrazilRegulatoryResult } from './types';
+```
+
+## Error Handling
+
+### Error Types
+
+Use custom error classes from `@brazil-swift-ops/utils`:
+- `ValidationError`: Input validation failures
+- `BusinessRuleError`: Business rule violations
+- `SystemError`: System-level errors
+- `ExternalServiceError`: External API failures
+
+### Error Logging
+
+```typescript
+import { getLogger } from '@brazil-swift-ops/utils';
+
+const logger = getLogger();
+logger.error('Operation failed', error, { context });
+```
+
+## Configuration
+
+### Environment Variables
+
+Configuration is loaded from environment variables via `@brazil-swift-ops/utils/config`:
+
+```typescript
+import { getConfig } from '@brazil-swift-ops/utils';
+
+const config = getConfig();
+```
+
+### Configuration Files
+
+- `.env`: Local development (not committed)
+- `.env.example`: Example configuration (committed)
+
+## Logging
+
+### Structured Logging
+
+```typescript
+import { getLogger, generateCorrelationId } from '@brazil-swift-ops/utils';
+
+const logger = getLogger();
+const correlationId = generateCorrelationId();
+logger.setCorrelationId(correlationId);
+
+logger.info('Transaction processed', { transactionId: 'TXN-123' });
+```
+
+### Log Levels
+
+- `debug`: Detailed debugging information
+- `info`: General informational messages
+- `warn`: Warning messages
+- `error`: Error messages
+- `fatal`: Critical errors
+
+## Version Management
+
+### Version Information
+
+```typescript
+import { getVersion, getVersionString } from '@brazil-swift-ops/utils';
+
+const version = getVersion();
+console.log(getVersionString()); // "brazil-swift-ops v1.0.0"
+```
+
+### Versioning Strategy
+
+- Semantic versioning (MAJOR.MINOR.PATCH)
+- Version in root `package.json` is source of truth
+- Rule set versions tracked separately in audit logs
+
+## Contributing
+
+### Workflow
+
+1. Create feature branch
+2. Make changes
+3. Write/update tests
+4. Run tests and type checking
+5. Commit with descriptive message
+6. Push and create PR
+
+### Commit Messages
+
+Format: `type(scope): description`
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `test`: Tests
+- `refactor`: Code refactoring
+- `chore`: Maintenance
+
+Example: `feat(rules-engine): add AML structuring detection`
+
+## Common Tasks
+
+### Adding a New Rule
+
+1. Create rule function in `packages/rules-engine/src/`
+2. Add result type in `packages/types/src/regulatory.ts`
+3. Register in `packages/rules-engine/src/orchestrator.ts`
+4. Add tests in `packages/rules-engine/src/__tests__/`
+
+### Adding a New ISO 20022 Message Type
+
+1. Define type in `packages/types/src/iso20022.ts`
+2. Create builder in `packages/iso20022/src/`
+3. Add validation function
+4. Update exporter
+5. Add tests
+
+### Adding a New UI Page
+
+1. Create component in `apps/web/src/pages/`
+2. Add route in `apps/web/src/App.tsx`
+3. Add navigation link
+4. Create store if needed
+
+## Troubleshooting
+
+### Build Errors
+
+```bash
+# Clean and rebuild
+pnpm clean
+pnpm install
+pnpm build
+```
+
+### Type Errors
+
+```bash
+# Check types
+pnpm type-check
+
+# Rebuild types package
+cd packages/types && pnpm build
+```
+
+### Test Failures
+
+```bash
+# Run tests with verbose output
+pnpm test -- --reporter=verbose
+```
+
+## Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [React Documentation](https://react.dev/)
+- [Vitest Documentation](https://vitest.dev/)
+- [Turborepo Documentation](https://turbo.build/repo/docs)