bigbasealpha/CONTRIBUTING.md

Enterprise-Grade NoSQL Database System with Modular Logger & Offline HSM Security - Complete database platform with professional text-based logging, encryption, caching, indexing, JWT authentication, auto-generated REST API, real-time dashboard, and maste

# Contributing to BigBaseAlpha

We welcome contributions to BigBaseAlpha! This document provides guidelines for contributing to this project.

## 🚀 Getting Started

### Prerequisites
- Node.js 14.0.0 or higher
- Git

### Setup Development Environment

1. Fork the repository
2. Clone your fork:
   ```bash
   git clone https://github.com/ByAlphas/bigbasealpha.git
   cd bigbasealpha
   ```

3. Install dependencies:
   ```bash
   npm install
   ```

4. Run tests to ensure everything works:
   ```bash
   npm test
   ```

5. Try the examples:
   ```bash
   node examples/basic-usage.js
   node demo-v1.5.0.js  # v1.5.0 Enterprise features demo
   node demo-hsm.js     # v1.5.0 HSM Security demo (100% Offline)
   ```

6. Test the v1.5.0 enterprise features:
   ```bash
   npm run services:start    # Start all v1.5.0 services
   npm run api:start        # REST API (port 3001)
   npm run dashboard:realtime # Real-time dashboard (port 8080)
   npm run auth:demo        # Create demo admin user
   npm run hsm:demo         # HSM security demonstration
   ```

## 🔐 HSM Development Guidelines (v1.5.0)

### Working with HSM Module
BigBaseAlpha v1.5.0 includes a complete offline HSM implementation. When contributing to HSM-related features:

#### HSM Security Principles
- **100% Offline Operation**: Never add network dependencies to HSM code
- **Air-Gapped Ready**: Ensure all HSM functions work without internet
- **Tamper Detection**: Maintain system fingerprinting and integrity checks
- **Encrypted Storage**: All keys must be encrypted at rest using AES-256-GCM
- **Audit Trail**: Log all HSM operations for security monitoring

#### HSM Code Standards
```javascript
// Good: Proper HSM operation with error handling
async function secureOperation(data, keyId) {
  try {
    const encrypted = await this.hsm.encrypt(data, keyId);
    this.hsm._logAccess('encrypt', keyId);
    return encrypted;
  } catch (error) {
    this.emit('hsm:error', error);
    throw new Error(`HSM operation failed: ${error.message}`);
  }
}

// Bad: Direct crypto without HSM protection
function unsecureOperation(data) {
  return crypto.createHash('sha256').update(data).digest('hex');
}
```

#### HSM Testing Requirements
- Test all HSM operations in offline mode
- Verify tamper detection mechanisms
- Validate key generation with different algorithms
- Test backup and recovery procedures
- Ensure audit logging captures all operations

## 📝 Development Guidelines

### Code Style
- Use modern ES6+ JavaScript
- Follow existing code formatting
- Write clear, descriptive variable and function names
- Add JSDoc comments for public APIs
- Keep functions small and focused

### File Structure
```
src/
├── core/           # Main database engine
├── storage/        # Storage adapters
├── security/       # Security modules
├── auth/           # JWT Authentication & User Management (v1.5.0)
├── api/            # Auto-generated REST API (v1.5.0)
├── dashboard/      # Web dashboard & Real-time monitoring (v1.5.0)
├── replication/    # Master-slave replication (v1.5.0)
├── indexing/       # Indexing system
├── caching/        # Caching layer
├── plugins/        # Plugin system
├── cli/           # Command-line interface
└── utils/         # Utilities
```

### Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes
- Use UPPER_CASE for constants
- Use descriptive names that explain purpose

## 🧪 Testing

### Running Tests
```bash
# Run all tests
npm test

# Run specific test file
node --test test/bigbase.test.js

# Run with verbose output
node --test --reporter=verbose test/**/*.test.js

# Test v1.5.0 enterprise features
npm run test:auth         # Authentication system tests
npm run test:api          # REST API tests
npm run test:replication  # Replication tests
npm run demo-v1.5.0       # Complete feature integration test
```

### Writing Tests
- Place tests in the `test/` directory
- Use the built-in Node.js test runner
- Follow the existing test patterns
- Test both success and error cases
- Include performance tests for critical paths

### Test Coverage
- Aim for high test coverage
- Test edge cases and error conditions
- Include integration tests for complex workflows

