# CodeLayers — Full Documentation

> Zero-knowledge code visualization platform. View any codebase as an interactive
> 3D dependency graph on Apple Vision Pro, iPad, iPhone, and the web.

---

## What Is CodeLayers?

CodeLayers turns codebases into interactive 3D dependency graphs. Developers use it
to understand architecture, review pull requests spatially, and navigate unfamiliar
code with AI assistance — all while maintaining complete privacy through client-side
encryption.

The platform runs on Apple Vision Pro (spatial computing with RealityKit), iPad,
iPhone, and any modern web browser (via Three.js). A Rust CLI handles all heavy
computation — parsing, graph building, encryption — on the developer's machine.
The backend only ever sees encrypted blobs.

---

## Core Principles

### Zero-Knowledge Architecture
The backend never sees plaintext code. All encryption and decryption happens
client-side. The server stores encrypted chunks and hashed metadata. Even file
paths are hashed before upload.

- **Encryption**: AES-256-GCM for all file chunks and graph data
- **Key Derivation**: PBKDF2-HMAC-SHA256 with 100,000 iterations from a 12-word BIP39 seed phrase
- **Backend Verification**: HKDF-SHA256 derived "mnemonic sync ID" verifies identity without exposing the encryption key
- **Authentication**: Apple Sign In for mobile/Vision Pro, mnemonic-based for CLI

### CLI-First Design
Heavy computation happens on the developer's machine:
- Tree-sitter parsing across 10 languages
- Dependency graph construction with centrality metrics
- Gzip compression followed by AES-256-GCM encryption
- SQLite caching for incremental updates

### Commit-Based Sync
Each git commit produces an immutable graph snapshot. Snapshots are compressed,
encrypted, and uploaded as atomic units. This enables time-travel through
codebase architecture.

---

## Getting Started

### Installation

```bash
brew install codelayers
```

### Authentication

```bash
# Generate or enter a 12-word BIP39 mnemonic
codelayers login

# Check status
codelayers status
```

The mnemonic serves dual purpose: it derives both the encryption key (for
zero-knowledge encryption) and the sync identity (for backend authentication).
Write it down — losing it means losing access to your encrypted data.

### Syncing a Repository

```bash
# One-time sync
codelayers sync /path/to/your/project

# Watch mode with live updates
codelayers watch /path/to/your/project

# Watch mode with AI agent integration
codelayers watch /path/to/your/project --agent claude
codelayers watch /path/to/your/project --agent gemini
codelayers watch /path/to/your/project --agent codex
```

### Pairing with Vision Pro

```bash
# Interactive pairing with 6-digit code verification
codelayers pair
```

Pairing uses mDNS discovery (`_codelayers-sync._tcp.local`) and ECDH key
exchange. After the initial pairing, all sync goes through the backend WebSocket —
P2P is only used for this one-time setup.

### Full CLI Reference

```bash
codelayers login                    # Authenticate with 12-word mnemonic
codelayers logout                   # Clear credentials
codelayers status                   # Show auth and encryption key status
codelayers sync <path>              # One-time sync repository to backend
codelayers sync <path> --clean      # Force re-sync from scratch
codelayers watch <path>             # Watch mode with live updates
codelayers watch <path> --agent claude  # Watch with Claude Code
codelayers watch <path> --agent gemini  # Watch with Gemini CLI
codelayers watch <path> --agent codex   # Watch with Codex
codelayers pair                     # Interactive device pairing (6-digit code)
codelayers list                     # List synced repositories
codelayers info <path>              # Show repository sync status
codelayers stop <path>              # Remove repository from sync
```

---

## 3D Visualization

### Visualization Modes

CodeLayers offers four ways to view your codebase:

1. **Solar System** — Files orbit as planets around a central star. Larger files
   have larger planets. Imports form orbital rings. Good for seeing the overall
   structure at a glance.

2. **City** — Files rendered as buildings on a grid. Height represents complexity
   or lines of code. Neighborhoods form around modules. Good for spotting
   hotspots and understanding relative scale.

3. **Tree** — Hierarchical layout following the directory tree. Parent directories
   branch into children. Good for navigating by file path.

4. **Neural** — Force-directed graph where heavily-connected files cluster
   together. Edges show actual import relationships. Good for finding tightly
   coupled modules and dependency patterns.

### Graph Metrics

Every node in the graph has computed metrics:

- **PageRank** — Measures importance based on how many files import it (and how
  important those files are). High PageRank = critical infrastructure file.
- **Betweenness Centrality** — How often a file sits on the shortest path between
  two other files. High centrality = bottleneck or bridge module.
- **Topological Depth** — Distance from the root of the dependency tree. Depth 0
  = entry point, higher depth = deeper internal implementation.

### Blast Radius Analysis

Before changing a file, you can analyze its blast radius — the full dependency
chain of everything that directly or transitively depends on it. This helps
answer "if I change this function signature, what breaks?"

The analysis returns:
- Dependency tree with depth and direction
- Node types (file, function, class)
- Lines of code per affected file
- Whether affected files have uncommitted changes

---

## AI Agent Integration

### Overview

CodeLayers integrates with AI coding agents to provide spatial awareness during
development. When running in watch mode with an agent, the AI can see and
control the 3D visualization while helping you write code.

### Supported Agents

- **Claude Code** (`--agent claude`) — Full integration with MCP server
- **Gemini CLI** (`--agent gemini`) — Full integration with MCP server
- **Codex** (`--agent codex`) — Full integration with MCP server

### MCP Server Tools

The built-in MCP server exposes these tools to the AI agent:

