GigaBrain 🧠#

A high-performance, in-memory graph database written in Rust with Cypher query support.

✨ Features#

• 🚀 High Performance: In-memory storage with optimized data structures
• 📊 Cypher Support: Neo4j-compatible query language
• 💻 Interactive CLI: Comprehensive command-line interface with REPL
• 🔍 Graph Algorithms: Built-in pathfinding, centrality, and community detection
• 🌐 Dual APIs: Both REST and gRPC interfaces
• 🔐 Authentication: JWT-based auth with role-based access control
• 💾 Persistence: Optional RocksDB backend for data durability
• 📈 Monitoring: Built-in metrics and observability
• ✅ Schema Validation: Comprehensive constraint system for data integrity
• 📥📤 Data Management: JSON/CSV import/export capabilities

🚀 Quick Start#

Installation#

git clone https://github.com/your-org/gigabrain.git
cd gigabrain
cargo build --release

Running the Server#

# Start both REST (port 3000) and gRPC (port 50051) servers
cargo run --bin gigabrain

Using the CLI#

# Build and start the interactive CLI
cargo build --release --bin gigabrain-cli
./target/release/gigabrain-cli

# Interactive REPL usage
gigabrain> CREATE (alice:Person {name: 'Alice', age: 30})
gigabrain> MATCH (n:Person) RETURN n.name, n.age
gigabrain> :stats
gigabrain> :help

# Single command execution
./target/release/gigabrain-cli --execute "MATCH (n) RETURN count(n)"

# Batch file processing
./target/release/gigabrain-cli --file my_queries.cypher

Basic Usage#

# Health check
curl http://localhost:3000/api/v1/health

# Create a person
curl -X POST http://localhost:3000/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["Person"],
    "properties": {
      "name": "Alice",
      "age": 30
    }
  }'

# Execute Cypher query
curl -X POST http://localhost:3000/api/v1/cypher \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (n:Person) RETURN n.name, n.age LIMIT 10"
  }'

📚 Documentation#

• CLI Guide - Complete command-line interface documentation
• API Reference - Complete REST and gRPC API documentation
• Architecture Guide - Technical architecture and design decisions
• Examples - Practical usage examples and tutorials
• Project Overview - Detailed project documentation

🏗️ Architecture#

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   CLI/REPL      │  │   REST API      │  │   gRPC API      │
│   Interface     │  │   (Port 3000)   │  │   (Port 50051)  │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                     │                     │
         └─────────────────────┼─────────────────────┘
                               │
               ┌─────────────────┐
               │   API Layer     │
               │  (Auth/Routing) │
               └─────────────────┘
                               │
               ┌─────────────────┐
               │  Query Engine   │
               │ (Cypher Parser) │
               └─────────────────┘
                               │
               ┌─────────────────┐
               │  Graph Engine   │
               │ (Core Storage)  │
               └─────────────────┘
                               │
               ┌─────────────────┐
               │ Storage Layer   │
               │ (Memory/RocksDB)│
               └─────────────────┘

🎯 Use Cases#

Social Networks#

• Friend recommendations
• Community detection
• Influence analysis

Fraud Detection#

• Pattern recognition
• Anomaly detection
• Risk scoring

Knowledge Graphs#

• Semantic search
• Recommendation engines
• Data lineage

Supply Chain#

• Route optimization
• Dependency analysis
• Impact assessment

📊 Performance#

Benchmarks on 16-core machine with 32GB RAM:

🔧 Configuration#

Server Options#

ServerConfig {
    rest_port: 3000,
    grpc_port: 50051,
    max_connections: 1000,
    request_timeout: Duration::from_secs(30),
    enable_cors: true,
    jwt_secret: "your-secret-key",
}

Storage Backends#

# In-memory (default)
cargo run

# With RocksDB persistence
cargo run --features rocksdb-storage

🧪 Development#

Building#

# Debug build
cargo build

# Release build
cargo build --release

# With all features
cargo build --all-features

Testing#

# Run all tests
cargo test

# Run with coverage
cargo test --all-features

# Benchmarks
cargo bench

Code Quality#

# Format code
cargo fmt

# Run linter
cargo clippy

# Check documentation
cargo doc --no-deps --open

🔌 API Examples#

REST API#

import requests

# Create node
response = requests.post('http://localhost:3000/api/v1/nodes', json={
    'labels': ['Person'],
    'properties': [
        {'key': 'name', 'value': {'string_value': 'Alice'}}
    ]
})

# Execute query
response = requests.post('http://localhost:3000/api/v1/cypher', json={
    'query': 'MATCH (n:Person) RETURN n.name'
})

gRPC API#

conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
client := pb.NewGigaBrainServiceClient(conn)

node, _ := client.CreateNode(context.Background(), &pb.CreateNodeRequest{
    Labels: []string{"Person"},
    Properties: []*pb.Property{
        {Key: "name", Value: &pb.PropertyValue{
            Value: &pb.PropertyValue_StringValue{StringValue: "Alice"},
        }},
    },
})

🏷️ Graph Algorithms#

Pathfinding#

• Dijkstra's shortest path
• A* pathfinding
• Bidirectional search

Centrality#

• PageRank
• Betweenness centrality
• Closeness centrality

Community Detection#

• Louvain algorithm
• Modularity optimization
• Label propagation

Traversal#

• Breadth-first search
• Depth-first search
• Random walks

📈 Monitoring#

Metrics#

# Prometheus metrics
curl http://localhost:3000/metrics

Health Checks#

# Application health
curl http://localhost:3000/api/v1/health

# Detailed status
curl http://localhost:3000/api/v1/stats

🚢 Deployment#

Docker#

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/gigabrain /usr/local/bin/
EXPOSE 3000 50051
CMD ["gigabrain"]

Kubernetes#

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gigabrain
spec:
  replicas: 3
  selector:
    matchLabels:
      app: gigabrain
  template:
    spec:
      containers:
      - name: gigabrain
        image: gigabrain:latest
        ports:
        - containerPort: 3000
        - containerPort: 50051

🤝 Contributing#

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines#

• Follow Rust best practices
• Write comprehensive tests
• Update documentation
• Use conventional commits

📄 License#

This project is licensed under the MIT License - see the LICENSE file for details.

🛣️ Roadmap#

v0.2.0#

• Distributed deployment support
• Advanced query optimization
• Real-time streaming APIs
• Graph visualization tools

v0.3.0#

• Machine learning integration
• Time-series graph support
• Advanced security features
• Cloud provider integrations

v1.0.0#

• Production-ready stability
• Enterprise features
• Professional support

📞 Support#

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🌟 Acknowledgments#

• Neo4j for Cypher query language inspiration
• Rust Graph for graph algorithms reference
• Tokio for async runtime
• Tonic for gRPC support

Built with ❤️ in Rust