> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sammwyy/mikuMikuBeam/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for contributing to Miku Miku Beam

## Welcome Contributors!

Thank you for your interest in contributing to Miku Miku Beam! We welcome contributions of all kinds including new attack protocols, bug fixes, and improvements.

## Getting Started

<Steps>
  <Step title="Fork and Clone">
    Fork the repository and clone it to your local machine:

    ```bash theme={null}
    git clone https://github.com/sammwyy/mikumikubeam.git
    cd mikumikubeam
    ```
  </Step>

  <Step title="Install Dependencies">
    Install all required dependencies for both Go and the web client:

    ```bash theme={null}
    make prepare
    ```

    This command runs:

    * `go mod tidy` for Go dependencies
    * `npm install` in the web-client directory
  </Step>

  <Step title="Create Required Files">
    Set up the necessary data files:

    ```bash theme={null}
    # Create proxies file (one per line)
    echo "http://proxy1:8080" > data/proxies.txt

    # Create user agents file (one per line)
    echo "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" > data/uas.txt
    ```
  </Step>

  <Step title="Build and Test">
    Build all components and verify everything works:

    ```bash theme={null}
    make all
    make run-server
    ```

    Visit `http://localhost:3000` to test the web interface.
  </Step>
</Steps>

## Development Workflow

### Building Components

You can build individual components or everything at once:

```bash theme={null}
# Build everything (recommended)
make all

# Or build individually
make webclient    # Build React frontend
make cli          # Build CLI binary
make server       # Build server binary
```

### Running Components

<CodeGroup>
  ```bash Server theme={null}
  make run-server
  # Or directly:
  ./bin/mmb-server
  ```

  ```bash CLI theme={null}
  make run-cli ARGS="attack http_flood http://example.com"
  # Or directly:
  ./bin/mmb-cli attack http_flood http://example.com --verbose
  ```
</CodeGroup>

### Cleaning Build Artifacts

```bash theme={null}
make clean
```

## Code Structure

<Note>
  Before making changes, familiarize yourself with the [project structure](/development/project-structure) to understand how components are organized.
</Note>

### Key Directories

* **`cmd/`** - Main applications (CLI and server)
* **`internal/`** - Core engine and attack implementations
* **`pkg/`** - Shared packages and utilities
* **`web-client/`** - React-based frontend

## Types of Contributions

### Bug Fixes

If you find a bug:

1. Check if an issue already exists
2. Create a new issue if needed with reproduction steps
3. Submit a PR with the fix
4. Include tests if applicable

### New Attack Methods

Want to add a new attack method? Check out our detailed guide:

<Card title="Adding New Attack Methods" icon="plus" href="/development/adding-attacks">
  Learn how to implement and register new attack methods with step-by-step instructions.
</Card>

### Feature Enhancements

For new features:

1. Open an issue to discuss the feature first
2. Get feedback from maintainers
3. Implement the feature
4. Submit a PR with documentation updates

### Documentation

Documentation improvements are always welcome:

* Fix typos or unclear explanations
* Add examples and use cases
* Improve setup instructions
* Add troubleshooting guides

## Coding Standards

### Go Code

* Follow standard Go conventions and formatting
* Use `gofmt` to format your code
* Add comments for exported functions and types
* Keep functions focused and testable

```go theme={null}
// Good: Clear, focused function with documentation
// Fire sends a single HTTP flood request to the target
func (w *floodWorker) Fire(ctx context.Context, params core.AttackParams, 
    p core.Proxy, ua string, logCh chan<- core.AttackStats) error {
    // Implementation
}
```

### React/TypeScript Code

* Use TypeScript for type safety
* Follow React best practices
* Keep components modular and reusable
* Use proper prop typing

### Commit Messages

* Use clear, descriptive commit messages
* Start with a verb (Add, Fix, Update, Remove)
* Reference issue numbers when applicable

```bash theme={null}
# Good commit messages
git commit -m "Add UDP flood attack method"
git commit -m "Fix proxy rotation bug in HTTP bypass"
git commit -m "Update documentation for CLI usage"

# Less ideal
git commit -m "fixes"
git commit -m "updates"
```

## Pull Request Process

<Steps>
  <Step title="Create a Branch">
    Create a descriptive branch name:

    ```bash theme={null}
    git checkout -b feature/udp-flood
    git checkout -b fix/proxy-rotation
    ```
  </Step>

  <Step title="Make Your Changes">
    Implement your changes following the coding standards.
  </Step>

  <Step title="Test Thoroughly">
    * Build all components: `make all`
    * Test the CLI and server
    * Verify no regressions
  </Step>

  <Step title="Commit and Push">
    ```bash theme={null}
    git add .
    git commit -m "Add UDP flood attack method"
    git push origin feature/udp-flood
    ```
  </Step>

  <Step title="Open Pull Request">
    * Provide a clear description of changes
    * Reference related issues
    * Explain the motivation and approach
    * Include screenshots for UI changes
  </Step>
</Steps>

## Testing

### Manual Testing

For attack methods:

1. Test with `--verbose` flag to see detailed logs
2. Verify proxy rotation works correctly
3. Test with and without proxies (`--no-proxy`)
4. Ensure graceful error handling

```bash theme={null}
# Test your new attack
./bin/mmb-cli attack your_method http://example.com --verbose --threads 4
```

### Testing Multi-client Support

For server changes:

1. Open multiple browser tabs
2. Start different attacks simultaneously
3. Verify each client has isolated state
4. Check real-time stats update correctly

## Prerequisites

Make sure you have these installed:

<CardGroup cols={3}>
  <Card title="Go" icon="golang">
    v1.21 or above
  </Card>

  <Card title="Node.js" icon="node">
    v18 or above
  </Card>

  <Card title="npm" icon="npm">
    Node Package Manager
  </Card>
</CardGroup>

## Getting Help

If you have questions or need help:

* Open an issue for bugs or feature requests
* Check existing issues and discussions
* Review the documentation thoroughly

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

***

Happy hacking! We look forward to your contributions!