# blackducksoftware/bdio architecture

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

- Interactive diagram: https://gitdiagram.com/blackducksoftware/bdio
- Repository: https://github.com/blackducksoftware/bdio

## Overview

#### Purpose and build
Black Duck I/O (BDIO) is a Java 8+ multi-module library and CLI for producing, consuming, validating, transforming, and storing JSON-LD BOM and scan graphs. The root Gradle build assembles its modules; the normative format is documented under `docs/spec/02.Model.txt` and `docs/spec/04.DocumentFormat.txt`.

#### Core JSON-LD model and streaming API
The `bdio2` module defines the primary public data model, document framing/context, and streaming read/write contracts. Applications construct model nodes, associate them with metadata/context, then serialize or consume document entries through reader/writer/emitter abstractions.
- `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java`
- `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java`
- `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioWriter.java`
- `bdio2/src/main/java/com/blackducksoftware/bdio2/model/`

#### Context, compatibility, and parsing boundary
`BdioContext` and bundled JSON-LD contexts define vocabulary/version interpretation. Emitters provide the ingestion boundary for native BDIO streams and legacy BDIO 1.x or scan-container inputs, isolating compatibility conversion from the current model.
- `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioContext.java`
- `bdio2/src/main/java/com/blackducksoftware/bdio2/EmitterFactory.java`
- `bdio2/src/main/java/com/blackducksoftware/bdio2/LegacyBdio1xEmitter.java`
- `bdio2/src/main/resources/com/blackducksoftware/bdio2/bdio-context-2.1.jsonld`

#### Reactive document implementations
Two adapter modules expose the core document/JSON-LD processing flow under alternative reactive runtimes. Consumers choose Reactor or RxJava rather than the base streaming interfaces; these are library integrations, not standalone services.
- `bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorBdioDocument.java`
- `bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorJsonLdProcessing.java`
- `bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaBdioDocument.java`
- `bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaJsonLdProcessing.java`

#### TinkerPop graph persistence and normalization
The graph layer maps BDIO JSON-LD documents to Apache TinkerPop graphs, with reader/writer and normalization stages behind a common `BlackDuckIo` API. Default implementations target in-memory TinkerGraph; SQLG implementations support PostgreSQL-backed graph storage, query optimization, and schema migration.
- `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java`
- `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/spi/DefaultBlackDuckIoReader.java`
- `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/SqlgBlackDuckIo.java`
- `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/flyway/SqlgFlywayExecutor.java`

#### Protobuf scan interchange
`bdio-protobuf` is a separate binary scan-data interchange path. Version-specific readers, writers, validators, and converters operate on typed header/node/chunk APIs, generated from protobuf schemas. Its boundary is distinct from the JSON-LD BDIO 2 graph model.
- `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/ProtobufBdioReader.java`
- `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioConverter.java`
- `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioV2Writer.java`
- `bdio-protobuf/src/main/proto/bdba_scan_nodes_v2.proto`

#### CLI entry point and operational flow
`bdio-tool` provides the executable entry point, `BdioMain`, dispatching file and graph operations such as concatenation, filtering, dependency/tree views, JSON-LD conversion, linting, SPDX output, and visualization. It consumes/produces BDIO through the core and graph boundaries rather than hosting a web application.
- `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java`
- `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractFileTool.java`
- `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractGraphTool.java`
- `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/LintTool.java`

#### Infrastructure and external dependencies
The material runtime is the JVM with Gradle builds. JSON-LD is the interchange representation; Reactor/RxJava are optional processing runtimes; Apache TinkerPop is the graph abstraction. SQLG, Flyway, JDBC, and PostgreSQL comprise the persistent graph path; `bdio-tinkerpop-db/Dockerfile` supplies the database image used by the documented build/test setup.

