InterRealm Graph

Extensible knowledge graph foundation for AI systems with dynamic schema management.

🏗️ Monorepo Structure

interrealm-graph/
├── packages/
│   ├── graph-types/        # TypeScript type definitions
│   ├── postgres/           # PostgreSQL metadata layer (Prisma)
│   ├── graph-service/      # REST API service
│   └── client-test/        # Test client application
├── package.json
├── turbo.json
└── README.md

📦 Packages

@interrealm/graph-types

Core TypeScript type definitions for graph schemas.

• Node type definitions
• Edge type definitions
• Schema validation
• Query types
• Deployment types

@interrealm/postgres

PostgreSQL metadata layer using Prisma ORM.

• Stores schema definitions
• Tracks node/edge types
• Manages dependencies
• Records deployments

@interrealm/graph-service

Express-based REST API service.

• Schema deployment endpoints
• Graph instance management
• Compatibility checking
• Metadata queries

@interrealm/client-test

Test client for validating the system.

• Basic functionality tests
• Document schema tests
• Integration examples

🚀 Quick Start

Prerequisites

• Node.js >= 18
• pnpm >= 8
• PostgreSQL >= 14
• Docker (optional, for PostgreSQL)

Installation

# Clone the repo
git clone https://github.com/your-org/interrealm-graph
cd interrealm-graph

# Install dependencies
pnpm install

# Build all packages
pnpm build

Setup PostgreSQL

# Start PostgreSQL with Docker
docker run -d \
  --name interrealm-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=interrealm \
  -p 5432:5432 \
  postgres:16

# Or use your existing PostgreSQL instance

Configure Database

# Create .env file in packages/postgres
cd packages/postgres
cat > .env << EOF
DATABASE_URL="postgresql://postgres:password@localhost:5432/interrealm?schema=public"
EOF

# Run migrations
pnpm db:migrate

# Generate Prisma client
pnpm db:generate

Start the Service

# From root directory
cd packages/graph-service

# Create .env file
cat > .env << EOF
PORT=3000
DATABASE_URL="postgresql://postgres:password@localhost:5432/interrealm?schema=public"
EOF

# Start the server
pnpm dev

Server will be running at http://localhost:3000

Run Tests

# In another terminal
cd packages/client-test

# Run basic tests
pnpm test:basic

# Run document schema tests
pnpm test:document-schema

# Run all tests
pnpm test:all

📚 Usage Examples

Define a Schema

import { defineSchema } from '@interrealm/graph-types';

const mySchema = defineSchema({
  name: 'my-app',
  version: '1.0.0',
  
  nodeTypes: {
    User: {
      properties: {
        email: { type: 'string', required: true },
        name: { type: 'string' }
      }
    },
    
    Post: {
      properties: {
        title: { type: 'string', required: true },
        content: { type: 'string' }
      }
    }
  },
  
  edgeTypes: {
    AUTHORED: {
      from: 'User',
      to: 'Post',
      cardinality: '1:N'
    }
  }
});

Deploy Schema via API

curl -X POST http://localhost:3000/api/schemas \
  -H "Content-Type: application/json" \
  -H "x-user-id: duncan" \
  -d @my-schema.json

List Schemas

curl http://localhost:3000/api/schemas

Get Specific Schema

curl http://localhost:3000/api/schemas/my-app/1.0.0

🔧 Development

Build

# Build all packages
pnpm build

# Build specific package
cd packages/graph-types
pnpm build

Watch Mode

# Watch all packages
pnpm dev

# Watch specific package
cd packages/graph-service
pnpm dev

Database Management

# Open Prisma Studio
cd packages/postgres
pnpm db:studio

# Create new migration
pnpm db:migrate

# Reset database
pnpm db:push --force-reset

Testing

# Run all tests
pnpm test

# Run tests for specific package
cd packages/graph-types
pnpm test

📊 Database Schema

The PostgreSQL metadata layer stores:

• schemas: Deployed schema versions
• node_types: Node type definitions
• edge_types: Edge type definitions
• schema_dependencies: Dependency graph
• graph_instances: Connected graph databases
• deployed_schemas: Deployment tracking

🔗 API Endpoints

Schemas

• POST /api/schemas - Deploy a schema
• GET /api/schemas - List all schemas
• GET /api/schemas/:name - Get latest version
• GET /api/schemas/:name/:version - Get specific version
• POST /api/schemas/check-compatibility - Check compatibility

Graph Instances

• POST /api/instances - Register graph instance
• GET /api/instances - List instances
• POST /api/instances/:id/deploy/:schema - Deploy schema to instance

Health

• GET /health - Service health check

🎯 Roadmap

• Core type system
• PostgreSQL metadata layer
• REST API service
• Basic test client
• ArangoDB adapter
• Neo4j adapter
• Schema versioning & migration
• GraphQL API generation
• Web UI for schema management
• Schema marketplace/registry

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT

🔗 Links

• GitHub: https://github.com/intereralm-io/intereralm-graph