## 🐛 Bug Reports

When reporting bugs, please include:

1. **Description**: Clear description of the issue
2. **Steps to Reproduce**: Exact steps to reproduce the bug
3. **Expected Behavior**: What should happen
4. **Actual Behavior**: What actually happens
5. **Environment**: Node.js version, OS, etc.
6. **Code Sample**: Minimal code that reproduces the issue

Use this template:

```markdown
## Bug Description
Brief description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- Node.js version: 
- OS: 
- BigBaseAlpha version: 

## Code Sample
```javascript
// Minimal code to reproduce the issue
```

## ✨ Feature Requests

For feature requests, please include:

1. **Use Case**: Why is this feature needed?
2. **Description**: Detailed description of the feature
3. **Examples**: Code examples of how it would be used
4. **Alternatives**: Other ways to achieve the same goal

## 🔧 Pull Requests

### Before Submitting
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes
4. Add/update tests
5. Ensure all tests pass: `npm test`
6. Update documentation if needed
7. Commit with clear messages

### Pull Request Process

1. **Create Pull Request**
   - Use a clear, descriptive title
   - Reference any related issues
   - Provide detailed description of changes

2. **Pull Request Template**
   ```markdown
   ## Description
   Brief description of changes

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

   ## Testing
   - [ ] Tests pass locally
   - [ ] Added new tests for changes
   - [ ] Updated existing tests

   ## Checklist
   - [ ] Code follows project style guidelines
   - [ ] Self-review completed
   - [ ] Documentation updated
   - [ ] No new warnings introduced
   ```

3. **Review Process**
   - Code will be reviewed by maintainers
   - Address any feedback
   - Keep the PR up to date with main branch

## 📚 Documentation

### Updating Documentation
- Update README.md for new features
- Add JSDoc comments for new APIs
- Update examples if behavior changes
- Include usage examples in documentation

### Documentation Style
- Use clear, concise language
- Include code examples
- Explain both what and why
- Keep examples up to date

## 🏗️ Architecture Guidelines

### Core Principles
- **Modularity**: Keep components loosely coupled
- **Performance**: Optimize for speed and memory usage
- **Security**: Security by design, not as an afterthought
- **Extensibility**: Support plugins and customization
- **Reliability**: Fail gracefully, provide clear error messages

### Adding New Features

1. **Plan the Feature**
   - Consider impact on existing code
   - Design for extensibility
   - Think about performance implications

2. **Implementation**
   - Follow existing patterns
   - Add comprehensive tests
   - Update documentation

3. **Integration**
   - Ensure compatibility with existing features
   - Test with various configurations
   - Consider plugin interactions

## 🔌 Plugin Development

### Creating Plugins
```javascript
export default {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Description of my plugin',
  
  async onInit(db) {
    // Initialize plugin
  },
  
  async onWrite(collection, data) {
    // Handle write operations
  }
};
```

### Plugin Guidelines
- Follow the plugin interface
- Handle errors gracefully
- Don't modify core database state directly
- Provide clear documentation
- Include tests for your plugin

## 📋 Release Process

### Versioning
We follow [Semantic Versioning](https://semver.org/):
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)

### Release Checklist
1. Update version in package.json
2. Update CHANGELOG.md
3. Run full test suite
4. Update documentation
5. Create release notes
6. Tag release in Git

## 🤝 Community Guidelines

### Code of Conduct
- Be respectful and inclusive
- Welcome newcomers
- Give constructive feedback
- Focus on the issue, not the person
- Help others learn and grow

### Communication
- Use GitHub issues for bugs and features
- Be clear and concise in communication
- Provide context and examples
- Be patient with responses

## 🆘 Getting Help

### Resources
- [GitHub Issues](https://github.com/ByAlphas/bigbasealpha/issues)
- [Documentation](README.md)
- [Examples](examples/)

### Questions
- Check existing issues first
- Provide clear context
- Include relevant code samples
- Be specific about what you're trying to achieve

## 🎯 Good First Issues

Look for issues labeled with:
- `good first issue`
- `beginner friendly`
- `documentation`
- `help wanted`

These are great starting points for new contributors!

## 🙏 Recognition

Contributors will be recognized in:
- README.md contributors section
- Release notes
- Special thanks in major releases

Thank you for contributing to BigBaseAlpha! 🚀