# visallo/vertexium architecture

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

- Interactive diagram: https://gitdiagram.com/visallo/vertexium
- Repository: https://github.com/visallo/vertexium

## Overview

Vertexium is a security-aware graph API with interchangeable storage implementations and search integration. A typical workflow submits graph operations under authorizations and visibilities, persists vertices, edges, and properties through the Accumulo implementation, then retrieves graph elements or searches for them through Elasticsearch. Core query construction and Accumulo’s server-side iterators provide useful internal layers; streaming values and historical events are additional data capabilities. The README documents the backend and security model; sampled source confirms query construction and streaming storage behavior, but does not expose every persistence or indexing call site.

Main entry points: [`accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloGraph.java`](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloGraph.java) (Accumulo Graph), [`core/src/main/java/org/vertexium/Graph.java`](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/Graph.java) (Graph API), [`core/src/main/java/org/vertexium/query/QueryBase.java`](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/query/QueryBase.java) (Query Builder), [`accumulo/graph/src/main/java/org/vertexium/accumulo/util/StreamingPropertyValueStorageStrategy.java`](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/StreamingPropertyValueStorageStrategy.java) (Streaming Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Graph API"]
  node_graph_api["Graph API<br/>[Graph.java]"]
  node_query_builder["Query Builder<br/>[QueryBase.java]"]
end

subgraph group_storage["Accumulo Storage"]
  node_accumulo_graph["Accumulo Graph<br/>[AccumuloGraph.java]"]
  node_accumulo_auth["Authorizations"]
  node_element_mutation["Element Mutations"]
  node_accumulo_iterators["Server Iterators"]
  node_accumulo_store[("Accumulo")]
end

subgraph group_search["Search"]
  node_es5_query["Elasticsearch 5 Query"]
  node_es7_query["Elasticsearch 7 Query"]
  node_elasticsearch[("Elasticsearch")]
end

subgraph group_data["Graph Data"]
  node_stream_storage["Streaming Storage"]
  node_data_table_strategy["Data Table Strategy"]
  node_hdfs_strategy["HDFS Overflow"]
  node_hdfs[("HDFS")]
  node_history["Historical Events"]
  node_extended_data["Extended Data"]
end

subgraph group_interfaces["Query Interfaces"]
  node_cypher_context["Cypher Context"]
  node_cli["Vertexium CLI"]
end

node_caller(("Application"))

node_caller -->|"calls graph API"| node_graph_api
node_graph_api -->|"implemented by"| node_accumulo_graph
node_graph_api -->|"builds queries"| node_query_builder
node_accumulo_graph -->|"checks authorizations"| node_accumulo_auth
node_accumulo_graph -->|"persists mutations"| node_element_mutation
node_element_mutation -->|"writes graph data"| node_accumulo_store
node_accumulo_graph -->|"reads graph data"| node_accumulo_store
node_accumulo_iterators -->|"filters rows"| node_accumulo_store
node_accumulo_graph -.->|"uses server filtering"| node_accumulo_iterators
node_query_builder -.->|"executes search"| node_es5_query
node_query_builder -.->|"executes search"| node_es7_query
node_es5_query -->|"submits queries"| node_elasticsearch
node_es7_query -->|"submits queries"| node_elasticsearch
node_accumulo_graph -->|"stores streaming values"| node_stream_storage
node_stream_storage -.->|"strategy option"| node_data_table_strategy
node_stream_storage -.->|"strategy option"| node_hdfs_strategy
node_data_table_strategy -->|"writes value chunks"| node_accumulo_store
node_hdfs_strategy -->|"writes small values"| node_accumulo_store
node_hdfs_strategy -->|"overflows large values"| node_hdfs
node_accumulo_graph -->|"supports event history"| node_history
node_accumulo_graph -->|"supports extended data"| node_extended_data
node_caller -->|"runs commands"| node_cli
node_cli -->|"provides query context"| node_cypher_context
node_cypher_context -->|"operates on graph"| node_graph_api

click node_graph_api "https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/Graph.java"
click node_query_builder "https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/query/QueryBase.java"
click node_accumulo_graph "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloGraph.java"
click node_accumulo_auth "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloAuthorizations.java"
click node_element_mutation "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/ElementMutationBuilder.java"
click node_accumulo_iterators "https://github.com/visallo/vertexium/blob/master/accumulo/iterators/src/main/java/org/vertexium/accumulo/iterator/ElementIterator.java"
click node_stream_storage "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/StreamingPropertyValueStorageStrategy.java"
click node_data_table_strategy "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/DataInDataTableStreamingPropertyValueStorageStrategy.java"
click node_hdfs_strategy "https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/OverflowIntoHdfsStreamingPropertyValueStorageStrategy.java"
click node_history "https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/historicalEvent/HistoricalEvent.java"
click node_extended_data "https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/ExtendedDataRow.java"
click node_es5_query "https://github.com/visallo/vertexium/blob/master/elasticsearch5/search-index/src/main/java/org/vertexium/elasticsearch5/ElasticsearchSearchQueryBase.java"
click node_es7_query "https://github.com/visallo/vertexium/blob/master/elasticsearch7/search-index/src/main/java/org/vertexium/elasticsearch7/ElasticsearchSearchQueryBase.java"
click node_cypher_context "https://github.com/visallo/vertexium/blob/master/cypher/src/main/java/org/vertexium/cypher/VertexiumCypherQueryContext.java"
click node_cli "https://github.com/visallo/vertexium/blob/master/cli/src/main/java/org/vertexium/cli/VertexiumShell.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_graph_api,node_query_builder toneBlue
class node_accumulo_graph,node_accumulo_auth,node_element_mutation,node_accumulo_iterators,node_accumulo_store toneAmber
class node_es5_query,node_es7_query,node_elasticsearch toneMint
class node_stream_storage,node_data_table_strategy,node_hdfs_strategy,node_hdfs,node_history,node_extended_data toneRose
class node_cypher_context,node_cli,node_caller toneIndigo
```

## Components

### Graph API

- [Graph API](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/Graph.java): `core/src/main/java/org/vertexium/Graph.java`
- [Query Builder](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/query/QueryBase.java): `core/src/main/java/org/vertexium/query/QueryBase.java`

### Accumulo Storage

- [Accumulo Graph](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloGraph.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloGraph.java`
- [Authorizations](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloAuthorizations.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/AccumuloAuthorizations.java`
- [Element Mutations](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/ElementMutationBuilder.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/ElementMutationBuilder.java`
- [Server Iterators](https://github.com/visallo/vertexium/blob/master/accumulo/iterators/src/main/java/org/vertexium/accumulo/iterator/ElementIterator.java): `accumulo/iterators/src/main/java/org/vertexium/accumulo/iterator/ElementIterator.java`
- **Accumulo**

### Search

- [Elasticsearch 5 Query](https://github.com/visallo/vertexium/blob/master/elasticsearch5/search-index/src/main/java/org/vertexium/elasticsearch5/ElasticsearchSearchQueryBase.java): `elasticsearch5/search-index/src/main/java/org/vertexium/elasticsearch5/ElasticsearchSearchQueryBase.java`
- [Elasticsearch 7 Query](https://github.com/visallo/vertexium/blob/master/elasticsearch7/search-index/src/main/java/org/vertexium/elasticsearch7/ElasticsearchSearchQueryBase.java): `elasticsearch7/search-index/src/main/java/org/vertexium/elasticsearch7/ElasticsearchSearchQueryBase.java`
- **Elasticsearch**

### Graph Data

- [Streaming Storage](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/StreamingPropertyValueStorageStrategy.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/util/StreamingPropertyValueStorageStrategy.java`
- [Data Table Strategy](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/DataInDataTableStreamingPropertyValueStorageStrategy.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/util/DataInDataTableStreamingPropertyValueStorageStrategy.java`
- [HDFS Overflow](https://github.com/visallo/vertexium/blob/master/accumulo/graph/src/main/java/org/vertexium/accumulo/util/OverflowIntoHdfsStreamingPropertyValueStorageStrategy.java): `accumulo/graph/src/main/java/org/vertexium/accumulo/util/OverflowIntoHdfsStreamingPropertyValueStorageStrategy.java`
- **HDFS**
- [Historical Events](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/historicalEvent/HistoricalEvent.java): `core/src/main/java/org/vertexium/historicalEvent/HistoricalEvent.java`
- [Extended Data](https://github.com/visallo/vertexium/blob/master/core/src/main/java/org/vertexium/ExtendedDataRow.java): `core/src/main/java/org/vertexium/ExtendedDataRow.java`

### Query Interfaces

- [Cypher Context](https://github.com/visallo/vertexium/blob/master/cypher/src/main/java/org/vertexium/cypher/VertexiumCypherQueryContext.java): `cypher/src/main/java/org/vertexium/cypher/VertexiumCypherQueryContext.java`
- [Vertexium CLI](https://github.com/visallo/vertexium/blob/master/cli/src/main/java/org/vertexium/cli/VertexiumShell.java): `cli/src/main/java/org/vertexium/cli/VertexiumShell.java`

### Other components

- **Application**

## Connections

- Application → Graph API: calls graph API
- Graph API → Accumulo Graph: implemented by
- Graph API → Query Builder: builds queries
- Accumulo Graph → Authorizations: checks authorizations
- Accumulo Graph → Element Mutations: persists mutations
- Element Mutations → Accumulo: writes graph data
- Accumulo Graph → Accumulo: reads graph data
- Server Iterators → Accumulo: filters rows
- Accumulo Graph → Server Iterators: uses server filtering
- Query Builder → Elasticsearch 5 Query: executes search
- Query Builder → Elasticsearch 7 Query: executes search
- Elasticsearch 5 Query → Elasticsearch: submits queries
- Elasticsearch 7 Query → Elasticsearch: submits queries
- Accumulo Graph → Streaming Storage: stores streaming values
- Streaming Storage → Data Table Strategy: strategy option
- Streaming Storage → HDFS Overflow: strategy option
- Data Table Strategy → Accumulo: writes value chunks
- HDFS Overflow → Accumulo: writes small values
- HDFS Overflow → HDFS: overflows large values
- Accumulo Graph → Historical Events: supports event history
- Accumulo Graph → Extended Data: supports extended data
- Application → Vertexium CLI: runs commands
- Vertexium CLI → Cypher Context: provides query context
- Cypher Context → Graph API: operates on graph