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

# Project Structure

> Understanding the Miku Miku Beam codebase organization

## Overview

Miku Miku Beam is organized into four main components that work together to provide both CLI and web-based stress testing capabilities.

## Directory Layout

```
mikumikubeam/
├── cmd/                    # Main applications
│   ├── mmb-cli/           # CLI application
│   └── mmb-server/        # Web server application
├── internal/              # Core engine and implementations
│   ├── attacks/          # Attack method implementations
│   ├── config/           # Configuration management
│   ├── engine/           # Attack coordination engine
│   ├── netutil/          # Network utilities
│   └── proxy/            # Proxy loading and management
├── pkg/                   # Shared packages
│   ├── api/              # API types and interfaces
│   └── target/           # Target parsing utilities
├── web-client/           # React-based frontend
│   ├── public/          # Static assets
│   └── src/             # React source code
├── data/                # Runtime data (not in repo)
│   ├── proxies.txt     # Proxy list
│   └── uas.txt         # User agent list
├── bin/                 # Compiled binaries (generated)
├── docs/               # Documentation assets
├── go.mod              # Go dependencies
├── go.sum              # Go dependency checksums
├── Makefile           # Build automation
└── README.md          # Project documentation
```

## Component Breakdown

### CLI (`cmd/mmb-cli/`)

The command-line interface for running attacks directly from the terminal.

<CodeGroup>
  ```go main.go theme={null}
  // Entry point for CLI application
  package main

  // Provides:
  // - Command parsing and validation
  // - Real-time colored output
  // - Attack statistics display
  // - Verbose logging support
  ```
</CodeGroup>

**Key Features:**

* Colored terminal output with real-time statistics
* `--verbose` flag for detailed attack logs
* `--no-proxy` flag to run without proxies
* `--threads` flag to control concurrency
* `--duration`, `--delay`, `--packet-size` for attack configuration

**Example Usage:**

```bash theme={null}
./bin/mmb-cli attack http_flood http://example.com --verbose --threads 8
```

### Server (`cmd/mmb-server/`)

Web server with Socket.IO support for the browser-based interface.

<CodeGroup>
  ```go main.go theme={null}
  // Entry point for web server
  package main

  // Provides:
  // - REST API endpoints
  // - Socket.IO real-time communication
  // - Static file serving
  // - Multi-client attack management
  ```
</CodeGroup>

**Key Features:**

* REST API endpoints (`/attacks`, `/configuration`)
* Real-time WebSocket communication via Socket.IO
* Serves static web client files
* Per-client attack instance management
* Runs on `http://localhost:3000` by default

**API Endpoints:**

* `POST /api/attacks` - Start an attack
* `DELETE /api/attacks` - Stop an attack
* `GET /api/configuration` - Get configuration
* WebSocket events for real-time stats

### Core Engine (`internal/`)

The heart of the application containing attack implementations and coordination logic.

#### Engine (`internal/engine/`)

Attack coordination and management system.

<Accordion title="engine.go (255 lines)">
  Core engine implementation:

  * `Engine` struct - Manages multiple concurrent attacks
  * `AttackInstance` - Represents a single running attack
  * `Start()` - Launches attacks with multiple threads
  * `Stop()` - Cancels specific attacks
  * `StopAll()` - Terminates all running attacks
  * Multi-threaded worker dispatch
  * Real-time statistics aggregation
</Accordion>

<Accordion title="registry.go (28 lines)">
  Attack worker registry:

  * `Registry` struct - Maps attack kinds to workers
  * `Register()` - Adds new attack methods
  * `Get()` - Retrieves worker by attack kind
  * `ListKinds()` - Returns all registered attacks
</Accordion>

<Accordion title="logging.go">
  Logging utilities:

  * `SendAttackLogIfVerbose()` - Conditional log sending
  * Prevents channel blocking
  * Formats attack statistics
</Accordion>

**Key Types:**

```go theme={null}
type AttackKind string

const (
    AttackHTTPFlood     AttackKind = "http_flood"
    AttackHTTPBypass    AttackKind = "http_bypass"
    AttackHTTPSlowloris AttackKind = "http_slowloris"
    AttackTCPFlood      AttackKind = "tcp_flood"
    AttackMinecraftPing AttackKind = "minecraft_ping"
)

type AttackParams struct {
    Target      string
    TargetNode  targetpkg.Node
    Duration    time.Duration
    PacketDelay time.Duration
    PacketSize  int
    Method      AttackKind
    Threads     int
    Verbose     bool
}

type AttackWorker interface {
    Fire(ctx context.Context, params AttackParams, proxy Proxy, 
         userAgent string, logCh chan<- AttackStats) error
}
```

