Skip to content

Architecture

GoGraph is a single-file embedded graph database written in pure Go, designed for minimalist, zero-dependency, high-performance runtime scenarios. The system design decouples through a clear layered model, ensuring single responsibility and high cohesion between modules.

1. System Module Division

GoGraph's core architecture is divided into 5 layers:

  1. API Layer (pkg/api): Provides user-friendly interfaces, similar to Open, Query, Exec from database/sql.
  2. Cypher Parsing and Execution Layer (pkg/cypher):
  3. Parser: Lexical analysis and syntax parsing, parsing Cypher statements into Abstract Syntax Trees (AST).
  4. AST: Declares execution nodes, structures, and data blocks.
  5. Executor: Coordinates Matcher, Creator, and Modifier to execute specific statement intents.
  6. Graph Model Layer (pkg/graph): Contains data structure encapsulation for nodes (Node), edges (Relationship), and property types (PropertyValue), along with core logic handling such as adjacency list management (AdjacencyList) and indexes (Index).
  7. Transaction Layer (pkg/tx): Encapsulates Pebble DB's transaction mechanism, controls multi-version concurrency (MVCC), and handles safe read/write operations.
  8. Storage Layer (pkg/storage): Based on CockroachDB's Pebble as a single-file storage engine, and handles encoding/gob serialization and deserialization.

2. System Architecture Diagram

The following Mermaid diagram shows GoGraph's architecture and data flow:

graph TD
    User([Application/User]) --> API[API Layer 
 pkg/api]

    subgraph GoGraph Core Engine
        API --> |Cypher String| Parser[Cypher Parser 
 pkg/cypher/parser.go]
        Parser --> |AST| Executor[Executor 
 pkg/cypher/executor.go]

        subgraph Action Handlers
            Executor --> |CREATE| Creator[Creator 
 pkg/cypher/creators]
            Executor --> |MATCH| Matcher[Matcher 
 pkg/cypher/matchers]
            Executor --> |SET/DELETE| Modifier[Modifier 
 pkg/cypher/modifiers]
        end

        Creator --> GraphModel[Graph Model / Data Encapsulation 
 pkg/graph]
        Matcher --> GraphModel
        Modifier --> GraphModel

        GraphModel --> |KV Mapping| TxMgr[Transaction Manager 
 pkg/tx]
    end

    TxMgr --> |Batch / Iterator| Storage[Storage Layer Pebble KV 
 pkg/storage]
    Storage --> |WAL & SSTables| Disk[(Local Single-File DB)]

3. Data Flow Description (CREATE Example)

  1. User calls api.Exec("CREATE (n:User {name: 'Alice'})").
  2. api.DB calls cypher.Parser to parse the statement into an AST (with CreateClause).
  3. Executor obtains a transaction object Tx and passes it to the Creator engine.
  4. Creator parses the AST to generate the corresponding graph.Node object, assigning a globally unique auto-incrementing ID.
  5. The graph layer uses storage.Marshal to serialize it into binary (gob).
  6. Creator delegates to the domain layer's graph.Index and graph.AdjacencyList (implicitly converting Tx to graph.Mutator for passing), synchronously building label indexes, property indexes, and adjacency list KV keys.
  7. Finally, Storage writes to disk through Pebble's Commit, making changes visible to other queries.

4. Core Execution Engine Optimizations (Query Optimization)

The refactored GoGraph implements a more advanced underlying query execution path: - Index Scan: When a MATCH statement specifies a node's Label (e.g., MATCH (n:User)), the engine no longer performs O(N) full table scans, but directly hits matching Node IDs via the Index tree with O(K) complexity. - Graph Traversal: For queries involving relationships (e.g., MATCH (n)-[r]->(m)), the system fully utilizes the adjacency list AdjacencyList, obtaining all associated edge IDs from the starting node in O(1) and precisely loading them, completely eliminating full-table brute-force traversal of edge relationships. - Rich Domain Model: All underlying KV assembly logic is consolidated in the pkg/graph layer, and the Cypher executor is only responsible for scheduling, ensuring atomic transaction modifications and high code cohesion.

5. Core Technology Stack

  • Base Language: Go 1.18+ (broad cross-platform compatibility)
  • Persistence Underlay: github.com/cockroachdb/pebble (replacement for LevelDB, high-performance KV library)
  • Object Serialization: Go's native encoding/gob (zero external dependencies, extremely fast and native encoding/decoding solution)
  • Observability: Logger/Tracer design based on the Option pattern for injection (defined in pkg/cypher/observability.go).