Key Concepts
Core concepts in Arke -- entities, content-addressed versioning, relationships, collections, and permissions.
Entities
Everything in Arke is an entity. Files, folders, users, collections, agents -- they all share the same base structure called Eidos. An entity is a versioned JSON manifest stored in content-addressed storage.
Each entity has:
- A persistent ID (ULID) that never changes
- A type (file, folder, collection, user, agent, etc.)
- Properties (type-specific metadata)
- Relationships (connections to other entities)
- A version chain linking back to all previous versions
Content-Addressed Versioning
Every version of an entity is stored as an immutable manifest in KV, keyed by its content hash (CID). The entity's ID resolves to its latest version via a tip pointer stored in a Durable Object.
Entity ID → Durable Object (tip) → CID → KV Manifest (immutable)When you update an entity, a new manifest is created with a prev link pointing to the previous version's CID. The tip pointer is atomically swapped to the new CID. The old version is never modified or deleted.
This gives you:
- Immutable history -- every version is permanent
- Conflict detection -- updates require Compare-And-Swap (CAS) against the current tip
- Integrity -- content hashes guarantee data hasn't been tampered with
Compare-And-Swap (CAS)
To update an entity, you must provide the CID you expect to be the current tip. If someone else updated the entity since you last read it, the CIDs won't match and you'll get a 409 Conflict error. This prevents lost updates in concurrent environments.
Relationships
Entities connect to each other through relationships. A relationship has:
- A predicate (the type of connection, e.g.
contains,references,parent) - A peer (the target entity ID)
- Optional metadata (key-value properties on the relationship itself)
Relationships are stored inside the entity manifest, so they're versioned along with everything else.
Collections
A collection is a permission boundary. Every entity belongs to at least one collection, and the collection determines who can view, edit, or manage its contents.
Collections have roles (owner, admin, editor, viewer) assigned to users. A user's role in a collection determines what actions they can take on entities within it.
Entity Types
| Type | Description |
|---|---|
collection | Permission container with role-based access |
folder | Hierarchical container within a collection |
file | Uploaded file with binary content and metadata |
user | Human account on the network |
agent | External AI service that processes entities |
group | Grouping of users/agents for permission management |
chunk | Text fragment for RAG and semantic search |
Networks
Arke has two networks:
- Main network -- Production data. Standard 26-character ULIDs.
- Test network -- Isolated test data. IDs are prefixed with
II(impossible in real ULIDs), routing to separate storage buckets.
Both networks run on the same infrastructure, but test data is fully isolated.