# radioactivetobi/bumblebee-hive architecture

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

- Interactive diagram: https://gitdiagram.com/radioactivetobi/bumblebee-hive
- Repository: https://github.com/radioactivetobi/bumblebee-hive

## Overview

Bumblebee is a read-only endpoint inventory and exposure scanner; Hive adds fleet ingestion, persistence, query APIs, and a dashboard. The principal workflow scans endpoint metadata, optionally matches an exposure catalog, emits records to Hive, and presents fleet inventory and findings. Scanner orchestration and Hive wiring are sampled; individual ecosystem parsers and some UI/API implementation details are represented at their supported tree paths, with uncertain links omitted.

Main entry points: [`internal/scanner/scanner.go`](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/scanner/scanner.go) (Scan orchestrator), [`cmd/bumblebee/main.go`](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/main.go) (Scanner CLI), [`cmd/hive/main.go`](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/hive/main.go) (Hive HTTP server), [`internal/ingest/handler.go`](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/ingest/handler.go) (NDJSON ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Endpoint scanning"]
  node_scanner_cli["Scanner CLI<br/>[main.go]"]
  node_root_resolution["Root resolution<br/>[roots.go]"]
  node_walker["Filesystem walker<br/>[walk.go]"]
  node_orchestrator["Scan orchestrator<br/>[scanner.go]"]
  node_ecosystem_parsers["Ecosystem parsers"]
  node_normalizer["Record normalization<br/>[normalize.go]"]
  node_record_sink["Record output<br/>[sink.go]"]
  node_http_output["HTTP output<br/>[httpsink.go]"]
end

subgraph group_hive["Hive services"]
  node_hive_server["Hive HTTP server<br/>[main.go]"]
  node_ingest_handler["NDJSON ingest<br/>[handler.go]"]
  node_ingest_auth["Ingest authentication<br/>[auth.go]"]
  node_sqlite_store[("SQLite inventory store<br/>[sqlite.go]")]
  node_read_api["REST read API<br/>[api.go]"]
end

subgraph group_dashboard["Fleet dashboard"]
  node_dashboard_app["Dashboard routes<br/>[App.tsx]"]
  node_dashboard_pages["Fleet views"]
  node_dashboard_client["API client<br/>[api.ts]"]
  node_demo_mode["Offline demo<br/>[Demo.tsx]"]
end

subgraph group_catalog["Exposure catalogs"]
  node_exposure_matcher["Exposure matching<br/>[exposure.go]"]
  node_osv_tool["OSV catalog builder<br/>[main.go]"]
  node_osv_records["OSV record mapping<br/>[osv.go]"]
end

node_endpoint(("Developer endpoint"))
node_dashboard_user(("Security/platform user"))

node_endpoint -->|"runs scan"| node_scanner_cli
node_scanner_cli -->|"resolves roots"| node_root_resolution
node_scanner_cli -->|"starts scan"| node_orchestrator
node_root_resolution -->|"provides roots"| node_orchestrator
node_orchestrator -->|"walks roots"| node_walker
node_orchestrator -->|"dispatches files"| node_ecosystem_parsers
node_orchestrator -->|"normalizes records"| node_normalizer
node_orchestrator -->|"matches packages"| node_exposure_matcher
node_scanner_cli -->|"emits records"| node_record_sink
node_record_sink -->|"sends batches"| node_http_output
node_http_output -->|"POSTs NDJSON"| node_hive_server
node_hive_server -->|"routes ingest"| node_ingest_handler
node_ingest_handler -->|"verifies request"| node_ingest_auth
node_ingest_handler -->|"ingests and promotes"| node_sqlite_store
node_hive_server -->|"routes API"| node_read_api
node_read_api -->|"queries inventory"| node_sqlite_store
node_dashboard_user -->|"uses dashboard"| node_dashboard_app
node_dashboard_app -->|"renders routes"| node_dashboard_pages
node_dashboard_pages -->|"requests data"| node_dashboard_client
node_dashboard_client -->|"calls endpoints"| node_read_api
node_dashboard_user -->|"loads local file"| node_demo_mode
node_osv_tool -->|"builds catalog"| node_osv_records
node_scanner_cli -->|"loads catalog"| node_exposure_matcher

click node_scanner_cli "https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/main.go"
click node_root_resolution "https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/roots.go"
click node_walker "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/walk/walk.go"
click node_orchestrator "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/scanner/scanner.go"
click node_ecosystem_parsers "https://github.com/radioactivetobi/bumblebee-hive/tree/main/internal/ecosystem"
click node_normalizer "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/normalize/normalize.go"
click node_exposure_matcher "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/exposure/exposure.go"
click node_record_sink "https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/sink.go"
click node_http_output "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/output/httpsink.go"
click node_hive_server "https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/hive/main.go"
click node_ingest_handler "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/ingest/handler.go"
click node_ingest_auth "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/ingest/auth.go"
click node_sqlite_store "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/store/sqlite/sqlite.go"
click node_read_api "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/api/api.go"
click node_dashboard_app "https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/App.tsx"
click node_dashboard_pages "https://github.com/radioactivetobi/bumblebee-hive/tree/main/web/src/pages"
click node_dashboard_client "https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/api.ts"
click node_demo_mode "https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/pages/Demo.tsx"
click node_osv_tool "https://github.com/radioactivetobi/bumblebee-hive/blob/main/tools/osvcatalog/main.go"
click node_osv_records "https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/osv/osv.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_scanner_cli,node_root_resolution,node_walker,node_orchestrator,node_ecosystem_parsers,node_normalizer,node_record_sink,node_http_output,node_dashboard_user toneBlue
class node_hive_server,node_ingest_handler,node_ingest_auth,node_sqlite_store,node_read_api toneAmber
class node_dashboard_app,node_dashboard_pages,node_dashboard_client,node_demo_mode toneMint
class node_exposure_matcher,node_osv_tool,node_osv_records toneRose
class node_endpoint toneIndigo
```

## Components

### Endpoint scanning

- [Scanner CLI](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/main.go): `cmd/bumblebee/main.go`
- [Root resolution](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/roots.go): `cmd/bumblebee/roots.go`
- [Filesystem walker](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/walk/walk.go): `internal/walk/walk.go`
- [Scan orchestrator](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/scanner/scanner.go): `internal/scanner/scanner.go`
- [Ecosystem parsers](https://github.com/radioactivetobi/bumblebee-hive/tree/main/internal/ecosystem): `internal/ecosystem`
- [Record normalization](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/normalize/normalize.go): `internal/normalize/normalize.go`
- [Record output](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/bumblebee/sink.go): `cmd/bumblebee/sink.go`
- [HTTP output](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/output/httpsink.go): `internal/output/httpsink.go`

### Hive services

- [Hive HTTP server](https://github.com/radioactivetobi/bumblebee-hive/blob/main/cmd/hive/main.go): `cmd/hive/main.go`
- [NDJSON ingest](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/ingest/handler.go): `internal/ingest/handler.go`
- [Ingest authentication](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/ingest/auth.go): `internal/ingest/auth.go`
- [SQLite inventory store](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/store/sqlite/sqlite.go): `internal/store/sqlite/sqlite.go`
- [REST read API](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/api/api.go): `internal/api/api.go`

### Fleet dashboard

- [Dashboard routes](https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Fleet views](https://github.com/radioactivetobi/bumblebee-hive/tree/main/web/src/pages): `web/src/pages`
- [API client](https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/api.ts): `web/src/api.ts`
- [Offline demo](https://github.com/radioactivetobi/bumblebee-hive/blob/main/web/src/pages/Demo.tsx): `web/src/pages/Demo.tsx`

### Exposure catalogs

- [Exposure matching](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/exposure/exposure.go): `internal/exposure/exposure.go`
- [OSV catalog builder](https://github.com/radioactivetobi/bumblebee-hive/blob/main/tools/osvcatalog/main.go): `tools/osvcatalog/main.go`
- [OSV record mapping](https://github.com/radioactivetobi/bumblebee-hive/blob/main/internal/osv/osv.go): `internal/osv/osv.go`

### Other components

- **Developer endpoint**
- **Security/platform user**

## Connections

- Developer endpoint → Scanner CLI: runs scan
- Scanner CLI → Root resolution: resolves roots
- Scanner CLI → Scan orchestrator: starts scan
- Root resolution → Scan orchestrator: provides roots
- Scan orchestrator → Filesystem walker: walks roots
- Scan orchestrator → Ecosystem parsers: dispatches files
- Scan orchestrator → Record normalization: normalizes records
- Scan orchestrator → Exposure matching: matches packages
- Scanner CLI → Record output: emits records
- Record output → HTTP output: sends batches
- HTTP output → Hive HTTP server: POSTs NDJSON
- Hive HTTP server → NDJSON ingest: routes ingest
- NDJSON ingest → Ingest authentication: verifies request
- NDJSON ingest → SQLite inventory store: ingests and promotes
- Hive HTTP server → REST read API: routes API
- REST read API → SQLite inventory store: queries inventory
- Security/platform user → Dashboard routes: uses dashboard
- Dashboard routes → Fleet views: renders routes
- Fleet views → API client: requests data
- API client → REST read API: calls endpoints
- Security/platform user → Offline demo: loads local file
- OSV catalog builder → OSV record mapping: builds catalog
- Scanner CLI → Exposure matching: loads catalog