Understand
Architecture
How Arke's layered architecture works -- from core storage primitives to external endpoints.
Layered System
Arke's API follows a layered architecture. Each layer builds on the one below it:
┌─────────────────────────────────────────────────────────────┐
│ Layer 4+: Type-Specific Profiles │
│ Files, folders, agents, groups, job collections │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Entities & Relationships │
│ Generic CRUD, relationship operations, version history │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Collections & Permissions │
│ Permission containers, role resolution, access control │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Users & Authentication │
│ JWT validation, API keys, user mapping │
├─────────────────────────────────────────────────────────────┤
│ Layer 0: Core Primitives │
│ KV manifests, Durable Object tips, D1 events │
└─────────────────────────────────────────────────────────────┘Storage Architecture
| Storage | Technology | Purpose |
|---|---|---|
| KV Namespaces | Cloudflare KV | Immutable manifest JSON (keyed by CID) |
| Durable Objects | Cloudflare DO (SQL-backed) | Tip pointers (entity ID to CID mapping) |
| D1 Databases | Cloudflare D1 | Tip sync for listing, events, attestation queue |
| R2 Buckets | Cloudflare R2 | Binary file storage (separate prod/test) |
| Pinecone | Service binding | Vector embeddings for semantic search |
| Neo4j | Service binding (GraphDB worker) | Relationship graph for traversal queries |
ID Resolution
When you request an entity by ID, the system resolves it through this chain:
Entity ID
↓
Durable Object (tip pointer)
↓
Manifest CID
↓
KV (immutable JSON manifest)The Durable Object provides atomic read/write operations for the mutable tip, while KV provides fast, globally distributed reads for immutable manifests.
External Services
Arke integrates with external services through Cloudflare service bindings:
- Pinecone Worker -- Handles vector embedding storage and semantic similarity search
- GraphDB Worker -- Proxies requests to Neo4j for graph traversal and the Argo query engine
- Chat Agent -- Processes natural language queries against the knowledge graph
Request Flow
A typical API request flows through:
- Authentication middleware -- Validates JWT or API key, sets user context
- Route handler -- Validates request, extracts parameters
- Permission check -- Resolves user's role, checks required action
- Operation -- Executes the business logic (create, update, etc.)
- Storage -- Reads/writes manifests, updates tips, queues events
- Events -- Background tasks fire (D1 sync, index updates, attestation)