# 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