#### Attacks (`internal/attacks/`)

Individual attack method implementations organized by protocol.

<AccordionGroup>
  <Accordion title="HTTP Attacks (internal/attacks/http/)">
    **flood.go** - HTTP Flood Attack

    * Sends random GET/POST requests
    * Configurable payload sizes
    * Random method selection based on packet size
    * User agent rotation

    **bypass.go** - HTTP Bypass Attack

    * Mimics real browser behavior
    * Handles redirects automatically
    * Manages cookies and sessions
    * Realistic headers and resources

    **slowloris.go** - HTTP Slowloris Attack

    * Sends slow HTTP requests
    * Keeps connections open
    * Exhausts server resources
    * Partial header sending
  </Accordion>

  <Accordion title="TCP Attacks (internal/attacks/tcp/)">
    **flood.go** - TCP Flood Attack

    * Raw TCP packet flooding
    * Random payload generation
    * Direct connection establishment
    * Proxy support via `netutil.DialTCP()`
  </Accordion>

  <Accordion title="Game Attacks (internal/attacks/game/)">
    **minecraft\_ping.go** - Minecraft Server Ping

    * Minecraft protocol implementation
    * Server status requests
    * MOTD (Message of the Day) queries
    * Player count polling
  </Accordion>
</AccordionGroup>

**Attack Implementation Pattern:**

All attacks follow this structure:

```go theme={null}
package attacktype

import (
    "context"
    core "github.com/sammwyy/mikumikubeam/internal/engine"
)

type workerName struct{}

func NewWorkerName() *workerName { 
    return &workerName{} 
}

func (w *workerName) Fire(ctx context.Context, params core.AttackParams,
    p core.Proxy, ua string, logCh chan<- core.AttackStats) error {
    // Implementation
    return nil
}
```

#### Configuration (`internal/config/`)

Configuration management for runtime settings.

<Accordion title="config.go">
  * Server port configuration
  * Data file paths (proxies, user agents)
  * Default attack parameters
  * Environment variable support
</Accordion>

#### Network Utilities (`internal/netutil/`)

Network helpers with proxy support.

<Accordion title="httpdial.go">
  HTTP client creation with proxy support:

  * `DialedHTTPClient()` - Creates HTTP client with proxy
  * Custom transport configuration
  * Timeout and retry logic
  * TLS configuration
</Accordion>

<Accordion title="tcpdial.go">
  TCP connection helpers:

  * `DialTCP()` - Establishes TCP connection via proxy
  * SOCKS5 proxy support
  * HTTP CONNECT tunneling
  * Connection timeout handling
</Accordion>

#### Proxy Management (`internal/proxy/`)

Proxy loading and filtering system.

<Accordion title="loader.go">
  * Loads proxies from `data/proxies.txt`
  * Parses proxy formats:
    * `protocol://user:pass@host:port`
    * `protocol://host:port`
    * `host:port` (defaults to http)
    * `host` (defaults to port 8080)
  * Validates proxy configurations
  * Filters out invalid entries
</Accordion>

### Shared Packages (`pkg/`)

Reusable packages that can be imported by external projects.

#### API Types (`pkg/api/`)

<Accordion title="types.go">
  Shared API types and interfaces:

  * Request/response structures
  * Attack configuration types
  * Statistics data models
  * Error definitions
</Accordion>

#### Target Utilities (`pkg/target/`)

<Accordion title="node.go">
  Target parsing and validation:

  * `Node` struct - Represents parsed target
  * `ParseTarget()` - Parses URLs and addresses
  * `ToURL()` - Converts back to URL format
  * Protocol/host/port extraction
</Accordion>

### Web Client (`web-client/`)

React-based frontend with Miku theme and real-time updates.

```
web-client/
├── public/              # Static assets
│   ├── index.html      # HTML template
│   ├── music/          # Background music
│   └── images/         # Miku-themed graphics
├── src/                # React source
│   ├── lib/           # Utilities and helpers
│   ├── components/    # React components
│   ├── App.tsx       # Main application
│   └── main.tsx      # Entry point
├── package.json       # Node dependencies
├── tsconfig.json     # TypeScript config
└── vite.config.ts    # Vite build config
```

**Key Features:**

* Modern UI with Miku theme
* Real-time attack visualization
* Socket.IO integration for live updates
* Attack configuration interface
* Proxy/UA editor built-in
* Multi-attack support (multiple tabs)

