# Card Network Architecture: A Spatial Content System for the Agentic Web

**Version 1.0 | December 2024**

## Abstract

Card Network Architecture (CNA) introduces a new paradigm for content representation where phone-sized cards serve as atomic units that stack, link, and network together. Designed for both human navigation and AI agent consumption, CNA provides structured, tokenized content optimized for edge computing and low-power devices.

## 1. Introduction

### 1.1 The Problem

Modern content systems face a fundamental tension:

1. **Humans** need visual, navigable, bite-sized content
2. **AI agents** need structured, tokenized, context-efficient data
3. **Edge devices** need minimal compute and offline capability

Current solutions (documents, wikis, databases) serve one audience poorly while optimizing for another.

### 1.2 The Solution

CNA resolves this tension through **cards** -- atomic content units sized like a mobile phone screen (~250 tokens). Cards are:

- **Self-contained**: Each card has a clear purpose
- **Typed**: Seven card types enable specialized rendering and behavior
- **Connected**: Typed edges create semantic relationships
- **Efficient**: Optimized for small LLM context windows

## 2. Core Concepts

### 2.1 Cards

A card is the atomic unit of CNA. Each card contains:

- **Header**: Title and optional icon
- **Body**: Content (text, code, media, actions, choices)
- **Metadata**: Tags, timestamps, token count
- **Connectors**: Visual attachment points for edges

**Design constraints:**
- Maximum ~250 tokens (fits in 2K context windows)
- Single responsibility principle
- Human-readable in isolation

### 2.2 Card Types

| Type | Purpose | Rendering |
|------|---------|-----------|
| content | Text, markdown | Rich text display |
| action | Buttons, forms | Interactive controls |
| decision | Branch points | Choice interface |
| media | Images, video | Media player |
| data | Structured data | Table/chart |
| embed | External content | iframe/embed |
| composite | Card container | Nested cards |

### 2.3 Edges

Edges define relationships between cards. Unlike hyperlinks, edges are:

- **Typed**: Seven edge types with distinct semantics
- **Weighted**: Priority for traversal algorithms
- **Bidirectional aware**: Can query incoming or outgoing

### 2.4 Compositions

Compositions are named collections of cards and edges:

- **Stack**: Linear vertical sequence
- **Network**: Graph of linked cards
- **Tree**: Decision/navigation hierarchy
- **Embedded**: Nested card structures

## 3. AI Optimization

### 3.1 Token Efficiency

CNA cards at ~250 tokens each preserve relationships while fitting in small context windows.

### 3.2 Graph Traversal

AI agents can navigate card networks without LLM inference using typed edges.

### 3.3 Edge Computing

CNA enables AI on constrained devices with small token footprints, typed edges for graph traversal without inference, aggressive caching via immutable cards, and offline support.

## 4. Human Experience

### 4.1 Spatial Navigation

Cards arrange spatially like physical objects -- stacks, 2D networks, zoom levels.

### 4.2 Mobile-First

Card dimensions match phone screens -- swipe, tap, pinch interactions.

### 4.3 Progressive Disclosure

Start with one card, reveal connected cards as needed.

## 5. Implementation

### 5.1 Storage

Cards and edges stored in SQLite/D1, vector indexes, and CDN edge caching.

### 5.2 API

RESTful API with CRUD, graph traversal, semantic search, and x402 payment protocol.

### 5.3 Rendering

React Flow for network visualization with custom card components per type.

## 6. Use Cases

- **Documentation**: Navigable card networks replacing traditional docs
- **Knowledge Bases**: Enterprise knowledge as searchable graphs
- **Educational Content**: Courses as card compositions
- **Agent Context**: Structured context for AI agents

## 7. Knowledge Evolution

CNA v1.1 introduces contradiction, supersession, and extension edges for knowledge that changes over time, plus a suggested edge review queue for human-in-the-loop validation and quality scoring for card prioritization.

## 8. Future Work

- Real-time collaboration
- Version control for cards/edges
- AI generation of card networks from documents
- Marketplace for card compositions

## 9. Conclusion

Card Network Architecture bridges the gap between human-readable content and machine-efficient data. The agentic web needs content built for agents. CNA provides that foundation.

---

**Specification**: [cardnetwork.org](https://cardnetwork.org)
**Demo**: [demo.cardnetwork.dev](https://demo.cardnetwork.dev)
**Website**: [cardnetwork.dev](https://cardnetwork.dev)