Graphmaster

A reference platform that maps real-world data domains to graph models, reasoning tasks, and recommended layouts. Graphmaster is a meta-graph—a knowledge graph about graphs—that helps developers and architects make informed decisions about graph visualization and analysis.

Quick Start

git clone https://github.com/yourusername/graphmaster.git
cd graphmaster
./setup.sh

This will:

1. Start Neo4j in Docker
2. Install npm dependencies
3. Load all seed data

Then open http://localhost:7474 (credentials: neo4j / graphmaster)

Requirements: Docker + Node.js 18+

---

What It Does

Graphmaster answers questions like:

• "For an ITSM domain, which graph layouts work best?"
• "What reasoning tasks does a Knowledge Graph support?"
• "Which constraints apply to hierarchical data, and what happens when they're violated?"
• "I need to do root-cause analysis—which layout should I use?"

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           GRAPHMASTER                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Domain ──HAS_PATTERN──► GraphPattern                              │
│     │                          │                                    │
│     │                          ├──HAS_CONSTRAINT──► Constraint      │
│     │                          │                        │           │
│     └──REQUIRES_TASK─┐         │            ◄──VIOLATES_CONSTRAINT──┤
│                      │         │                        │           │
│                      ▼         │                   FailureMode      │
│   Layout ──SUPPORTS_TASK──► ReasoningTask              ▲            │
│     │                                                  │            │
│     ├──OBSCURES_TASK──► ReasoningTask                  │            │
│     ├──WORKS_WITH──► GraphPattern                      │            │
│     ├──INCOMPATIBLE_WITH──► GraphPattern               │            │
│     ├──REQUIRES_CONSTRAINT──► Constraint               │            │
│     └──CAN_CAUSE───────────────────────────────────────┘            │
│                                                                     │
│   ExampleGraph ──ILLUSTRATES──► GraphPattern                        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Node Types

Node	Description
Domain	Real-world problem areas (ITSM, Knowledge Graphs, Biology, etc.)
Layout	Graph visualization algorithms (Dagre, CoSE, Concentric, etc.)
ReasoningTask	Cognitive tasks users perform (root-cause analysis, clustering, etc.)
GraphPattern	Structural patterns (DAG, tree, mesh, bipartite, etc.)
Constraint	Rules that must hold (acyclicity, single root, etc.)
FailureMode	What goes wrong when constraints are violated
ExampleGraph	Small illustrative graphs demonstrating patterns

Using Your Own Neo4j Instance

If you already have Neo4j running (local install, Aura, etc.):

git clone https://github.com/yourusername/graphmaster.git
cd graphmaster
npm install

# Configure connection
cp .env.example .env
# Edit .env with your Neo4j credentials

npm run ingest

Expected output:

╔════════════════════════════════════════════════════════════╗
║           GRAPHMASTER NEO4J INGESTION                      ║
╚════════════════════════════════════════════════════════════╝

✓ Neo4j connection verified

📂 Loading and validating data...
✓ Loaded and validated 10 items from domains.json
✓ Loaded and validated 17 items from layouts.json
✓ Loaded and validated 15 items from reasoning-tasks.json
✓ Loaded and validated 12 items from graph-patterns.json
✓ Loaded and validated 12 items from constraints.json
✓ Loaded and validated 10 items from failure-modes.json
✓ Loaded relationships from relationships.json

📋 Creating uniqueness constraints...
📇 Creating indexes...
📥 Ingesting nodes...
🔗 Ingesting relationships...

╔════════════════════════════════════════════════════════════╗
║                    INGESTION COMPLETE                      ║
╚════════════════════════════════════════════════════════════╝

Run Sample Queries

npm run queries

This demonstrates the types of questions Graphmaster can answer.

Example Queries

Which layout best supports root-cause analysis?

MATCH (l:Layout)-[r:SUPPORTS_TASK]->(t:ReasoningTask {name: 'Root Cause Analysis'})
RETURN l.name as layout, r.strength as strength
ORDER BY CASE r.strength WHEN 'strong' THEN 1 WHEN 'moderate' THEN 2 ELSE 3 END

What layouts work for ITSM domain?

MATCH (d:Domain {slug: 'itsm'})-[:REQUIRES_TASK]->(t:ReasoningTask)
MATCH (l:Layout)-[:SUPPORTS_TASK]->(t)
RETURN DISTINCT l.name as layout, collect(DISTINCT t.name) as supportedTasks

What fails if I use Dagre with cyclic data?

MATCH (l:Layout {name: 'Dagre'})-[:INCOMPATIBLE_WITH]->(p:GraphPattern {topology: 'cyclic'})
MATCH (l)-[:CAN_CAUSE]->(f:FailureMode)
RETURN f.name, f.symptom, f.mitigations

Full recommendation path: Domain → Pattern → Layout

MATCH (d:Domain {slug: 'itsm'})-[:HAS_PATTERN]->(p:GraphPattern)
MATCH (l:Layout)-[:WORKS_WITH]->(p)
RETURN d.name as domain, p.name as pattern, collect(DISTINCT l.name) as layouts

Project Structure

graphmaster/
├── src/
│   ├── types/
│   │   ├── nodes.ts        # TypeScript types + Zod schemas for all node types
│   │   ├── relationships.ts # Relationship types and metadata
│   │   └── index.ts
│   ├── data/
│   │   ├── domains.json    # Domain seed data
│   │   ├── layouts.json    # Layout seed data (from Cytoscape.js research)
│   │   ├── reasoning-tasks.json
│   │   ├── graph-patterns.json
│   │   ├── constraints.json
│   │   ├── failure-modes.json
│   │   └── relationships.json # All relationships between nodes
│   └── scripts/
│       ├── db.ts           # Neo4j connection utilities
│       ├── ingest.ts       # Main ingestion script
│       └── queries.ts      # Sample query demonstrations
├── docs/
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Data Sources

The layout taxonomy is derived from Cytoscape.js documentation and demos, mapped to:

• Formal graph theory concepts
• Cognitive affordances (what reasoning each layout enables)
• Domain applicability
• Constraint requirements

Key Design Decisions

1. Idempotent Ingestion: Uses MERGE exclusively—safe to re-run anytime
2. Zod Validation: All JSON data is validated at load time against TypeScript types
3. No APOC: Pure Cypher, works with any Neo4j 5+ deployment
4. Relationship Properties: Supports metadata like strength on SUPPORTS_TASK edges
5. Extensible: Add new domains, layouts, or patterns by editing JSON files

Extending Graphmaster

Add a New Domain

1. Add entry to src/data/domains.json
2. Add relationships in src/data/relationships.json
3. Run npm run ingest

Add a New Layout

1. Add entry to src/data/layouts.json following the LayoutSchema
2. Add SUPPORTS_TASK, WORKS_WITH, and other relationships
3. Run npm run ingest

Scripts

Command	Description
./setup.sh	Full setup (start Neo4j + seed data)
npm run neo4j:start	Start Neo4j
npm run neo4j:stop	Stop Neo4j
npm run neo4j:clean	Stop Neo4j and delete all data
npm run neo4j:shell	Open Cypher CLI
npm run neo4j:logs	View Neo4j logs
npm run ingest	Load/reload data into Neo4j
npm run queries	Run sample queries
npm run build	Compile TypeScript

License

MIT

Contributing

This is a portfolio project demonstrating:

• Domain-driven graph modeling
• Idempotent ETL patterns
• TypeScript + Neo4j integration
• Schema-as-code principles

Contributions welcome!