#### highlight_files
Highlight files in the 3D visualization. Parameters:
- `paths`: Array of file paths to highlight
- `color`: yellow, red, green, blue, purple, cyan, magenta, orange, white, pink
- `label`: Short label shown in the 3D view
- `title`: Descriptive title for the highlight set

#### focus_file
Zoom the 3D camera to center on a specific file. Parameters:
- `path`: File path to focus on
- `highlight`: Also highlight the file (default: true)

#### show_dependencies
Show import/dependency relationship lines in 3D and return dependency data.
Parameters:
- `path`: File path to analyze
- `incoming`: Show files that import this file (default: true)
- `outgoing`: Show files imported by this file (default: true)

#### get_blast_radius
Analyze downstream impact of changes. Returns dependency chain tree.
Parameters:
- `files`: Array of file paths to analyze
- `functions`: Optional specific functions to analyze
- `max_hops`: Max dependency depth (default: 5)

#### set_visualization_mode
Switch visualization mode. Parameters:
- `mode`: solar_system, city, tree, or neural

#### clear_highlights
Remove all highlights from the 3D visualization.

#### change_title
Set the chat session title.

### Session Modes

AI sessions can operate in two modes:

- **Chat Mode** — Text-only chat with the AI agent. No 3D visualization.
  Used when you just want to talk through a problem.
- **3D Mode** — Full visualization with integrated chat. The AI can see and
  manipulate the graph while helping you code.

---

## Supported Languages

CodeLayers uses tree-sitter for parsing, supporting:

| Language | What's Extracted |
|----------|-----------------|
| Rust | Functions, structs, enums, traits, impl blocks, use/mod imports |
| TypeScript | Functions, classes, interfaces, imports, exports, type aliases |
| JavaScript | Functions, classes, imports, exports, CommonJS requires |
| Python | Functions, classes, imports, decorators |
| Java | Classes, interfaces, methods, imports, annotations |
| Go | Functions, structs, interfaces, imports, methods |
| C++ | Functions, classes, namespaces, includes, templates |
| C# | Classes, interfaces, methods, using directives, namespaces |
| Ruby | Classes, modules, methods, requires |
| PHP | Classes, functions, use statements, namespaces |
| Swift | Classes, structs, enums, protocols, imports, extensions |

---

## Data Flow

### Initial Sync
1. CLI detects git repository and reads file tree
2. Tree-sitter parses each file, extracting symbols and relationships
3. Graph builder constructs dependency graph with edges for imports, calls, type references
4. Graph analyzer computes PageRank, betweenness centrality, topological depth
5. Identifiers (paths, symbols) are hashed for zero-knowledge
6. Code is chunked (64KB), compressed (gzip), encrypted (AES-256-GCM)
7. Uploaded via chunked upload protocol (handles large graphs with 5k+ nodes)
8. Locally cached in SQLite (~/.codelayers/ast_cache.db)

### Watch Mode (Incremental)
1. File system change detected (notify crate, 300ms debounce)
2. Changed file re-parsed with tree-sitter
3. SQLite cache updated with new AST
4. Affected graph portions rebuilt
5. Delta sent to backend WebSocket
6. Backend broadcasts to all connected viewers (Vision Pro, web, mobile)
7. Viewers update 3D visualization in real-time

### Viewer Loading
1. Connect to backend WebSocket
2. Fetch latest commit-based graph snapshot (encrypted + gzip compressed)
3. Decrypt with mnemonic-derived key
4. Decompress gzip
5. Layout nodes in 3D space (solar_system, city, tree, or neural algorithm)
6. Render with RealityKit (Vision Pro) or Three.js (web)

---

## Web Viewer

The web viewer at codelayers.ai provides browser-based 3D visualization:

- **Explore page** (`/explore`): Browse pre-indexed open-source projects like
  React, Kubernetes, Django, and more. No account needed.
- **Share links** (`/s/:id`): View shared visualizations. The encryption key
  is in the URL fragment (after #) and never sent to the server.
- **Explore by ID** (`/e/:id`): Direct link to a specific explore visualization.

Built with Next.js, React Three Fiber, and Three.js. All decryption happens
in the browser using the Web Crypto API.

---

## Performance

| Operation | Target |
|-----------|--------|
| Initial sync (1000 files) | 50-120 seconds |
| Incremental update (file change) | 110-340ms |
| P2P local latency | < 100ms |
| Vision Pro time to interactive | 3-8 seconds |
| API p95 latency | < 200ms |

---

## Technology Stack

### CLI (Rust)
- clap (CLI framework), tokio (async runtime)
- tree-sitter with 10 language grammars
- rusqlite for SQLite caching
- ring/RustCrypto for AES-256-GCM, PBKDF2, ECDH
- notify for file watching
- mdns-sd for P2P discovery
- tokio-tungstenite for WebSocket

### Backend (Rust)
- Axum web framework
- PostgreSQL via sqlx
- jsonwebtoken for JWT
- tokio-tungstenite for WebSocket

### Vision Pro (Swift)
- SwiftUI + RealityKit for spatial UI
- CryptoKit for decryption
- URLSession for HTTP/WebSocket
- Bonjour for mDNS discovery

### Web (TypeScript)
- Next.js 16 with App Router
- React Three Fiber + Three.js for 3D
- Zustand for state management
- Tailwind CSS

### Shared Library (Rust)
- Common crate used by CLI and Backend
- Graph node/edge type definitions
- API request/response types
- P2P message protocol types

---

## Links

- Website: https://codelayers.ai
- Web Viewer: https://codelayers.ai
- Explore Open Source: https://codelayers.ai/explore
- App Store: https://apps.apple.com/app/codelayers/id6756067177