Skip to main content

Chapter 1: Introduction and Core Concepts

Overview

Vektagraf represents a paradigm shift in database design, bringing together the best of object-oriented programming, vector search, and graph databases into a unified, schema-driven platform. Unlike traditional databases that force you to think in terms of tables, documents, or nodes, Vektagraf lets you work with objects as the primary abstraction, just as you do in your application code.

This chapter introduces Vektagraf's core philosophy, architecture, and unique value propositions. You'll learn how Vektagraf's object-centric design simplifies complex data operations while providing enterprise-grade security and performance.

Learning Objectives

By the end of this chapter, you will understand:

  • Vektagraf's object-centric design philosophy and how it differs from traditional databases
  • The schema-driven development approach and its benefits
  • Core architectural components and their interactions
  • How vectors and graphs are treated as object properties rather than separate entities
  • The unique value propositions that make Vektagraf suitable for modern applications

Prerequisites

  • Basic understanding of Dart programming language
  • Familiarity with database concepts (SQL or NoSQL)
  • Understanding of object-oriented programming principles

Core Concepts

The Object-Centric Philosophy

Traditional databases force you to think in their terms: tables and rows for SQL, documents for NoSQL, or nodes and edges for graph databases. This creates an impedance mismatch between your application's object model and the database's storage model.

Vektagraf eliminates this mismatch by making objects the primary abstraction. In Vektagraf:

  • Objects are first-class citizens: Your Dart objects map directly to database entities
  • Vectors are just properties: High-dimensional vectors are treated as regular object properties that happen to support similarity search
  • Relationships are object references: Graph edges emerge naturally from object relationships
  • Security is object-aware: Access control and encryption operate at the object and field level
// Traditional approach: Think in database terms
await db.collection('users').doc(userId).update({
  'profile_vector': embedding,
  'friend_ids': [friend1Id, friend2Id]
});

// Vektagraf approach: Think in object terms
final user = await db.users().where((u) => u.id == userId).first;
user.profileEmbedding = embedding;
user.friends.addAll([friend1, friend2]);
await user.save();

Schema-Driven Development

Vektagraf uses a single schema written in JSON to define your entire data model, including:

  • Object structures and field types
  • Vector configurations and similarity functions
  • Relationship definitions and graph topology
  • Security policies and access controls
  • Privacy settings and compliance requirements

This schema serves as the single source of truth for your application's data layer:

{
  "models": {
    "user": {
      "id": "id",
      "name": "string",
      "email": "string",
      "profile_embedding": {
        "type": "vector",
        "dimensions": 384,
        "distance_function": "cosine"
      },
      "posts": "[@post]",
      "friends": "{@user}"
    }
  }
}

From this schema, Vektagraf automatically generates:

  • Type-safe Dart classes with proper field types and validation
  • Database operations optimized for your specific data model
  • Vector search methods for similarity operations
  • Graph traversal APIs for relationship navigation
  • Security enforcement based on your access control policies

Fluent Method Chaining

Vektagraf provides a fluent API that lets you build complex queries using natural Dart syntax. Operations can be chained together to create sophisticated data access patterns:

// Find posts similar to user interests, from high-reputation authors,
// with preferred tags, ordered by recency
final recommendations = await db.posts()
  .whereSimilar(userInterestVector, limit: 50)
  .where((post) => post.author.reputation > 100)
  .expand((post) => post.tags)
  .where((tag) => userPreferredTags.contains(tag.name))
  .expand((tag) => tag.posts)
  .orderBy((post) => post.createdAt, descending: true)
  .take(10);

This approach combines:

  • Vector similarity search (whereSimilar)
  • Traditional filtering (where)
  • Graph traversal (expand)
  • Sorting and pagination (orderBy, take)

All in a single, readable expression with full type safety.

Architecture Overview

Vektagraf's architecture is designed around modularity, performance, and security. The system consists of several key components that work together to provide a unified data platform.

