# perplexityai/bumblebee architecture

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

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

## Overview

1. Bumblebee is a single-purpose Go CLI that runs as a static binary on macOS and Linux. Its architecture is intentionally read-only: it inspects local metadata files, never invokes package managers, and never reads source code or performs network lookups during a scan.

2. The executable entrypoint lives under `cmd/bumblebee`. It exposes a small command surface: `scan` for inventory collection, `roots` for previewing resolved scan roots, `version` for build provenance, and `selftest` for an embedded end-to-end smoke test.

3. The scan model is one-shot. Bumblebee performs a single filesystem pass and exits; scheduling is external. Scan behavior is shaped by profile (`baseline`, `project`, `deep`) plus optional flags such as `--root`, `--ecosystem`, `--exposure-catalog`, and `--findings-only`.

4. Root resolution is a distinct boundary. `roots.go` and `internal/walk` determine which directories are eligible based on profile and root kind. `baseline` and `project` use curated global/user/project locations; `deep` is the only mode allowed to walk arbitrary explicit roots, including broad roots like `$HOME`.

5. Filesystem traversal is centralized in `internal/walk`. This layer is responsible for enumerating candidate metadata files and directory keys, while keeping the scanner focused on interpretation rather than discovery. The read surface is limited to inventory sources listed in the docs: lockfiles, installed package metadata, extension manifests, and supported MCP JSON configs.

6. Ecosystem-specific parsing is isolated in `internal/ecosystem/*`. Each subpackage handles one family of metadata and maps it into the shared model: npm/pnpm/Yarn/Bun, PyPI, Go modules, RubyGems, Composer, MCP configs, editor extensions, and browser extensions. This separation is the main parsing boundary in the repo.

7. Normalization and shared data modeling live in `internal/model` and `internal/normalize`. These packages canonicalize package names, versions, ecosystems, source types, and confidence levels so that records are comparable across scans. Stable `record_id` values are content-addressed from canonical identity fields, which is important for deduplication and current-state tracking downstream.

8. Endpoint identity is captured separately in `internal/endpoint`. Every emitted record carries host-level context such as hostname, OS, architecture, username, UID, and optional device ID. This makes records suitable for fleet correlation without needing an external device inventory service.

9. Exposure matching is an optional second pass in `internal/exposure`. When given one or more catalog files, Bumblebee performs exact `(ecosystem, package name, version)` matching against the scanned inventory and emits `finding` records with severity, catalog identifiers, and evidence. Catalog loading supports multiple JSON files in a directory, but only if they share the same supported schema version.

10. Output is split between normal records and diagnostics. `internal/output` and `sink.go` handle NDJSON emission, with package/finding/summary records going to the main output stream and diagnostics going to stderr. The run always ends with a `scan_summary` record so downstream receivers can decide whether to promote the run to current state.

11. The transport boundary is intentionally outside the scanner core. The docs describe file and HTTPS sinks plus a receiver-side current-state model, which means Bumblebee’s job is to produce structured NDJSON and not to manage persistence or fleet ingestion itself.

12. `selftest` is a built-in validation path, not a production scan mode. It runs against embedded fixtures under `cmd/bumblebee/selftest/fixtures`, uses fake package names, and verifies that the installed binary can still detect the expected metadata without touching the network.

13. The repository also contains versioned schemas and threat-intel inputs. `docs/schema/v0.1.0` defines the wire format for package, finding, exposure catalog, diagnostics, and summary records, while `threat_intel/` holds maintained catalog JSON files that can be fed into scans as prebuilt advisory inputs.

