# yanzyuyu/beam architecture

> Architecture diagram of the GitHub repository yanzyuyu/beam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yanzyuyu/beam
- Repository: https://github.com/yanzyuyu/beam

## Overview

Beam is a local-network portal for sharing files and clipboard text between devices through a browser. The workflow starts with the CLI discovering a LAN address, choosing storage and a port, then starting an HTTP server and presenting a QR code; peers use the portal to upload, browse, download, and delete files, organize folders, and exchange text. Server-Sent Events announce updates to connected clients. The README also describes browser-based tools and embedded web assets. Those UI capabilities are represented at the shared web source path; the excerpt is partial, so detailed UI-to-route wiring is omitted.

Main entry points: [`pkg/server/server.go`](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go) (HTTP server), [`cmd/beam/main.go`](https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go) (CLI launcher), [`pkg/store/store.go`](https://github.com/yanzyuyu/beam/blob/main/pkg/store/store.go) (Sharing state), [`pkg/web/web.go`](https://github.com/yanzyuyu/beam/blob/main/pkg/web/web.go) (Browser interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and Discovery"]
  node_cli["CLI launcher<br/>[main.go]"]
  node_lan["LAN discovery<br/>[netutil.go]"]
  node_port["Port selection<br/>[netutil.go]"]
  node_browser["Browser opening<br/>[main.go]"]
end

subgraph group_portal["Web Portal"]
  node_webserver["HTTP server<br/>[server.go]"]
  node_webui["Browser interface<br/>[web.go]"]
  node_qr["QR presentation<br/>[main.go]"]
  node_qrroute["QR endpoint<br/>[server.go]"]
end

subgraph group_sharing["Sharing Services"]
  node_fileapi["File transfer API<br/>[server.go]"]
  node_folderapi["Folder API<br/>[server.go]"]
  node_textapi["Clipboard API<br/>[server.go]"]
  node_events["Live event stream<br/>[server.go]"]
  node_browsertools["Browser tools<br/>[web.go]"]
end

subgraph group_state["Local State"]
  node_store[("Sharing state<br/>[store.go]")]
  node_disk[("Local files")]
end

node_owner(("Beam operator"))
node_peer(("Peer devices"))
node_network(("Local Wi-Fi"))

node_owner -->|"starts"| node_cli
node_cli -->|"detects address"| node_lan
node_cli -->|"selects port"| node_port
node_cli -->|"opens storage"| node_store
node_cli -->|"configures"| node_webserver
node_cli -->|"prints portal QR"| node_qr
node_cli -->|"opens portal"| node_browser
node_browser -->|"opens"| node_webui
node_qr -->|"encodes portal address"| node_peer
node_qrroute -->|"serves QR image"| node_peer
node_peer -->|"connects over"| node_network
node_network -->|"carries HTTP"| node_webserver
node_webserver -->|"serves interface"| node_webui
node_webserver -->|"dispatches routes"| node_fileapi
node_webserver -->|"dispatches routes"| node_folderapi
node_webserver -->|"dispatches routes"| node_textapi
node_webserver -->|"dispatches route"| node_qrroute
node_peer -->|"uploads and requests"| node_fileapi
node_peer -->|"manages folders"| node_folderapi
node_peer -->|"shares text"| node_textapi
node_fileapi -->|"reads and writes files"| node_store
node_folderapi -->|"manages folders"| node_store
node_textapi -->|"reads and writes text"| node_store
node_webserver -->|"dispatches stream"| node_events
node_events -->|"subscribes to updates"| node_store
node_store -->|"signals changes"| node_events
node_events -->|"streams updates"| node_peer
node_store -->|"persists manifest and files"| node_disk
node_browsertools -->|"provides browser tools"| node_peer

click node_cli "https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go"
click node_lan "https://github.com/yanzyuyu/beam/blob/main/pkg/netutil/netutil.go"
click node_port "https://github.com/yanzyuyu/beam/blob/main/pkg/netutil/netutil.go"
click node_browser "https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go"
click node_webserver "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_webui "https://github.com/yanzyuyu/beam/blob/main/pkg/web/web.go"
click node_qr "https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go"
click node_qrroute "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_fileapi "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_folderapi "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_textapi "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_events "https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go"
click node_browsertools "https://github.com/yanzyuyu/beam/blob/main/pkg/web/web.go"
click node_store "https://github.com/yanzyuyu/beam/blob/main/pkg/store/store.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lan,node_port,node_browser toneBlue
class node_webserver,node_webui,node_qr,node_qrroute toneAmber
class node_fileapi,node_folderapi,node_textapi,node_events,node_browsertools toneMint
class node_store,node_disk toneRose
class node_owner,node_peer,node_network toneIndigo
```

## Components

### Startup and Discovery

- [CLI launcher](https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go): `cmd/beam/main.go`
- [LAN discovery](https://github.com/yanzyuyu/beam/blob/main/pkg/netutil/netutil.go): `pkg/netutil/netutil.go`
- [Port selection](https://github.com/yanzyuyu/beam/blob/main/pkg/netutil/netutil.go): `pkg/netutil/netutil.go`
- [Browser opening](https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go): `cmd/beam/main.go`

### Web Portal

- [HTTP server](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Browser interface](https://github.com/yanzyuyu/beam/blob/main/pkg/web/web.go): `pkg/web/web.go`
- [QR presentation](https://github.com/yanzyuyu/beam/blob/main/cmd/beam/main.go): `cmd/beam/main.go`
- [QR endpoint](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`

### Sharing Services

- [File transfer API](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Folder API](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Clipboard API](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Live event stream](https://github.com/yanzyuyu/beam/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Browser tools](https://github.com/yanzyuyu/beam/blob/main/pkg/web/web.go): `pkg/web/web.go`

### Local State

- [Sharing state](https://github.com/yanzyuyu/beam/blob/main/pkg/store/store.go): `pkg/store/store.go`
- **Local files**

### Other components

- **Beam operator**
- **Peer devices**
- **Local Wi-Fi**

## Connections

- Beam operator → CLI launcher: starts
- CLI launcher → LAN discovery: detects address
- CLI launcher → Port selection: selects port
- CLI launcher → Sharing state: opens storage
- CLI launcher → HTTP server: configures
- CLI launcher → QR presentation: prints portal QR
- CLI launcher → Browser opening: opens portal
- Browser opening → Browser interface: opens
- QR presentation → Peer devices: encodes portal address
- QR endpoint → Peer devices: serves QR image
- Peer devices → Local Wi-Fi: connects over
- Local Wi-Fi → HTTP server: carries HTTP
- HTTP server → Browser interface: serves interface
- HTTP server → File transfer API: dispatches routes
- HTTP server → Folder API: dispatches routes
- HTTP server → Clipboard API: dispatches routes
- HTTP server → QR endpoint: dispatches route
- Peer devices → File transfer API: uploads and requests
- Peer devices → Folder API: manages folders
- Peer devices → Clipboard API: shares text
- File transfer API → Sharing state: reads and writes files
- Folder API → Sharing state: manages folders
- Clipboard API → Sharing state: reads and writes text
- HTTP server → Live event stream: dispatches stream
- Live event stream → Sharing state: subscribes to updates
- Sharing state → Live event stream: signals changes
- Live event stream → Peer devices: streams updates
- Sharing state → Local files: persists manifest and files
- Browser tools → Peer devices: provides browser tools