graph TB
    subgraph "Application Layer"
        App[Dart Application]
        Schema[JSON Schema]
        Generated[Generated Code]
    end
    
    subgraph "Vektagraf Core"
        DB[VektagrafDatabase]
        Parser[Schema Parser]
        CodeGen[Code Generator]
        Transaction[Transaction Manager]
    end
    
    subgraph "Storage Layer"
        Memory[Memory Engine]
        File[File Engine]
        Vector[Vector Spaces]
        Graph[Graph Engine]
    end
    
    subgraph "Security Layer"
        Encryption[Encryption Engine]
        Access[Access Control]
        Audit[Audit Logger]
        Privacy[Privacy Engine]
    end
    
    subgraph "Network Layer"
        Client[Vektagraf Client]
        Server[Vektagraf Server]
        Transport[Transport Layer]
    end
    
    App --> Generated
    Schema --> Parser
    Parser --> CodeGen
    CodeGen --> Generated
    Generated --> DB
    
    DB --> Transaction
    DB --> Memory
    DB --> File
    DB --> Vector
    DB --> Graph
    
    DB --> Encryption
    DB --> Access
    DB --> Audit
    DB --> Privacy
    
    Client --> Transport
    Server --> Transport
    Transport --> DB
    
    style App fill:#e1f5fe
    style Schema fill:#f3e5f5
    style Generated fill:#e8f5e8
    style DB fill:#fff3e0
    style Security fill:#ffebee

Core Components

VektagrafDatabase

The main entry point for all database operations. Provides:

  • Object lifecycle management (create, read, update, delete)
  • Transaction coordination and ACID guarantees
  • Query planning and optimization
  • Security policy enforcement

Schema Parser and Code Generator

Transforms JSON schemas into executable Dart code:

  • Schema Parser: Validates and parses JSON schema definitions
  • Code Generator: Creates type-safe Dart classes and database extensions
  • Extension Generator: Builds fluent APIs for each model type

Storage Engines

Multiple storage backends for different deployment scenarios:

  • Memory Engine: In-memory storage for development and testing
  • File Engine: Persistent file-based storage for embedded applications
  • Distributed Engine: Clustered storage for enterprise deployments

Vector Spaces

Specialized storage and indexing for high-dimensional vectors:

  • HNSW (Hierarchical Navigable Small World): Fast approximate nearest neighbor search
  • IVFFlat: Inverted file with flat compression for memory efficiency
  • Memory Vector Space: In-memory vector storage for small datasets

Security Framework

Comprehensive security and privacy protection:

  • Encryption Engine: AES-256-GCM encryption at rest and in transit
  • Access Control: Role-based and attribute-based access control (RBAC/ABAC)
  • Privacy Engine: Selective disclosure, zero-knowledge proofs, differential privacy
  • Audit Logger: Comprehensive audit trails for compliance

Data Flow Architecture

sequenceDiagram
    participant App as Application
    participant Gen as Generated Code
    participant DB as VektagrafDatabase
    participant Sec as Security Layer
    participant Store as Storage Engine
    participant Vec as Vector Space
    
    App->>Gen: user.save()
    Gen->>DB: saveObject(user)
    DB->>Sec: checkPermissions(user, 'write')
    Sec-->>DB: authorized
    DB->>Sec: encryptFields(user)
    Sec-->>DB: encryptedUser
    DB->>Store: storeObject(encryptedUser)
    Store-->>DB: objectId
    
    alt Vector Field Present
        DB->>Vec: addVector(user.embedding, metadata)
        Vec-->>DB: vectorId
    end
    
    DB-->>Gen: success
    Gen-->>App: saved user

This architecture ensures that:

  1. Security is enforced at every layer - no data bypasses access control
  2. Vector operations are transparent - embedding fields automatically get indexed
  3. Performance is optimized - queries are planned and executed efficiently
  4. Transactions are atomic - all operations succeed or fail together

Comparison with Traditional Databases

Understanding how Vektagraf differs from traditional database approaches helps clarify its unique value proposition.

vs. Relational Databases (SQL)

Aspect SQL Databases Vektagraf
Data Model Tables, rows, columns Objects with properties
Relationships Foreign keys, JOINs Direct object references
Vector Search External extensions Built-in vector properties
Schema Evolution ALTER TABLE migrations JSON schema updates
Type Safety Runtime SQL errors Compile-time Dart validation
Query Language SQL strings Fluent Dart methods 
// SQL approach
final result = await db.query('''
  SELECT u.*, p.title 
  FROM users u 
  JOIN posts p ON u.id = p.author_id 
  WHERE u.name LIKE ? 
  ORDER BY p.created_at DESC
''', ['%Alice%']);

// Vektagraf approach
final result = await db.users()
  .where((u) => u.name.contains('Alice'))
  .expand((u) => u.posts)
  .orderBy((p) => p.createdAt, descending: true);