Main entry points: [`internal/walk/walk.go`](https://github.com/perplexityai/bumblebee/blob/main/internal/walk/walk.go) (Walk), [`internal/model/model.go`](https://github.com/perplexityai/bumblebee/blob/main/internal/model/model.go) (Model), [`internal/scanner/scanner.go`](https://github.com/perplexityai/bumblebee/blob/main/internal/scanner/scanner.go) (Scanner), [`cmd/bumblebee/main.go`](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/main.go) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cmd["CLI"]
  node_n_main["Main<br/>cli entrypoint<br/>[main.go]"]
  node_n_roots["Roots<br/>root resolver<br/>[roots.go]"]
  node_n_selftest["Selftest<br/>embedded smoke test<br/>[selftest.go]"]
  node_n_version["Version<br/>provenance command<br/>[version.go]"]
end

subgraph group_grp_scan["Scan core"]
  node_n_scanner["Scanner<br/>scan orchestrator<br/>[scanner.go]"]
  node_n_walk["Walk<br/>filesystem traversal<br/>[walk.go]"]
  node_n_dirkey["Dir keys<br/>path classification<br/>[dirkey_unix.go]"]
  node_n_model["Model<br/>record schema<br/>[model.go]"]
  node_n_normalize["Normalize<br/>canonicalization<br/>[normalize.go]"]
  node_n_endpoint["Endpoint<br/>host identity<br/>[endpoint.go]"]
  node_n_exposure["Exposure<br/>catalog matcher<br/>[exposure.go]"]
  node_n_npm["npm<br/>ecosystem parser<br/>[npm.go]"]
  node_n_pnpm["pnpm<br/>ecosystem parser<br/>[pnpm.go]"]
  node_n_yarn["Yarn<br/>ecosystem parser<br/>[yarn.go]"]
  node_n_bun["Bun<br/>ecosystem parser<br/>[bun.go]"]
  node_n_pypi["PyPI<br/>ecosystem parser<br/>[pypi.go]"]
  node_n_gomod["Go mod<br/>ecosystem parser<br/>[gomod.go]"]
  node_n_rubygems["RubyGems<br/>ecosystem parser<br/>[rubygems.go]"]
  node_n_composer["Composer<br/>ecosystem parser<br/>[composer.go]"]
  node_n_mcp["MCP<br/>ecosystem parser<br/>[mcp.go]"]
  node_n_editorext["Editor ext<br/>ecosystem parser<br/>[editorext.go]"]
  node_n_browserext["Browser ext<br/>ecosystem parser<br/>[browserext.go]"]
end

subgraph group_grp_output["Emission"]
  node_n_output["Output<br/>ndjson emitter<br/>[output.go]"]
  node_n_sink["Sink<br/>CLI output boundary<br/>[sink.go]"]
  node_n_httpsink["HTTP sink<br/>transport adapter<br/>[httpsink.go]"]
end

subgraph group_grp_docs["Schemas & intel"]
  node_n_schema["Schemas<br/>wire schema<br/>[v0.1.0]"]
  node_n_threat["Threat intel<br/>catalog data"]
end

node_n_main -->|"scan roots"| node_n_roots
node_n_main -->|"scan"| node_n_scanner
node_n_main -->|"selftest"| node_n_selftest
node_n_main -->|"version"| node_n_version
node_n_roots -->|"eligibility"| node_n_walk
node_n_scanner -->|"discover"| node_n_walk
node_n_scanner -->|"records"| node_n_model
node_n_scanner -->|"canonicalize"| node_n_normalize
node_n_scanner -->|"host context"| node_n_endpoint
node_n_scanner -->|"optional match"| node_n_exposure
node_n_walk -->|"dir keys"| node_n_dirkey
node_n_walk -->|"metadata"| node_n_npm
node_n_walk -->|"metadata"| node_n_pnpm
node_n_walk -->|"metadata"| node_n_yarn
node_n_walk -->|"metadata"| node_n_bun
node_n_walk -->|"metadata"| node_n_pypi
node_n_walk -->|"metadata"| node_n_gomod
node_n_walk -->|"metadata"| node_n_rubygems
node_n_walk -->|"metadata"| node_n_composer
node_n_walk -->|"metadata"| node_n_mcp
node_n_walk -->|"metadata"| node_n_editorext
node_n_walk -->|"metadata"| node_n_browserext
node_n_npm -->|"map"| node_n_model
node_n_pnpm -->|"map"| node_n_model
node_n_yarn -->|"map"| node_n_model
node_n_bun -->|"map"| node_n_model
node_n_pypi -->|"map"| node_n_model
node_n_gomod -->|"map"| node_n_model
node_n_rubygems -->|"map"| node_n_model
node_n_composer -->|"map"| node_n_model
node_n_mcp -->|"map"| node_n_model
node_n_editorext -->|"map"| node_n_model
node_n_browserext -->|"map"| node_n_model
node_n_normalize -->|"canonical ids"| node_n_model
node_n_exposure -->|"findings"| node_n_model
node_n_exposure -->|"catalogs"| node_n_threat
node_n_output -->|"emit"| node_n_sink
node_n_output -->|"format"| node_n_schema
node_n_sink -->|"transport"| node_n_httpsink
node_n_selftest -->|"fixtures"| node_n_schema

click node_n_main "https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/main.go"
click node_n_roots "https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/roots.go"
click node_n_selftest "https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/selftest.go"
click node_n_version "https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/version.go"
click node_n_scanner "https://github.com/perplexityai/bumblebee/blob/main/internal/scanner/scanner.go"
click node_n_walk "https://github.com/perplexityai/bumblebee/blob/main/internal/walk/walk.go"
click node_n_dirkey "https://github.com/perplexityai/bumblebee/blob/main/internal/walk/dirkey_unix.go"
click node_n_model "https://github.com/perplexityai/bumblebee/blob/main/internal/model/model.go"
click node_n_normalize "https://github.com/perplexityai/bumblebee/blob/main/internal/normalize/normalize.go"
click node_n_endpoint "https://github.com/perplexityai/bumblebee/blob/main/internal/endpoint/endpoint.go"
click node_n_exposure "https://github.com/perplexityai/bumblebee/blob/main/internal/exposure/exposure.go"
click node_n_npm "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/npm/npm.go"
click node_n_pnpm "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/pnpm/pnpm.go"
click node_n_yarn "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/yarn/yarn.go"
click node_n_bun "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/bun/bun.go"
click node_n_pypi "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/pypi/pypi.go"
click node_n_gomod "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/gomod/gomod.go"
click node_n_rubygems "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/rubygems/rubygems.go"
click node_n_composer "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/composer/composer.go"
click node_n_mcp "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/mcp/mcp.go"
click node_n_editorext "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/editorext/editorext.go"
click node_n_browserext "https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/browserext/browserext.go"
click node_n_output "https://github.com/perplexityai/bumblebee/blob/main/internal/output/output.go"
click node_n_sink "https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/sink.go"
click node_n_httpsink "https://github.com/perplexityai/bumblebee/blob/main/internal/output/httpsink.go"
click node_n_schema "https://github.com/perplexityai/bumblebee/blob/main/docs/schema/v0.1.0"
click node_n_threat "https://github.com/perplexityai/bumblebee/tree/main/threat_intel"

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_n_main,node_n_roots,node_n_selftest,node_n_version toneBlue
class node_n_scanner,node_n_walk,node_n_dirkey,node_n_model,node_n_normalize,node_n_endpoint,node_n_exposure,node_n_npm,node_n_pnpm,node_n_yarn,node_n_bun,node_n_pypi,node_n_gomod,node_n_rubygems,node_n_composer,node_n_mcp,node_n_editorext,node_n_browserext toneAmber
class node_n_output,node_n_sink,node_n_httpsink toneMint
class node_n_schema,node_n_threat toneRose
```

## Components

### CLI

Executable entrypoint and user-facing commands

- [Main](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/main.go): cli entrypoint · Bootstraps the command surface and dispatches subcommands · `cmd/bumblebee/main.go`
- [Roots](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/roots.go): root resolver · Resolves scan roots for preview and scan planning · `cmd/bumblebee/roots.go`
- [Selftest](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/selftest.go): embedded smoke test · Runs fixture-based end-to-end validation against the installed binary · `cmd/bumblebee/selftest.go`
- [Version](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/version.go): provenance command · Emits build and version provenance · `cmd/bumblebee/version.go`

### Scan core

Root resolution, traversal, parsing, normalization, and findings

- [Scanner](https://github.com/perplexityai/bumblebee/blob/main/internal/scanner/scanner.go): scan orchestrator · Coordinates one-shot inventory collection and optional exposure matching · `internal/scanner/scanner.go`
- [Walk](https://github.com/perplexityai/bumblebee/blob/main/internal/walk/walk.go): filesystem traversal · Enumerates eligible directories and candidate metadata files · `internal/walk/walk.go`
- [Dir keys](https://github.com/perplexityai/bumblebee/blob/main/internal/walk/dirkey_unix.go): path classification · Platform-specific directory key logic used during traversal · `internal/walk/dirkey_unix.go`
- [Model](https://github.com/perplexityai/bumblebee/blob/main/internal/model/model.go): record schema · Defines shared package, finding, summary, and record structures · `internal/model/model.go`
- [Normalize](https://github.com/perplexityai/bumblebee/blob/main/internal/normalize/normalize.go): canonicalization · Canonicalizes names, versions, ecosystems, and confidence levels · `internal/normalize/normalize.go`
- [Endpoint](https://github.com/perplexityai/bumblebee/blob/main/internal/endpoint/endpoint.go): host identity · Captures host-level context attached to every emitted record · `internal/endpoint/endpoint.go`
- [Exposure](https://github.com/perplexityai/bumblebee/blob/main/internal/exposure/exposure.go): catalog matcher · Matches scanned inventory against advisory catalogs to produce findings · `internal/exposure/exposure.go`
- [npm](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/npm/npm.go): ecosystem parser · Parses npm and related JavaScript package metadata · `internal/ecosystem/npm/npm.go`
- [pnpm](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/pnpm/pnpm.go): ecosystem parser · Parses pnpm lock and package metadata · `internal/ecosystem/pnpm/pnpm.go`
- [Yarn](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/yarn/yarn.go): ecosystem parser · Parses Yarn lock and package metadata · `internal/ecosystem/yarn/yarn.go`
- [Bun](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/bun/bun.go): ecosystem parser · Parses Bun package metadata · `internal/ecosystem/bun/bun.go`
- [PyPI](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/pypi/pypi.go): ecosystem parser · Parses installed Python package metadata · `internal/ecosystem/pypi/pypi.go`
- [Go mod](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/gomod/gomod.go): ecosystem parser · Parses Go module metadata · `internal/ecosystem/gomod/gomod.go`
- [RubyGems](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/rubygems/rubygems.go): ecosystem parser · Parses installed Ruby gem metadata · `internal/ecosystem/rubygems/rubygems.go`
- [Composer](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/composer/composer.go): ecosystem parser · Parses PHP Composer metadata · `internal/ecosystem/composer/composer.go`
- [MCP](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/mcp/mcp.go): ecosystem parser · Parses supported MCP JSON configs · `internal/ecosystem/mcp/mcp.go`
- [Editor ext](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/editorext/editorext.go): ecosystem parser · Parses editor extension manifests · `internal/ecosystem/editorext/editorext.go`
- [Browser ext](https://github.com/perplexityai/bumblebee/blob/main/internal/ecosystem/browserext/browserext.go): ecosystem parser · Parses browser extension manifests · `internal/ecosystem/browserext/browserext.go`

### Emission

Record shaping and output sinks

- [Output](https://github.com/perplexityai/bumblebee/blob/main/internal/output/output.go): ndjson emitter · Separates normal records from diagnostics and emits scan summaries · `internal/output/output.go`
- [Sink](https://github.com/perplexityai/bumblebee/blob/main/cmd/bumblebee/sink.go): CLI output boundary · Wires stdout and stderr emission for records and diagnostics · `cmd/bumblebee/sink.go`
- [HTTP sink](https://github.com/perplexityai/bumblebee/blob/main/internal/output/httpsink.go): transport adapter · Client-side transport helper for sending structured output · `internal/output/httpsink.go`

### Schemas & intel

Wire schemas and maintained threat-intel inputs

- [Schemas](https://github.com/perplexityai/bumblebee/blob/main/docs/schema/v0.1.0): wire schema · Versioned JSON schemas for package, finding, exposure catalog, diagnostic, and summary records · `docs/schema/v0.1.0`
- [Threat intel](https://github.com/perplexityai/bumblebee/tree/main/threat_intel): catalog data · Maintained advisory catalog JSON inputs usable during scans · `threat_intel`

## Connections

- Main → Roots: scan roots · CLI delegates root preview and root selection to the resolver
- Main → Scanner: scan · CLI dispatches the one-shot scan pipeline
- Main → Selftest: selftest · CLI exposes the embedded validation path
- Main → Version: version · CLI exposes build provenance
- Roots → Walk: eligibility · Root resolution feeds the traversal boundary
- Scanner → Walk: discover · Scanner asks walk to enumerate candidate metadata sources
- Scanner → Model: records · Scanner produces shared inventory and finding records
- Scanner → Normalize: canonicalize · Scanner normalizes identities before emission and matching
- Scanner → Endpoint: host context · Scanner attaches endpoint identity to emitted records
- Scanner → Exposure: optional match · Scanner performs a second-pass advisory match when catalogs are provided
- Walk → Dir keys: dir keys · Traversal uses platform-specific directory key logic
- Walk → npm: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → pnpm: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Yarn: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Bun: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → PyPI: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Go mod: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → RubyGems: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Composer: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → MCP: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Editor ext: metadata · Traversal surfaces metadata for ecosystem parsers
- Walk → Browser ext: metadata · Traversal surfaces metadata for ecosystem parsers
- npm → Model: map · Parser maps ecosystem-specific metadata into shared records
- pnpm → Model: map · Parser maps ecosystem-specific metadata into shared records
- Yarn → Model: map · Parser maps ecosystem-specific metadata into shared records
- Bun → Model: map · Parser maps ecosystem-specific metadata into shared records
- PyPI → Model: map · Parser maps ecosystem-specific metadata into shared records
- Go mod → Model: map · Parser maps ecosystem-specific metadata into shared records
- RubyGems → Model: map · Parser maps ecosystem-specific metadata into shared records
- Composer → Model: map · Parser maps ecosystem-specific metadata into shared records
- MCP → Model: map · Parser maps ecosystem-specific metadata into shared records
- Editor ext → Model: map · Parser maps ecosystem-specific metadata into shared records
- Browser ext → Model: map · Parser maps ecosystem-specific metadata into shared records
- Normalize → Model: canonical ids · Normalization supports content-addressed record identity and deduplication
- Exposure → Model: findings · Exposure matching consumes inventory records and emits findings
- Exposure → Threat intel: catalogs · Matcher consumes maintained threat-intel catalog JSON inputs
- Output → Sink: emit · Output layer routes records and diagnostics to the CLI sink boundary
- Output → Schemas: format · Emission follows the versioned wire schemas
- Sink → HTTP sink: transport · Sink boundary aligns with file and HTTPS transport adapters
- Selftest → Schemas: fixtures · Selftest validates output shape against the embedded schema expectations
