README.md raw

Neo4j Database Backend

A graph database backend implementation for the ORLY Nostr relay using Neo4j.

Quick Start

1. Start Neo4j

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.15

2. Configure Environment

All Neo4j configuration is defined in app/config/config.go and visible via ./orly help:

export ORLY_DB_TYPE=neo4j
export ORLY_NEO4J_URI=bolt://localhost:7687
export ORLY_NEO4J_USER=neo4j
export ORLY_NEO4J_PASSWORD=password
Note: Configuration is centralized in app/config/config.go. Do not use os.Getenv() directly in package code - all environment variables should be passed via the database.DatabaseConfig struct.

3. Run ORLY

./orly

Features

Architecture

See docs/NEO4J_BACKEND.md for comprehensive documentation on:

Tag-Based e/p Model

All tags, including e (event references) and p (pubkey mentions), are stored through intermediate Tag nodes:

Event -[:TAGGED_WITH]-> Tag{type:'e',value:eventId} -[:REFERENCES]-> Event
Event -[:TAGGED_WITH]-> Tag{type:'p',value:pubkey} -[:REFERENCES]-> NostrUser
Event -[:TAGGED_WITH]-> Tag{type:'t',value:topic}  (no REFERENCES for regular tags)

Benefits:

Migration: Existing databases with direct REFERENCES/MENTIONS relationships are automatically migrated at startup via v3 migration.

Web of Trust (WoT) Extensions

This package includes schema support for Web of Trust trust metrics computation:

- NostrUser nodes with trust metrics (influence, PageRank, verified counts) - NostrUserWotMetricsCard nodes for personalized multi-tenant metrics - Social graph relationships (FOLLOWS, MUTES, REPORTS) - Cypher schema definitions and example queries

- Algorithm implementations (GrapeRank, Personalized PageRank) - Event processing logic for kinds 0, 3, 1984, 10000 - Multi-tenant architecture and configuration - Performance considerations and deployment modes

Note: The WoT schema is applied automatically but WoT features are not yet fully implemented. See ADDITIONAL_REQUIREMENTS.md for the roadmap.

File Structure

Core Implementation

Documentation

Tests

Testing

Quick Start

# Start Neo4j using docker-compose
cd pkg/neo4j
docker-compose up -d

# Wait for Neo4j to be ready (~30 seconds)
docker-compose logs -f neo4j  # Look for "Started."

# Set Neo4j connection
export ORLY_NEO4J_URI="bolt://localhost:7687"
export ORLY_NEO4J_USER="neo4j"
export ORLY_NEO4J_PASSWORD="testpass123"

# Run all tests
go test -v

# Run social event processor tests
go test -v -run TestSocialEventProcessor

# Cleanup
docker-compose down -v

Test Coverage

The social-event-processor_test.go file contains comprehensive tests for:

See TESTING.md for detailed test documentation, troubleshooting, and how to view the graph in Neo4j Browser.

Viewing Test Results

After running tests, explore the graph at http://localhost:7474:

// View all social relationships
MATCH path = (u1:NostrUser)-[r:FOLLOWS|MUTES|REPORTS]->(u2:NostrUser)
RETURN path

// View event processing history
MATCH (evt:ProcessedSocialEvent)
RETURN evt ORDER BY evt.created_at

Example Cypher Queries

Find all events by an author

MATCH (e:Event {pubkey: "abc123..."})
RETURN e
ORDER BY e.created_at DESC

Find events with specific tags

MATCH (e:Event)-[:TAGGED_WITH]->(t:Tag {type: "t", value: "bitcoin"})
RETURN e

Event reference query (e-tags)

MATCH (e:Event)-[:TAGGED_WITH]->(t:Tag {type: "e"})-[:REFERENCES]->(ref:Event)
WHERE e.id = "abc123..."
RETURN e, ref

Mentions query (p-tags)

MATCH (e:Event)-[:TAGGED_WITH]->(t:Tag {type: "p"})-[:REFERENCES]->(u:NostrUser)
WHERE e.id = "abc123..."
RETURN e, u

Social graph query

MATCH (author:NostrUser {pubkey: "abc123..."})
<-[:AUTHORED_BY]-(e:Event)
-[:TAGGED_WITH]->(:Tag {type: "p"})-[:REFERENCES]->(mentioned:NostrUser)
RETURN author, e, mentioned

Performance Tips

  1. Use Limits: Always include LIMIT in queries
  2. Index Usage: Ensure queries use indexed properties (id, kind, created_at)
  3. Parameterize: Use parameterized queries to enable query plan caching
  4. Monitor: Use EXPLAIN and PROFILE to analyze query performance

Limitations

Why Neo4j for Nostr?

Nostr is inherently a social graph with heavy relationship queries:

Neo4j excels at these patterns, making it a natural fit for relationship-heavy Nostr queries.

License

Same as ORLY relay project.