brazil-swift-ops/docs/DEVELOPER_GUIDE.md

Developer Guide

Getting Started

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0

Installation

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run type checking
pnpm type-check

# Run tests
pnpm test

Development

# 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

# 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

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:

{
  "dependencies": {
    "@brazil-swift-ops/types": "workspace:*"
  }
}

Type Exports

Export types from index.ts:

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

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:

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

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

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

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

Type Errors

# Check types
pnpm type-check

# Rebuild types package
cd packages/types && pnpm build

Test Failures

# Run tests with verbose output
pnpm test -- --reporter=verbose

Resources

• TypeScript Handbook
• React Documentation
• Vitest Documentation
• Turborepo Documentation