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
320
docs/DEVELOPER_GUIDE.md
Normal file
320
docs/DEVELOPER_GUIDE.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user