vs. Document Databases (NoSQL)

Aspect Document DBs Vektagraf
Structure Flexible documents Structured objects
Relationships Manual references Automatic graph edges
Vector Search Plugin required Native support
Consistency Eventually consistent ACID transactions
Type Safety Runtime validation Compile-time checking
Security Application-level Database-enforced 
// MongoDB approach
final users = await collection.find({
  'profile.interests': {'\$in': userInterests}
}).toList();

// Vektagraf approach
final users = await db.users()
  .whereSimilar(userInterestVector, limit: 10);

vs. Vector Databases

Aspect Vector DBs Vektagraf
Primary Focus Vector similarity Object-centric with vectors
Data Model Vectors + metadata Rich object models
Relationships External system Built-in graph operations
Transactions Limited support Full ACID compliance
Security Basic access control Enterprise-grade privacy
Integration Separate system Unified data platform 
// Pinecone/Weaviate approach
final vectors = await vectorDB.query(
  vector: queryEmbedding,
  topK: 10,
  filter: {'category': 'technology'}
);
// Then fetch full objects from another database...

// Vektagraf approach
final posts = await db.posts()
  .whereSimilar(queryEmbedding, limit: 10)
  .where((p) => p.category == 'technology');
// Objects and vectors unified in one operation

vs. Graph Databases

Aspect Graph DBs Vektagraf
Query Language Cypher, Gremlin Fluent Dart methods
Data Model Nodes and edges Objects and relationships
Vector Support External plugins Native vector properties
Type Safety Runtime validation Compile-time checking
Schema Schema-optional Schema-driven
Performance Graph-optimized Multi-modal optimized 
// Neo4j Cypher approach
MATCH (u:User)-[:FRIENDS_WITH]->(f:User)-[:POSTED]->(p:Post)
WHERE u.name = 'Alice'
RETURN p.title, p.content

// Vektagraf approach
final posts = await db.users()
  .where((u) => u.name == 'Alice')
  .expand((u) => u.friends)
  .expand((f) => f.posts);

Unique Value Propositions

Vektagraf's design provides several unique advantages that make it particularly suitable for modern applications:

1. Unified Data Platform

Instead of managing separate systems for objects, vectors, and graphs, Vektagraf provides a single platform that handles all three seamlessly:

// One database, multiple paradigms
final recommendations = await db.users()
  .where((u) => u.id == currentUserId)           // Object filtering
  .expand((u) => u.friends)                      // Graph traversal
  .expand((f) => f.posts)                        // More graph traversal
  .whereSimilar(userInterestVector, limit: 20)   // Vector similarity
  .where((p) => p.publishedAt.isAfter(lastWeek)) // Object filtering
  .take(5);                                      // Pagination

2. Schema-Driven Security

Security policies are defined alongside data models, ensuring consistent enforcement:

{
  "models": {
    "user": {
      "email": {
        "type": "string",
        "security": {
          "encrypted": true,
          "access": ["read:owner", "read:admin"]
        }
      },
      "profile_embedding": {
        "type": "vector",
        "dimensions": 384,
        "security": {
          "encrypted": true,
          "differential_privacy": {"epsilon": 0.1}
        }
      }
    }
  }
}

3. Privacy-by-Design

Built-in privacy features enable compliant data sharing:

// Share user data with selective disclosure
final publicProfile = await user.toDisclosureToken(
  disclosableFields: ['name', 'skills'],
  signingKey: privateKey,
);

// Prove age without revealing it
final ageProof = await user.createAgeProof(
  minimumAge: 21,
  signingKey: privateKey,
);

4. Natural Dart Integration

Generated code feels like native Dart, with full IDE support:

// Type-safe, auto-complete friendly
final user = User(
  name: 'Alice',
  email: 'alice@example.com',
  profileEmbedding: embedding,
);

await db.users().save(user);

// Compile-time error if field doesn't exist
final posts = await user.posts.where((p) => p.published).toList();

5. Flexible Deployment

Same codebase works across deployment scenarios:

// Embedded mode - single file database
final db = VektagrafDatabase();
await db.open('app.vektagraf');

// Hosted mode - connect to server
final db = VektagrafDatabase();
await db.open('vektagraf://server:port/database');

// Distributed mode - cluster connection
final db = VektagrafDatabase();
await db.open('vektagraf://cluster/database?nodes=3');

