# Contributing to Mercury UPI PSP Platform

Thank you for your interest in contributing to the Mercury UPI PSP Platform! This document provides guidelines and procedures for contributing to this financial technology project.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing Requirements](#testing-requirements)
- [Security Guidelines](#security-guidelines)
- [Pull Request Process](#pull-request-process)
- [Documentation](#documentation)

## Code of Conduct

As a financial technology platform, we maintain the highest standards of professionalism and ethics. All contributors must:

- Follow ethical coding practices
- Prioritize security and user data protection
- Maintain confidentiality of sensitive financial information
- Collaborate respectfully with team members
- Report security vulnerabilities responsibly

## Getting Started

### Prerequisites

- Elixir 1.14+ and OTP 25+
- MySQL 8.0+
- Node.js 18+ (for asset compilation)
- Git

### Development Setup

1. Clone the repository
2. Install dependencies: `mix deps.get`
3. Set up the database: `mix ecto.setup`
4. Install frontend dependencies: `cd assets && npm install`
5. Start the development server: `mix phx.server`

### Environment Configuration

Copy the environment variables from the README.md and configure:

```bash
export DATABASE_URL="mysql://username:password@localhost/mercury_upi_psp_dev"
export SECRET_KEY_BASE="your-secret-key-base"
export PHX_HOST="localhost"
```

## Development Workflow

### Branch Naming

- `feature/description` - New features
- `bugfix/description` - Bug fixes
- `security/description` - Security-related changes
- `docs/description` - Documentation updates
- `refactor/description` - Code refactoring

### Commit Messages

Follow conventional commit format:

```
type(scope): brief description

- More detailed explanation if needed
- List specific changes
- Reference issue numbers
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `security`

Examples:
```
feat(international): add Singapore corridor support
fix(qr): resolve QR validation timeout issue
security(auth): implement rate limiting for login attempts
```

## Coding Standards

### Elixir/Phoenix Standards

1. **Code Formatting**
   - Use `mix format` before committing
   - Follow `.formatter.exs` configuration
   - Maximum line length: 100 characters

2. **Naming Conventions**
   - Functions and variables: `snake_case`
   - Modules: `PascalCase`
   - Atoms: `:snake_case`
   - Constants: `@uppercase_with_underscores`

3. **Documentation**
   - Add `@doc` for all public functions
   - Include `@spec` for type specifications
   - Provide examples in documentation

4. **Error Handling**
   - Use `{:ok, result}` and `{:error, reason}` tuples
   - Avoid raising exceptions in business logic
   - Provide meaningful error messages

### Database Standards

1. **Migrations**
   - Use descriptive names with timestamps
   - Include rollback instructions
   - Add proper indexes and constraints
   - Test migrations thoroughly

2. **Schema Design**
   - Use proper data types for financial amounts (decimal)
   - Add foreign key constraints
   - Include timestamps on all tables
   - Use meaningful column names

### API Standards

1. **RESTful Design**
   - Use proper HTTP methods (GET, POST, PUT, DELETE)
   - Implement consistent response formats
   - Use appropriate HTTP status codes
   - Version APIs properly

2. **Request/Response Format**
   ```json
   {
     "status": "success|error",
     "data": {...},
     "message": "Human readable message",
     "errors": [...] // Only for error responses
   }
   ```

## Testing Requirements

### Test Coverage

- Maintain minimum 90% test coverage
- Write tests for all business logic
- Include integration tests for APIs
- Test error scenarios and edge cases

### Test Categories

1. **Unit Tests**
   - Test individual functions and modules
   - Mock external dependencies
   - Fast execution (<5ms per test)

2. **Integration Tests**
   - Test API endpoints end-to-end
   - Test database interactions
   - Test external service integrations (mocked)

3. **Property Tests**
   - Use StreamData for property-based testing
   - Test data validation logic
   - Test financial calculations

### Running Tests

```bash
# Run all tests
mix test

# Run with coverage
mix test --cover

# Run specific test file
mix test test/da_product_app_web/controllers/api/v1/upi_controller_test.exs

# Run tests matching pattern
mix test --only tag:integration
```

## Security Guidelines

⚠️ **CRITICAL**: This is a financial platform. Security is non-negotiable.

### Security Checklist

- [ ] Input validation on all user inputs
- [ ] SQL injection prevention (use Ecto parameterized queries)
- [ ] XSS prevention (escape output)
- [ ] CSRF protection enabled
- [ ] Proper authentication and authorization
- [ ] Sensitive data encryption
- [ ] Secure API key management
- [ ] Audit logging for financial operations

### Sensitive Data Handling

1. **Never log sensitive information**:
   - Payment card details
   - Bank account numbers
   - User passwords or tokens
   - API keys or secrets

2. **Data Encryption**:
   - Encrypt sensitive data at rest
   - Use HTTPS for all communications
   - Implement proper key management

3. **Access Control**:
   - Implement role-based access control
   - Use principle of least privilege
   - Regular access reviews

### Security Testing

- Run security linters: `mix sobelow`
- Perform dependency audits: `mix deps.audit`
- Test authentication and authorization
- Validate input sanitization

## Pull Request Process

### Before Submitting

1. **Code Quality**
   - [ ] Code follows style guidelines
   - [ ] All tests pass
   - [ ] Code coverage maintained
   - [ ] No security vulnerabilities

2. **Documentation**
   - [ ] Code is properly documented
   - [ ] API documentation updated
   - [ ] CHANGELOG updated (for user-facing changes)

3. **Testing**
   - [ ] New tests added for new functionality
   - [ ] Edge cases covered
   - [ ] Integration tests pass

### PR Description Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Security fix

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Security Review
- [ ] No sensitive data exposed
- [ ] Input validation implemented
- [ ] Authorization checks in place

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests pass
```

### Review Process

1. **Automated Checks**
   - Tests must pass
   - Code quality checks pass
   - Security scans pass

2. **Manual Review**
   - Code review by at least one team member
   - Security review for financial logic
   - Architecture review for significant changes

3. **Approval Requirements**
   - Technical lead approval for architecture changes
   - Security team approval for security-related changes
   - QA approval for user-facing changes

## Documentation

### Code Documentation

- Document all public APIs
- Include usage examples
- Explain complex business logic
- Document security considerations

### Project Documentation

- Keep README.md updated
- Update API documentation
- Maintain deployment guides
- Document configuration changes

### Domain Documentation

- Explain UPI-specific concepts
- Document regulatory requirements
- Maintain partner integration guides
- Keep troubleshooting guides current

## Development Best Practices

### Performance

- Use database indexes appropriately
- Implement caching for expensive operations
- Monitor query performance
- Optimize critical code paths

### Monitoring

- Add proper logging for debugging
- Implement health checks
- Monitor key metrics
- Set up alerting for errors

### Deployment

- Use feature flags for gradual rollouts
- Implement proper rollback procedures
- Test migrations in staging
- Coordinate with operations team

## Getting Help

### Resources

- Project documentation in `/docs`
- API documentation in `COMPLETE_UPI_API_DOCUMENTATION.md`
- NPCI specifications in `UPI-Specififcation-Document.md`
- Testing guides in `TESTING_GUIDE.md`

### Support Channels

- Technical questions: Create GitHub issue
- Security concerns: Email security team
- Architecture discussions: Schedule team meeting
- Urgent issues: Contact on-call engineer

## License

This project is proprietary software. All contributions become part of the proprietary codebase. By contributing, you agree to assign rights to MomentPay.

---

Thank you for contributing to the Mercury UPI PSP Platform! Your efforts help build a secure and reliable payment infrastructure.