brazil-swift-ops/docs/DEVELOPER_GUIDE.md

# 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)