Repository map

The repository is organized by responsibility, not by one monolithic driver.

Area	What to learn	Evidence
graph/graph-core	models, repository contracts, schema and algorithms	GraphOperations.kt
graph/graph-*	backend semantics and adapters	Neo4jGraphOperations.kt
graph-io/*	records, formats and bulk transfer	GraphBulkImporter.kt
ktor, spring-boot	application lifetime integration	GraphPlugin.kt
examples	domain-shaped use and cross-backend tests	AbstractCodeGraphTest.kt
benchmark	workload evidence, not API promises	benchmark/README.md

Read core contracts before a backend implementation. Then trace one operation from interface to backend test. Example projects are deliberately unpublished; copy their design ideas, not their dependency coordinates or deployment assumptions.

When diagnosing a failure, locate its layer: model validation, repository capability, backend query/transaction, format codec, or application lifecycle. This prevents a driver-specific symptom from being documented as a portable contract.

Trace one operation through the repository

rg -n 'fun shortestPath' graph/graph-core graph/graph-neo4j graph/graph-memgraph graph/graph-age graph/graph-tinkerpop graph/graph-falkordb
./gradlew :bluetape4k-graph-core:test --tests '*ShortestPathFallbackTest'
./gradlew :code-graph-examples:test --tests '*TinkerGraphCodeGraphTest'

Expected: the contract appears in core, backend implementations or fallbacks supply behavior, and the domain example asserts a concrete path. If core passes but the example fails, inspect schema/data setup. If only one backend fails, inspect its query translation and capability test. If all implementations pass but an application route fails, move outward to framework lifetime and resource ownership.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.5.1 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

graph Architecture diagram

Release README: README.md

graph Class Structure 2 diagram

Release README: README.md

Backend capability matrix

Release README: README.md

Bluetape4k Graph overview diagram

Release README: README.md