Core Concepts

This guide explains the core concepts of Kumiho Cloud and how they relate to the Dart SDK.

Graph-Native Architecture

Kumiho Cloud is built on a graph database (Neo4j), which means relationships between assets are first-class citizens. Unlike traditional file-based systems, Kumiho tracks:

Dependencies: What assets does this asset depend on?
Lineage: What was this asset created from?
Usage: Where is this asset used?

┌───────────────────────────────────────────────────────┐
│                         PROJECT                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │                        SPACE                    │  │
│  │  ┌─────────┐      ┌─────────┐     ┌─────────┐   │  │
│  │  │  ITEM   │────▶│  ITEM   │────▶│  ITEM   │   │  │
│  │  └────┬────┘      └────┬────┘     └────┬────┘   │  │
│  │       │                │               │        │  │
│  │  ┌────▼────┐      ┌────▼────┐     ┌────▼────┐   │  │
│  │  │REVISION │      │REVISION │     │REVISION │   │  │
│  │  │   v1    │      │   v1    │     │   v1    │   │  │
│  │  └────┬────┘      └────┬────┘     └────┬────┘   │  │
│  │       │                │               │        │  │
│  │  ┌────▼────┐      ┌────▼────┐     ┌────▼────┐   │  │
│  │  │ARTIFACT │      │ARTIFACT │     │ARTIFACT │   │  │
│  │  └─────────┘      └─────────┘     └─────────┘   │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘

Entity Hierarchy

Project

A Project is the top-level container representing a production, show, or workspace. Each project is isolated within a tenant’s graph database.

final project = await client.createProject(
  'sci-fi-short',
  description: 'Sci-fi short film VFX assets',
);

Key attributes:

name: URL-safe identifier (used in Kref URIs)
description: Human-readable description
kref: Reference URI (kref://sci-fi-short)

Space

A Space organizes assets within a project. Common groupings include:

By type: characters, environments, props
By episode: ep01, ep02
By department: modeling, animation, lighting

final space = await client.createSpace('/sci-fi-short', 'characters');

Key attributes:

name: URL-safe identifier
path: Full path in the hierarchy (e.g., /sci-fi-short/characters)
metadata: Custom key-value metadata

Item

An Item represents a single creative asset or AI artifact. Items have a kind that indicates what type of asset they are.

final item = await client.createItem(
  '/sci-fi-short/characters',
  'hero-robot',
  'model',
);

Common item kinds:

model: 3D models
texture: Textures and materials
animation: Animation data
rig: Character rigs
composite: Compositing setups
ai_model: Trained AI models
dataset: Training datasets
prompt: AI prompts

Key attributes:

name: URL-safe identifier
kind: Category of the asset
kref: Reference URI (kref://sci-fi-short/characters/hero-robot.model)

Revision

A Revision represents a specific iteration of an item. Revisions are immutable once published.

// Create a revision
final revision = await client.createRevision(item.kref);

// Create a revision with metadata
final revision = await client.createRevision(
  item.kref,
  metadata: {'artist': 'john', 'status': 'wip'},
);

Key attributes:

revisionNumber: Sequential version number
metadata: Custom key-value metadata
tags: Applied tags (e.g., latest, published, approved)
kref: Reference URI (kref://sci-fi-short/characters/hero-robot.model?r=1)

Artifact

An Artifact is a file reference attached to a revision. Kumiho follows a BYO-storage philosophy — files stay on your storage, only paths are tracked.

await client.createArtifact(
  revision.kref,
  'mesh',
  '/mnt/assets/hero-robot.fbx',
);

await client.createArtifact(
  revision.kref,
  'textures',
  's3://bucket/hero-robot/textures.tar',
);

Key attributes:

name: Artifact identifier
location: File path or URI (file://, s3://, smb://, etc.)
kref: Reference URI

Bundle

A Bundle groups related items or revisions together, useful for releases or delivery packages.

final bundle = await client.createBundle(
  '/sci-fi-short',
  'release-v1',
  metadata: {'channel': 'beta'},
);

await client.addBundleMember(bundle.kref, item.kref);
await client.addBundleMember(bundle.kref, rigRevision.kref);

Kref URIs

Every object in Kumiho is addressable by a URI-style Kref (Kumiho Reference):

Entity	Format	Example
Project	`kref://project`	`kref://sci-fi-short`
Space	`kref://project/space`	`kref://sci-fi-short/characters`
Item	`kref://project/space/item.kind`	`kref://sci-fi-short/characters/hero.model`
Revision	`kref://project/space/item.kind?r=N`	`kref://sci-fi-short/characters/hero.model?r=1`
Artifact	`kref://project/space/item.kind?r=N&a=name`	`kref://sci-fi-short/characters/hero.model?r=1&a=mesh`

Edges (Relationships)

Edges represent relationships between revisions. Common edge types include:

Edge Type	Description
`DEPENDS_ON`	Asset requires another asset to function
`DERIVED_FROM`	Asset was created from another asset
`REFERENCED`	Asset references another asset
`CONTAINS`	Asset contains another asset
`CREATED_FROM`	Asset was created using another asset

// Create a dependency relationship
await client.createEdge(
  modelRevision.kref,
  textureRevision.kref,
  EdgeType.dependsOn,
);

// Analyze impact of changes
final impact = await client.analyzeImpact(textureRevision.kref);

BYO Storage Philosophy

Kumiho does not store your files. Instead, it tracks references (artifacts) to files that remain on your storage:

Local filesystems: file:///path/to/file.fbx
Network shares: smb://server/share/file.fbx
Cloud storage: s3://bucket/path/file.fbx

This approach provides:

No egress costs: Files never leave your infrastructure
Flexibility: Use any storage that works for your pipeline
Control: Keep your data on your own storage solutions

Multi-Tenant Architecture

Kumiho Cloud is a multi-tenant SaaS platform:

Each organization is a tenant
Tenants are isolated in separate Neo4j databases
Regional deployment ensures data locality
The SDK automatically discovers your tenant’s region

// SDK handles tenant discovery automatically
final client = KumihoClient(host: 'api.kumiho.io', port: 443);
final tenantInfo = await client.getTenant();
print('Connected to tenant: ${tenantInfo.name}');