# codejunkie99/graph-engineering architecture

> Architecture diagram of the GitHub repository codejunkie99/graph-engineering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codejunkie99/graph-engineering
- Repository: https://github.com/codejunkie99/graph-engineering

## Overview

#### Purpose and Distribution

This repository is an agent-consumable “Graph Engineering” skill, not an executable application. It teaches and guides two connected practices: knowledge-graph construction and agent task-graph design. The source skill is `graph-engineering/SKILL.md`; the distributable artifact is `dist/graph-engineering.skill`.

Primary installation copies the skill directory into a skill-compatible agent harness. The expected entry interaction is a natural-language request to build a knowledge graph or teach graph engineering.

#### Skill Orchestrator

`graph-engineering/SKILL.md` is the central control document. It defines the agent’s operating modes, likely including build guidance and interactive teaching, and directs the agent through the knowledge-graph pipeline and task-graph principles.

`WORKFLOWS.md` provides alternate prompt-level entry points: an end-to-end tutor workflow plus focused commands that can be chained across a build. This is the user-facing orchestration layer for environments that do not invoke the skill directly.

#### Knowledge-Graph Pipeline

The core production model is a nine-stage, ordered pipeline:

1. scope
2. representation
3. ontology
4. entity extraction
5. relation extraction
6. event modeling/extraction
7. quality gate
8. fusion
9. LLM-facing serving

The key boundary is “model before extraction”: scope, representation, and ontology establish constraints before source facts are produced. Quality gates validate intermediate outputs; fusion resolves and reconciles records before graph storage or retrieval serving.

The conceptual pipeline is defined by `graph-engineering/SKILL.md` and decomposed into reusable workflow prompts in `WORKFLOWS.md`.

#### Domain Modeling and Extraction

Ontology and representation design are the schema boundary between an unstructured domain and graph data. `graph-engineering/references/modeling.md` supplies the modeling guidance, while `graph-engineering/references/extraction.md` covers deriving entities, relations, and likely source-grounded facts.

Extraction is treated as a staged transformation rather than direct triple generation: entities, relations, and events are separate concerns. This makes provenance, temporal context, validation, and later entity resolution possible.

#### Fusion and LLM Serving

Fusion is a required consolidation phase between extraction and storage/serving. It resolves duplicate or conflicting entities and facts, preserving graph quality rather than allowing raw extracted claims to become canonical graph records.

`graph-engineering/references/fusion-and-llm.md` defines the integration boundary with GraphRAG and LLM applications: the graph is a structured memory/retrieval substrate, not merely a collection of extracted triples.

#### Task-Graph Design

The second architectural half models how AI-agent work executes. `graph-engineering/references/task-graphs.md` defines task nodes as jobs and edges as actual execution dependencies.

The central execution pattern is: split independent work, run workers in parallel, verify outputs in separate contexts, then merge through a single accountable owner. This distinguishes genuine data/control dependencies from “fake edges” that add coordination without transferring work.

A stop rule prevents unnecessary multi-agent decomposition for sequential work, and a human gate is placed at costly-to-reverse decisions.

#### Reference Base and External Inputs

The repository packages distilled instructional material rather than runtime integrations. The reference corpus is organized across `graph-engineering/references/curriculum.md`, `graph-engineering/references/modeling.md`, `graph-engineering/references/extraction.md`, `graph-engineering/references/fusion-and-llm.md`, and `graph-engineering/references/task-graphs.md`.

Its external intellectual sources are Southeast University’s Knowledge Graph course, GraphRAG/LLM practices, and published multi-agent research from Google DeepMind, MIT, and Anthropic. No database, cloud service, web server, or application runtime is present in this repository.