System Architecture Deep Dive

Object Lifecycle Management

Vektagraf manages the complete lifecycle of objects from creation to deletion, with automatic handling of vectors and relationships:

stateDiagram-v2
    [*] --> Created: new Object()
    Created --> Validated: validate()
    Validated --> Encrypted: encrypt()
    Encrypted --> Stored: store()
    Stored --> Indexed: index vectors
    Indexed --> Active: ready
    
    Active --> Modified: update()
    Modified --> Validated: validate()
    
    Active --> Retrieved: query()
    Retrieved --> Decrypted: decrypt()
    Decrypted --> Active: ready
    
    Active --> Deleted: delete()
    Deleted --> [*]: cleanup

Vector Integration Architecture

Vectors are seamlessly integrated into the object model:

graph LR
    subgraph "Object Layer"
        Obj[User Object]
        Embed[profileEmbedding: List<double>]
    end
    
    subgraph "Vector Layer"
        VSpace[Vector Space]
        HNSW[HNSW Index]
        Search[Similarity Search]
    end
    
    subgraph "Storage Layer"
        ObjStore[Object Storage]
        VecStore[Vector Storage]
    end
    
    Obj --> Embed
    Embed --> VSpace
    VSpace --> HNSW
    HNSW --> Search
    
    Obj --> ObjStore
    VSpace --> VecStore
    
    Search -.-> Obj

When you save an object with vector fields:

  1. Object data is stored in the primary storage engine
  2. Vector data is automatically indexed in the appropriate vector space
  3. Metadata links connect object IDs to vector IDs
  4. Similarity queries return full objects, not just vectors

Graph Relationship Handling

Object relationships automatically create graph edges:

// Define relationships in schema
{
  "user": {
    "friends": "{@user}",      // Many-to-many relationship
    "posts": "[@post]"         // One-to-many relationship
  },
  "post": {
    "author": "@user",         // Many-to-one relationship
    "tags": "{@tag}"           // Many-to-many relationship
  }
}

// Use relationships naturally in code
final user = User(name: 'Alice');
final post = Post(title: 'Hello World', author: user);
user.posts.add(post);  // Automatically creates graph edge

// Traverse relationships with fluent API
final friendsPosts = await db.users()
  .where((u) => u.name == 'Alice')
  .expand((u) => u.friends)    // Follow friend edges
  .expand((f) => f.posts);     // Follow post edges

Security Architecture

Security is enforced at multiple layers:

graph TB
    subgraph "Application Layer"
        API[Generated API]
        Auth[Authentication]
    end
    
    subgraph "Security Layer"
        RBAC[Role-Based Access Control]
        Encrypt[Field Encryption]
        Audit[Audit Logging]
        Privacy[Privacy Engine]
    end
    
    subgraph "Storage Layer"
        Store[Encrypted Storage]
        Index[Encrypted Indexes]
    end
    
    API --> Auth
    Auth --> RBAC
    RBAC --> Encrypt
    Encrypt --> Audit
    Audit --> Privacy
    Privacy --> Store
    Privacy --> Index
    
    style Security fill:#ffebee
    style Store fill:#e8f5e8

Summary

Vektagraf represents a new approach to database design that prioritizes developer experience while providing enterprise-grade capabilities. By treating objects as the primary abstraction and integrating vectors and graphs as natural properties, Vektagraf eliminates the complexity of managing multiple specialized systems.

Key takeaways from this chapter:

  1. Object-centric design eliminates impedance mismatch between application and database models
  2. Schema-driven development provides a single source of truth for data, security, and API generation
  3. Fluent method chaining enables complex queries with natural Dart syntax
  4. Unified platform combines object storage, vector search, and graph operations
  5. Privacy-by-design enables compliant data sharing and advanced privacy features
  6. Flexible deployment supports embedded, hosted, and distributed scenarios

In the next chapter, we'll dive into practical usage by setting up your first Vektagraf application and exploring the basic operations that form the foundation of more advanced features.

Next Steps

  • Chapter 2: Getting Started and Basic Usage - Set up your first Vektagraf-backed application
  • Chapter 3: Schema Design and Code Generation - Master the schema-driven development workflow
  • Chapter 5: Vector Search and Similarity Operations - Explore advanced vector search capabilities
  • Chapter 6: Graph Operations and Relationship Modeling - Learn graph traversal and analysis patterns
No Comments
Back to top