| title | Explanation |
|---|---|
| description | Concept-oriented documentation explaining how VisionClaw is built and why — architecture, domain model, the knowledge and ontology pipeline, platform surfaces, and the security model. |
VisionClaw Docs · Explanation
Understanding-oriented documentation. These pages explain how the system is shaped and why — the architecture, the domain boundaries, the knowledge pipeline, and the trade-offs behind each decision. They are the Diátaxis explanation tier: read them to build a mental model, not to follow steps. For step-by-step learning see the tutorials; for task recipes see the how-to guides; for exhaustive detail see the reference.
Every page back-links to the Architecture Decision Records that govern it.
How the running system is layered, from the CUDA force engine up to the browser and XR clients.
| Page | What it explains |
|---|---|
| System Overview | End-to-end tour — how a Logseq note becomes a GPU-laid-out node in the browser and on Quest 3. The 10,000-foot map. |
| Backend Architecture | The hexagonal Rust core — 8 workspace crates, 9 ports / 12 adapters, 44 hexser handlers (19 directive + 25 query), no CQRS bus. |
| Actor Hierarchy | The 45 Actix actors (19 service + 16 GPU + 10 WebSocket session) and how messages flow between supervisors. |
| Client Architecture | The TypeScript/React client (465 files, 16 feature modules), WebGL/WebGPU rendering, and the binary position pipeline. |
| Physics GPU Engine | The 82 CUDA kernels across 9 source files; 55× speedup (246 ms CPU → 4.5 ms GPU at 100K nodes); force-directed layout on the GPU. |
| Agent–Physics Bridge | Deep-dive — how agent nodes enter the same force graph as knowledge and ontology nodes. |
| XR Architecture | Quest 3 / WebXR plus the Godot presence layer and the visionclaw-xr-presence crate. |
| Deployment Topology | Container and network layout — API :4000, nginx :3001, Solid pod :8484, legacy MCP TCP :9500. |
| Technology Choices | Why Rust + Actix + CUDA + Oxigraph + React, and the trade-offs behind each pick. |
The strategic domain-driven design model — where the boundaries are drawn and why.
| Page | What it explains |
|---|---|
| Bounded Contexts | The bounded-context map and the reasoning behind each split. |
| DDD Bounded Contexts | Strategic DDD deep-dive — context boundaries, relationships, and ubiquitous language. |
| DDD Semantic Pipeline | The semantic ingestion and parsing context. |
| DDD Insight Migration Context | How insights are promoted from transient analysis into the persistent graph. |
| DDD Identity Contexts | Identity, pod, and Nostr identity boundaries. |
| DDD Enterprise Contexts | Enterprise-facing contexts and their integration seams. |
| DDD Contributor Enablement Context | The contributor-support and enablement context. |
The full per-context catalogue lives in the DDD documents.
How notes become a reasoned, governed knowledge graph and how learnt insight flows back in.
| Page | What it explains |
|---|---|
| Ontology Pipeline | Note → OWL — Whelk-rs OWL 2 EL reasoning, SHACL-lite and JSON-LD validation, PROV-O provenance (PRD-022), and the 7 MCP ontology tools. |
| Feature Engineering Pipeline | How graph features are derived to drive layout and clustering. |
| Insight Migration Loop | How agent-generated insight is migrated back into the persistent graph. |
| RuVector Integration | RuVector / AgentDB memory — MiniLM-L6-v2 384-dim embeddings and HNSW semantic search. |
VisionClaw as a coordination platform, and how it composes with the agentbox subsystem.
| Page | What it explains |
|---|---|
| VisionFlow Coordination Platform | VisionFlow as a multi-agent coordination surface over the graph. |
| VisionFlow Wardley Map | A strategic Wardley map of the platform's value chain and evolution. |
| Subsystems | How VisionClaw composes with the agentbox subsystem — what each owns and where the seam sits. |
| Agent Control Surface | How agents are observed and steered through the live graph. |
| Ecosystem Convergence | The convergence of the knowledge-graph, agent, and pod ecosystems. |
| Solid Sidecar Architecture | The Solid pod sidecar (:8484) and the URN → Solid resource mapping. |
| User & Agent Pod Design | Per-user and per-agent pod design and data ownership. |
| Page | What it explains |
|---|---|
| Security Model | The authentication and authorisation model, the SETTINGS_AUTH_BYPASS caveat, and the threat surfaces. |