Main entry points: [`graph-engineering/SKILL.md`](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md) (Skill orchestrator), [`graph-engineering/references/extraction.md`](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/extraction.md) (Extraction guidance), [`graph-engineering/references/modeling.md`](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/modeling.md) (Modeling guidance), [`graph-engineering/references/fusion-and-llm.md`](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/fusion-and-llm.md) (Fusion and LLM guidance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Distribution"]
  node_skill["Skill orchestrator<br/>skill document<br/>[SKILL.md]"]
  node_workflows["Workflow prompts<br/>prompt workflows<br/>[WORKFLOWS.md]"]
  node_artifact["Distributable skill<br/>package artifact"]
end

subgraph group_knowledge["Knowledge-Graph Guidance"]
  node_scope["Scope<br/>pipeline stage<br/>[SKILL.md]"]
  node_representation["Representation<br/>pipeline stage<br/>[SKILL.md]"]
  node_ontology["Ontology<br/>schema stage<br/>[SKILL.md]"]
  node_entities["Entity extraction<br/>extraction stage<br/>[SKILL.md]"]
  node_relations["Relation extraction<br/>extraction stage<br/>[SKILL.md]"]
  node_events["Event modeling and extraction<br/>extraction stage<br/>[SKILL.md]"]
  node_quality["Quality gate<br/>validation stage<br/>[SKILL.md]"]
  node_fusion["Fusion<br/>consolidation stage<br/>[SKILL.md]"]
  node_serving["LLM-facing serving<br/>retrieval stage<br/>[SKILL.md]"]
  node_modeling_ref["Modeling guidance<br/>reference<br/>[modeling.md]"]
  node_extraction_ref["Extraction guidance<br/>reference<br/>[extraction.md]"]
  node_fusion_ref["Fusion and LLM guidance<br/>reference<br/>[fusion-and-llm.md]"]
end

subgraph group_taskgraphs["Task-Graph Guidance"]
  node_task_ref["Task-graph guidance<br/>reference<br/>[task-graphs.md]"]
  node_parallel["Parallel workers<br/>execution pattern<br/>[task-graphs.md]"]
  node_verify["Separate verification<br/>execution pattern<br/>[task-graphs.md]"]
  node_merge["Accountable merge owner<br/>execution pattern<br/>[task-graphs.md]"]
  node_human_gate["Human decision gate<br/>control point<br/>[task-graphs.md]"]
end

node_skill -->|"offers alternate entry points"| node_workflows
node_skill -->|"packaged as"| node_artifact
node_skill -->|"starts pipeline"| node_scope
node_scope -->|"constrains"| node_representation
node_representation -->|"defines"| node_ontology
node_ontology -->|"models before extraction"| node_entities
node_entities -->|"feeds"| node_relations
node_relations -->|"feeds"| node_events
node_events -->|"validated by"| node_quality
node_quality -->|"approved claims"| node_fusion
node_fusion -->|"canonical graph for"| node_serving
node_modeling_ref -.->|"guides"| node_representation
node_modeling_ref -.->|"guides"| node_ontology
node_extraction_ref -.->|"guides"| node_entities
node_extraction_ref -.->|"guides"| node_relations
node_extraction_ref -.->|"guides"| node_events
node_fusion_ref -.->|"guides"| node_fusion
node_fusion_ref -.->|"defines integration"| node_serving
node_skill -->|"teaches"| node_task_ref
node_parallel -->|"outputs checked by"| node_verify
node_verify -->|"verified work to"| node_merge
node_human_gate -->|"approves irreversible decisions"| node_merge

click node_skill "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_workflows "https://github.com/codejunkie99/graph-engineering/blob/master/WORKFLOWS.md"
click node_artifact "https://github.com/codejunkie99/graph-engineering/blob/master/dist/graph-engineering.skill"
click node_scope "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_representation "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_ontology "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_entities "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_relations "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_events "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_quality "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_fusion "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_serving "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md"
click node_modeling_ref "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/modeling.md"
click node_extraction_ref "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/extraction.md"
click node_fusion_ref "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/fusion-and-llm.md"
click node_task_ref "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md"
click node_parallel "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md"
click node_verify "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md"
click node_merge "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md"
click node_human_gate "https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_workflows,node_artifact toneBlue
class node_scope,node_representation,node_ontology,node_entities,node_relations,node_events,node_quality,node_fusion,node_serving,node_modeling_ref,node_extraction_ref,node_fusion_ref toneAmber
class node_task_ref,node_parallel,node_verify,node_merge,node_human_gate toneMint
```

## Components

### Distribution

- [Skill orchestrator](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): skill document · Defines operating modes and the ordered graph-engineering process. · `graph-engineering/SKILL.md`
- [Workflow prompts](https://github.com/codejunkie99/graph-engineering/blob/master/WORKFLOWS.md): prompt workflows · Provides tutor and focused chained entry points. · `WORKFLOWS.md`
- [Distributable skill](https://github.com/codejunkie99/graph-engineering/blob/master/dist/graph-engineering.skill): package artifact · Installable agent-harness skill package. · `dist/graph-engineering.skill`

### Knowledge-Graph Guidance

- [Scope](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): pipeline stage · `graph-engineering/SKILL.md`
- [Representation](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): pipeline stage · `graph-engineering/SKILL.md`
- [Ontology](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): schema stage · Defines graph concepts and constraints before fact extraction. · `graph-engineering/SKILL.md`
- [Entity extraction](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): extraction stage · `graph-engineering/SKILL.md`
- [Relation extraction](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): extraction stage · `graph-engineering/SKILL.md`
- [Event modeling and extraction](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): extraction stage · `graph-engineering/SKILL.md`
- [Quality gate](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): validation stage · Validates intermediate extracted outputs. · `graph-engineering/SKILL.md`
- [Fusion](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): consolidation stage · Reconciles duplicate and conflicting claims before serving. · `graph-engineering/SKILL.md`
- [LLM-facing serving](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/SKILL.md): retrieval stage · Exposes the graph as structured memory and retrieval context. · `graph-engineering/SKILL.md`
- [Modeling guidance](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/modeling.md): reference · `graph-engineering/references/modeling.md`
- [Extraction guidance](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/extraction.md): reference · `graph-engineering/references/extraction.md`
- [Fusion and LLM guidance](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/fusion-and-llm.md): reference · `graph-engineering/references/fusion-and-llm.md`

### Task-Graph Guidance

- [Task-graph guidance](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md): reference · `graph-engineering/references/task-graphs.md`
- [Parallel workers](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md): execution pattern · Independent jobs run concurrently. · `graph-engineering/references/task-graphs.md`
- [Separate verification](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md): execution pattern · Outputs are checked in separate contexts. · `graph-engineering/references/task-graphs.md`
- [Accountable merge owner](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md): execution pattern · One owner merges verified work. · `graph-engineering/references/task-graphs.md`
- [Human decision gate](https://github.com/codejunkie99/graph-engineering/blob/master/graph-engineering/references/task-graphs.md): control point · Used for costly-to-reverse decisions. · `graph-engineering/references/task-graphs.md`

## Connections

- Skill orchestrator → Workflow prompts: offers alternate entry points
- Skill orchestrator → Distributable skill: packaged as
- Skill orchestrator → Scope: starts pipeline
- Scope → Representation: constrains
- Representation → Ontology: defines
- Ontology → Entity extraction: models before extraction
- Entity extraction → Relation extraction: feeds
- Relation extraction → Event modeling and extraction: feeds
- Event modeling and extraction → Quality gate: validated by
- Quality gate → Fusion: approved claims
- Fusion → LLM-facing serving: canonical graph for
- Modeling guidance → Representation: guides
- Modeling guidance → Ontology: guides
- Extraction guidance → Entity extraction: guides
- Extraction guidance → Relation extraction: guides
- Extraction guidance → Event modeling and extraction: guides
- Fusion and LLM guidance → Fusion: guides
- Fusion and LLM guidance → LLM-facing serving: defines integration
- Skill orchestrator → Task-graph guidance: teaches
- Parallel workers → Separate verification: outputs checked by
- Separate verification → Accountable merge owner: verified work to
- Human decision gate → Accountable merge owner: approves irreversible decisions