---
title: Architecture
description: UNRDF v5 system architecture and design
---

# Architecture

UNRDF v5 is a modular RDF knowledge graph platform built on three core principles:

1. **Runtime Type Safety** (Zod > TypeScript)
2. **Stream-First Processing** (Transform Streams)
3. **Oxigraph Foundation** (WASM-powered performance)

---

## System Overview

```
┌─────────────────────────────────────────────────┐
│             Application Layer                    │
│  (@unrdf/hooks, @unrdf/cli)                      │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│          Processing Layer                        │
│  (@unrdf/streaming, @unrdf/federation,          │
│   @unrdf/knowledge-engine)                       │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│            Core Layer                            │
│  (@unrdf/core - Store, Validation, Data)        │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│         Foundation Layer                         │
│  (@unrdf/oxigraph - WASM Triple Store)           │
└──────────────────────────────────────────────────┘
```

---

## Package Architecture

### Core Packages (@unrdf/core)
**Purpose**: Foundational RDF operations
**Key Components**:
- `createStore()` - RDF store factory
- `dataFactory` - RDF term creation
- `QuadSchema` - Zod validation

**Dependencies**: @unrdf/oxigraph, zod
**Size**: ~50KB (minified)

---

### Oxigraph Bindings (@unrdf/oxigraph)
**Purpose**: Low-level WASM triple store
**Key Components**:
- Oxigraph WASM bindings
- Memory-efficient quad storage
- SPARQL 1.1 query engine

**Dependencies**: None (pure WASM)
**Size**: ~2.5MB (WASM binary)

---

### React Hooks (@unrdf/hooks)
**Purpose**: React integration
**Key Components**:
- `useStore()` - Context-based store access
- `useQuery()` - SPARQL query hooks
- `useReasoning()` - OWL-RL inference

**Dependencies**: @unrdf/core, react
**Size**: ~15KB

---

### Streaming (@unrdf/streaming)
**Purpose**: Large dataset processing
**Key Components**:
- `N3Parser` - Transform stream
- `QuadTransform` - Mapping/filtering

**Dependencies**: @unrdf/core, n3
**Size**: ~80KB

---

## Design Patterns

### 1. MJS + JSDoc + Zod Paradigm

**Why no TypeScript in source?**

- **Runtime Safety**: Zod validates at runtime, TypeScript only at compile-time
- **Developer Experience**: JSDoc provides IDE hints without build step
- **Zero Compilation**: Direct Node.js execution

**Example**:

```javascript
// ❌ TypeScript approach
export function createStore(): Store { ... }

// ✅ UNRDF approach
/**
 * Create an RDF store
 * @returns {Store} Store instance
 */
export function createStore() {
  return StoreSchema.parse(oxigraphStore);
}

export const StoreSchema = z.object({
  add: z.function(),
  size: z.number(),
});
```

---

### 2. Data Factory Pattern

Centralized term creation prevents invalid RDF:

```javascript
// ✅ Valid
const node = dataFactory.namedNode('http://example.org');

// ❌ Invalid (caught by Zod)
const node = { value: 'not-an-iri' }; // Runtime error
```

---

### 3. Stream Processing

Transform streams for memory efficiency:

```javascript
import { N3Parser } from '@unrdf/streaming';

readStream
  .pipe(new N3Parser())
  .pipe(new QuadTransform(/* ... */))
  .pipe(writeStream);
```

---

## Data Flow

### Write Path

```
User Code
  ↓
dataFactory.quad()
  ↓
QuadSchema.parse() [Zod validation]
  ↓
store.add()
  ↓
Oxigraph WASM
  ↓
In-memory storage
```

### Read Path

```
store.match(s, p, o)
  ↓
Oxigraph WASM query
  ↓
Iterator<Quad>
  ↓
User Code
```

---

## Performance Characteristics

| Operation | Time Complexity | Notes |
|-----------|----------------|-------|
| `store.add()` | O(1) amortized | Hash-based insertion |
| `store.match()` | O(log n) | B-tree index lookup |
| `store.size` | O(1) | Cached count |
| SPARQL query | O(n × m) | n=triples, m=patterns |

---

## Memory Model

### Store Memory

- **Quads**: ~120 bytes/quad (average)
- **Indexes**: 4 indexes (SPOG, POGS, OSPG, GSPO)
- **WASM Heap**: 1GB max (configurable)

### Garbage Collection

- **Blank nodes**: Reference-counted
- **Literals**: Interned (deduplicated)
- **Named nodes**: IRI interning

---

## Extension Points

### Custom Reasoners

```javascript
import { Reasoner } from '@unrdf/knowledge-engine';

class MyReasoner extends Reasoner {
  infer(store) {
    // Custom inference logic
  }
}
```

### Custom Parsers

```javascript
import { Transform } from 'node:stream';

class MyParser extends Transform {
  _transform(chunk, encoding, callback) {
    // Parse custom format → quads
  }
}
```

---

## Related

- [Concepts: RDF Fundamentals](/concepts/rdf-fundamentals)
- [Concepts: Validation](/concepts/validation)
- [API Reference](/api)

---

## References

- [Oxigraph Documentation](https://github.com/oxigraph/oxigraph)
- [RDF 1.1 Specification](https://www.w3.org/TR/rdf11-concepts/)
- [Zod Documentation](https://zod.dev)