**Build Output:**

* Built files go to `bin/web-client/`
* Server serves from this location
* Production builds are optimized and minified

## Build System

The `Makefile` provides convenient build commands:

```makefile theme={null}
make prepare      # Install all dependencies
make all          # Build everything
make webclient    # Build React frontend only
make cli          # Build CLI binary only  
make server       # Build server binary only
make run-cli      # Run CLI with args
make run-server   # Run web server
make clean        # Clean build artifacts
```

### Build Flow

<Steps>
  <Step title="Install Dependencies">
    ```bash theme={null}
    make prepare
    ```

    Runs `go mod tidy` and `npm install`
  </Step>

  <Step title="Build Web Client">
    ```bash theme={null}
    make webclient
    ```

    * Installs npm dependencies
    * Runs `npm run build` (Vite)
    * Copies to `bin/web-client/`
  </Step>

  <Step title="Build Binaries">
    ```bash theme={null}
    make cli server
    ```

    * Compiles Go code
    * Outputs to `bin/mmb-cli` and `bin/mmb-server`
  </Step>
</Steps>

## Data Files

Runtime data stored in the `data/` directory:

### Proxies (`data/proxies.txt`)

One proxy per line in various formats:

```text theme={null}
http://proxy1.example.com:8080
socks5://user:pass@proxy2.example.com:1080
proxy3.example.com:3128
proxy4.example.com
```

### User Agents (`data/uas.txt`)

One user agent string per line:

```text theme={null}
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36
```

<Note>
  These files can be edited through the web interface or manually.
</Note>

## Workflow Diagrams

### Attack Execution Flow

```mermaid theme={null}
graph TD
    A[User/CLI Request] --> B[Engine.Start]
    B --> C[Create AttackInstance]
    C --> D[Spawn Worker Threads]
    D --> E[Worker Loop]
    E --> F[Select Random Proxy/UA]
    F --> G[AttackWorker.Fire]
    G --> H[Send Stats]
    H --> I{Duration Ended?}
    I -->|No| E
    I -->|Yes| J[Stop Attack]
```

### Multi-Client Architecture

```mermaid theme={null}
graph LR
    A[Browser Client 1] --> D[Server]
    B[Browser Client 2] --> D
    C[Browser Client 3] --> D
    D --> E[Engine]
    E --> F[Attack Instance 1]
    E --> G[Attack Instance 2]
    E --> H[Attack Instance 3]
```

Each client maintains its own isolated attack instance.

## Development Tips

### Adding New Features

<CardGroup cols={2}>
  <Card title="New Attack Method" icon="plus">
    1. Create worker in `internal/attacks/`
    2. Register in `cmd/mmb-cli/` and `cmd/mmb-server/`
    3. Add to web client dropdown
  </Card>

  <Card title="New Protocol Support" icon="network-wired">
    1. Create package in `internal/attacks/protocol/`
    2. Implement `AttackWorker` interface
    3. Add network helpers to `internal/netutil/` if needed
  </Card>

  <Card title="Engine Enhancement" icon="gear">
    Modify `internal/engine/engine.go`

    * Update `AttackParams` struct
    * Add new stats fields
    * Enhance worker dispatch logic
  </Card>

  <Card title="UI Changes" icon="palette">
    Edit files in `web-client/src/`

    * Update components
    * Rebuild with `make webclient`
    * Server automatically serves new build
  </Card>
</CardGroup>

### Common File Locations

<AccordionGroup>
  <Accordion title="Where do I add a new attack type?">
    1. Create file in `internal/attacks/[protocol]/[name].go`
    2. Add constant to `internal/engine/engine.go`
    3. Register in both `cmd/mmb-cli/main.go` and `cmd/mmb-server/main.go`
  </Accordion>

  <Accordion title="Where are attack parameters defined?">
    `internal/engine/engine.go` - See `AttackParams` struct
  </Accordion>

  <Accordion title="Where is the proxy logic?">
    * Loading: `internal/proxy/loader.go`
    * HTTP usage: `internal/netutil/httpdial.go`
    * TCP usage: `internal/netutil/tcpdial.go`
  </Accordion>

  <Accordion title="Where are API endpoints defined?">
    `cmd/mmb-server/main.go` - HTTP handlers and Socket.IO events
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Add Attack Methods" icon="wand-magic-sparkles" href="/development/adding-attacks">
    Learn how to implement custom attack methods
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/development/contributing">
    Submit your enhancements to the project
  </Card>
</CardGroup>