# Architecture: hyper-p2p-bucket-rate-limit

**Category:** Measurement & rate control

```mermaid
flowchart LR
  App[Application] --> Mod[HyperP2PBucketRateLimit]
  Mod --> Mux[Protomux bucket-rate-limit/v1]
  Mux --> Swarm[Hyperswarm]
```

## Sequence (P2P)

```mermaid
sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
```

## Wire messages

| type | fields | direction | behavior |
|------|--------|-----------|----------|
| `bucket` | peerId, tokens, updatedAt | gossip | Handled in onmessage / gossipSend |
| `configure` | buckets, burst, rate, type | gossip | Handled in onmessage / gossipSend |
| `sync` | buckets, type | gossip | Handled in onmessage / gossipSend |

## State model

- In-memory `Map` / `Set` structures for hot path
- Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
- `close()` tears down swarm, timers, and clears ephemeral state

## Composition

Composes with: `hyper-p2p-congestion-signal`, `hyper-p2p-bandwidth-broker`.