Main entry points: [`bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java`](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java) (BdioDocument), [`bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java`](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java) (Reader / Writer), [`bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java`](https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java) (BlackDuckIo), [`bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java`](https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java) (BdioMain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["BDIO 2 Core"]
  node_document["BdioDocument<br/>core document API<br/>[BdioDocument.java]"]
  node_model["BDIO model nodes<br/>public model"]
  node_context["BdioContext<br/>context resolver<br/>[BdioContext.java]"]
  node_jsonld_context["Bundled JSON-LD context<br/>JSON-LD resource"]
  node_streaming["Reader / Writer<br/>streaming API<br/>[BdioReader.java]"]
  node_emitters["EmitterFactory<br/>ingestion boundary"]
  node_legacy["Legacy BDIO 1.x emitter<br/>compatibility converter"]
end

subgraph group_reactive["Reactive Adapters"]
  node_reactor["Reactor document API<br/>Reactor adapter"]
  node_rxjava["RxJava document API<br/>RxJava adapter"]
end

subgraph group_graph["Graph Persistence"]
  node_blackduck_io["BlackDuckIo<br/>graph persistence API<br/>[BlackDuckIo.java]"]
  node_graph_reader["Default graph reader<br/>graph mapper"]
  node_sqlg[("SQLG graph backend<br/>persistent graph backend")]
  node_migration["SQLG Flyway migrations<br/>schema migration"]
end

subgraph group_protobuf["Protobuf Interchange"]
  node_protobuf_schema["Scan protobuf schema"]
  node_protobuf_converter["Protobuf converter<br/>binary interchange"]
  node_protobuf_reader["Protobuf reader<br/>binary reader"]
  node_protobuf_writer["Protobuf V2 writer<br/>binary writer"]
end

subgraph group_tooling["CLI"]
  node_cli{{"BdioMain<br/>CLI entry point<br/>[BdioMain.java]"}}
  node_file_tools["File tools<br/>CLI file operations"]
  node_graph_tools["Graph tools<br/>CLI graph operations"]
  node_lint["LintTool<br/>CLI validator<br/>[LintTool.java]"]
end

node_spec["BDIO format spec<br/>normative docs<br/>[02.Model.txt]"]

node_spec -.->|"specifies"| node_document
node_model -->|"framed by"| node_document
node_jsonld_context -->|"defines vocabulary"| node_context
node_context -->|"interprets"| node_document
node_document -->|"serialized as entries"| node_streaming
node_emitters -->|"emits input to"| node_streaming
node_legacy -->|"selected for legacy input"| node_emitters
node_reactor -->|"adapts"| node_document
node_rxjava -->|"adapts"| node_document
node_streaming -->|"maps documents through"| node_blackduck_io
node_blackduck_io -->|"default implementation"| node_graph_reader
node_blackduck_io -->|"persistent implementation"| node_sqlg
node_migration -->|"migrates schema for"| node_sqlg
node_protobuf_schema -->|"generates typed API for"| node_protobuf_converter
node_protobuf_reader -->|"feeds typed scan data"| node_protobuf_converter
node_protobuf_converter -->|"converts before output"| node_protobuf_writer
node_cli -->|"dispatches"| node_file_tools
node_cli -->|"dispatches"| node_graph_tools
node_cli -->|"dispatches"| node_lint
node_file_tools -->|"consumes and produces"| node_streaming
node_graph_tools -->|"uses"| node_blackduck_io
node_lint -->|"validates input through"| node_streaming

click node_spec "https://github.com/blackducksoftware/bdio/blob/master/docs/spec/02.Model.txt"
click node_document "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java"
click node_context "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioContext.java"
click node_jsonld_context "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/resources/com/blackducksoftware/bdio2/bdio-context-2.1.jsonld"
click node_streaming "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java"
click node_emitters "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/EmitterFactory.java"
click node_legacy "https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/LegacyBdio1xEmitter.java"
click node_reactor "https://github.com/blackducksoftware/bdio/blob/master/bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorBdioDocument.java"
click node_rxjava "https://github.com/blackducksoftware/bdio/blob/master/bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaBdioDocument.java"
click node_blackduck_io "https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java"
click node_graph_reader "https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/spi/DefaultBlackDuckIoReader.java"
click node_sqlg "https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/SqlgBlackDuckIo.java"
click node_migration "https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/flyway/SqlgFlywayExecutor.java"
click node_protobuf_schema "https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/proto/bdba_scan_nodes_v2.proto"
click node_protobuf_converter "https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioConverter.java"
click node_protobuf_reader "https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/ProtobufBdioReader.java"
click node_protobuf_writer "https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioV2Writer.java"
click node_cli "https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java"
click node_file_tools "https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractFileTool.java"
click node_graph_tools "https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractGraphTool.java"
click node_lint "https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/LintTool.java"

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_document,node_model,node_context,node_jsonld_context,node_streaming,node_emitters,node_legacy toneBlue
class node_reactor,node_rxjava toneAmber
class node_blackduck_io,node_graph_reader,node_sqlg,node_migration toneMint
class node_protobuf_schema,node_protobuf_converter,node_protobuf_reader,node_protobuf_writer toneRose
class node_cli,node_file_tools,node_graph_tools,node_lint toneIndigo
class node_spec toneNeutral
```

## Components

### BDIO 2 Core

JSON-LD model, contexts, and streaming contracts.

- [BdioDocument](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java): core document API · Frames model nodes with metadata and JSON-LD context. · `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java`
- **BDIO model nodes**: public model · Domain nodes used to construct BOM and scan graphs.
- [BdioContext](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioContext.java): context resolver · Interprets BDIO vocabulary and versions. · `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioContext.java`
- [Bundled JSON-LD context](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/resources/com/blackducksoftware/bdio2/bdio-context-2.1.jsonld): JSON-LD resource · `bdio2/src/main/resources/com/blackducksoftware/bdio2/bdio-context-2.1.jsonld`
- [Reader / Writer](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java): streaming API · Reads and writes BDIO document entries. · `bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java`
- [EmitterFactory](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/EmitterFactory.java): ingestion boundary · Selects native and compatibility stream emitters. · `bdio2/src/main/java/com/blackducksoftware/bdio2/EmitterFactory.java`
- [Legacy BDIO 1.x emitter](https://github.com/blackducksoftware/bdio/blob/master/bdio2/src/main/java/com/blackducksoftware/bdio2/LegacyBdio1xEmitter.java): compatibility converter · Converts legacy BDIO and scan-container input. · `bdio2/src/main/java/com/blackducksoftware/bdio2/LegacyBdio1xEmitter.java`

### Reactive Adapters

Optional Reactor and RxJava integrations.

- [Reactor document API](https://github.com/blackducksoftware/bdio/blob/master/bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorBdioDocument.java): Reactor adapter · Reactive document and JSON-LD processing for Reactor. · `bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorBdioDocument.java`
- [RxJava document API](https://github.com/blackducksoftware/bdio/blob/master/bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaBdioDocument.java): RxJava adapter · Reactive document and JSON-LD processing for RxJava. · `bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaBdioDocument.java`

### Graph Persistence

TinkerPop mapping, normalization, and SQL-backed storage.

- [BlackDuckIo](https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java): graph persistence API · Common API for BDIO-to-TinkerPop graph operations. · `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java`
- [Default graph reader](https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/spi/DefaultBlackDuckIoReader.java): graph mapper · Reads BDIO into normalized TinkerPop graphs. · `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/spi/DefaultBlackDuckIoReader.java`
- [SQLG graph backend](https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/SqlgBlackDuckIo.java): persistent graph backend · PostgreSQL-backed BlackDuckIo implementation. · `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/SqlgBlackDuckIo.java`
- [SQLG Flyway migrations](https://github.com/blackducksoftware/bdio/blob/master/bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/flyway/SqlgFlywayExecutor.java): schema migration · Migrates persistent graph schema. · `bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/flyway/SqlgFlywayExecutor.java`

### Protobuf Interchange

Separate typed binary scan-data path.

- [Scan protobuf schema](https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/proto/bdba_scan_nodes_v2.proto): protobuf schema · Defines typed version-2 scan headers, nodes, and chunks. · `bdio-protobuf/src/main/proto/bdba_scan_nodes_v2.proto`
- [Protobuf converter](https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioConverter.java): binary interchange · Converts typed protobuf scan data. · `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioConverter.java`
- [Protobuf reader](https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/ProtobufBdioReader.java): binary reader · `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/ProtobufBdioReader.java`
- [Protobuf V2 writer](https://github.com/blackducksoftware/bdio/blob/master/bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioV2Writer.java): binary writer · `bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioV2Writer.java`

### CLI

Command-line file and graph operations.

- [BdioMain](https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java): CLI entry point · Dispatches file, conversion, lint, graph, and output commands. · `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java`
- [File tools](https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractFileTool.java): CLI file operations · Handles file-oriented BDIO transformations. · `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractFileTool.java`
- [Graph tools](https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractGraphTool.java): CLI graph operations · Provides dependency, tree, visualization, and graph views. · `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractGraphTool.java`
- [LintTool](https://github.com/blackducksoftware/bdio/blob/master/bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/LintTool.java): CLI validator · Validates BDIO input from the command line. · `bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/LintTool.java`

### Other components

- [BDIO format spec](https://github.com/blackducksoftware/bdio/blob/master/docs/spec/02.Model.txt): normative docs · Defines the JSON-LD model and document format. · `docs/spec/02.Model.txt`

## Connections

- BDIO format spec → BdioDocument: specifies
- BDIO model nodes → BdioDocument: framed by
- Bundled JSON-LD context → BdioContext: defines vocabulary
- BdioContext → BdioDocument: interprets
- BdioDocument → Reader / Writer: serialized as entries
- EmitterFactory → Reader / Writer: emits input to
- Legacy BDIO 1.x emitter → EmitterFactory: selected for legacy input
- Reactor document API → BdioDocument: adapts
- RxJava document API → BdioDocument: adapts
- Reader / Writer → BlackDuckIo: maps documents through
- BlackDuckIo → Default graph reader: default implementation
- BlackDuckIo → SQLG graph backend: persistent implementation
- SQLG Flyway migrations → SQLG graph backend: migrates schema for
- Scan protobuf schema → Protobuf converter: generates typed API for
- Protobuf reader → Protobuf converter: feeds typed scan data
- Protobuf converter → Protobuf V2 writer: converts before output
- BdioMain → File tools: dispatches
- BdioMain → Graph tools: dispatches
- BdioMain → LintTool: dispatches
- File tools → Reader / Writer: consumes and produces
- Graph tools → BlackDuckIo: uses
- LintTool → Reader / Writer: validates input through