---
icon: CubeIcon
---

import { Callout, Steps, Tabs } from 'nextra/components'

# KGC-4D Overview

Welcome to **KGC 4D** (Knowledge Graph Composition in 4 Dimensions) - a revolutionary approach to knowledge graph construction combining RDF, event sourcing, and hyperdimensional reasoning.

<Callout type="info">
**Production Ready**: 250/250 tests passing ✓ | OTEL validated 100/100 ✓ | 0 high-risk failure modes ✓
</Callout>

## What is KGC-4D?

KGC 4D combines three powerful concepts:

1. **RDF (Resource Description Framework)**: Represent knowledge as simple subject-predicate-object facts called "quads"
2. **Hyperdimensional Information Theory (HDIT)**: Mathematical framework treating knowledge as multidimensional vectors
3. **Event Sourcing**: Complete history of all state changes with time-travel capabilities

**Result**: A knowledge graph that you can query in the past, understand semantically, and reason about across multiple dimensions.

## The Four Dimensions

| Dimension | Explanation | Type |
|-----------|-------------|------|
| **Observable State (O)** | Current RDF triples in the Universe graph | $\mathcal{O} \in \text{RDF}$ |
| **Nanosecond Time (t_ns)** | BigInt timestamps with monotonic ordering | $t_{ns} \in \mathbb{N}$ |
| **Vector Causality (V)** | Logical clocks tracking distributed events | $\vec{V} \in \mathbb{Z}^n$ |
| **Git References (G)** | Content-addressed snapshots with BLAKE3 hashing | $G \in \text{SHA256}$ |

<Callout type="warning">
**Mathematical Foundation**: KGC-4D operates in a 4-dimensional space where each dimension provides unique queryability and reasoning capabilities.
</Callout>

### State Space Definition

The complete state of a knowledge graph at any point is defined as:

```math
S(t) = \langle O, t_{ns}, \vec{V}, G \rangle
```

Where:
- $O$ represents the observable RDF quads
- $t_{ns}$ provides total ordering via nanosecond timestamps
- $\vec{V}$ captures distributed causality
- $G$ references immutable snapshots

## Key Features

### Complete History
- **Never lose information** - Event log is immutable
- **Audit trail built-in** - Every change is recorded
- **Non-repudiation** - Who did what, when?

### Time-Travel Queries
- "What was the state on January 1st?" ✓
- "How did this knowledge evolve?" ✓
- "What changed between these dates?" ✓

### Semantic Reasoning
- Understand relationships across domains
- Compose knowledge from multiple sources
- 74 application patterns documented

## Quick Start

<Steps>

### Install the package

<Tabs items={['npm', 'pnpm', 'yarn']}>
<Tabs.Tab>
```bash
npm install @unrdf/core
```
</Tabs.Tab>
<Tabs.Tab>
```bash
pnpm add @unrdf/core
```
</Tabs.Tab>
<Tabs.Tab>
```bash
yarn add @unrdf/core
```
</Tabs.Tab>
</Tabs>

### Create a store

```javascript
import { createStore, dataFactory } from '@unrdf/core';

const store = createStore();
```

### Add knowledge

```javascript
const { quad, namedNode, literal } = dataFactory;

store.add(quad(
  namedNode('http://example.org/alice'),
  namedNode('http://xmlns.com/foaf/0.1/name'),
  literal('Alice')
));
```

### Query back

```javascript
const results = store.match(
  namedNode('http://example.org/alice'),
  null,
  null
);

for (const quad of results) {
  console.log(quad.object.value); // "Alice"
}
```

</Steps>

## Performance Characteristics

| Workload | Latency | Memory | Status |
|----------|---------|--------|--------|
| Under 1K operations | Under 50ms | Under 10MB | ✅ Safe |
| 1K-10K operations | 1-5s | 10-100MB | ⚠️ Monitor |
| Over 10K operations | 10-50s | 100MB-1GB | ❌ Optimize first |

<Callout type="warning">
For production workloads exceeding 10K operations, consider batch processing or streaming approaches.
</Callout>

## Documentation Structure

Our documentation follows the [Diátaxis](https://diataxis.fr/) framework:

<Tabs items={['Tutorials', 'How-To Guides', 'Reference', 'Explanations']}>
<Tabs.Tab>
**Learning-Oriented** - Learn by doing with step-by-step guides

- Getting Started with KGC-4D
- Working with Events
- Temporal Snapshots
- Time-Travel Debugging
</Tabs.Tab>
<Tabs.Tab>
**Task-Oriented** - Solve specific problems with practical guides

- Time Travel: Reconstruct state at any point
- Verification: Cryptographic snapshot validation
- Querying: SPARQL and JavaScript APIs
- Git Integration: Store snapshots
- Isomorphic Deployment: Node.js and Browser
</Tabs.Tab>
<Tabs.Tab>
**Information-Oriented** - Complete API and architecture documentation

- API Reference
- Architecture Overview
- Poka-Yoke Guards (24 mistake-proofing mechanisms)
- Constants and URIs
</Tabs.Tab>
<Tabs.Tab>
**Understanding-Oriented** - Deep dives into theory and principles

- [Why 4 Dimensions?](/concepts/kgc-4d/four-dimensions)
- [Causality and Vector Clocks](/concepts/kgc-4d/mathematics)
- Temporal Reconstruction
- Git as Immutable History
- [Event Sourcing Architecture](/concepts/kgc-4d/event-sourcing)
</Tabs.Tab>
</Tabs>

## Next Steps

<Callout>
Choose your learning path:

- **I want to build** → Start with [Getting Started](/guides/getting-started)
- **I want to understand** → Read [Four Dimensions](/concepts/kgc-4d/four-dimensions)
- **I need to solve a problem** → Browse [How-To Guides](/guides)
- **I want mathematical details** → See [Mathematical Foundations](/concepts/kgc-4d/mathematics)
</Callout>