Complete documentation for VisionFlow's enterprise-grade multi-agent knowledge graphing system.
226 documents organized using the Diátaxis Framework for maximum discoverability
- Install VisionFlow → Deploy with Docker
- Create First Graph → Launch AI agents
- Navigate in 3D → Master the interface
|
Just getting started? Start here: Then: |
Building features? Start here: Then: |
Designing systems? Start here: Then: |
Deploying to production? Start here: Then: |
Step-by-step lessons to learn by doing
| Tutorial | What You'll Learn | Time |
|---|---|---|
| Installation | Docker and native setup for all platforms | 10 min |
| First Graph | Create your first visualization with AI agents | 15 min |
| Neo4j Quick Start | Query and explore the graph database | 20 min |
Practical instructions for specific tasks
🎯 Core Features (8 guides)
| Guide | Task |
|---|---|
| Navigation Guide | 3D interface controls, camera, selection |
| Filtering Nodes | Client-side graph filtering with real-time updates |
| Intelligent Pathfinding | Graph traversal and shortest paths |
| Natural Language Queries | Ask questions in plain English |
| Semantic Forces | Physics-based meaningful layouts |
| Configuration | Environment variables and settings |
| Troubleshooting | Solve common issues |
| Extending the System | Plugin patterns and custom components |
🔐 Authentication & Security (3 guides)
| Guide | Task |
|---|---|
| Auth & User Settings | User authentication system implementation |
| Nostr Authentication | Decentralized identity with Nostr protocol |
| Settings Authentication | Secure settings API with JWT |
🤖 AI Agent System (4 guides)
| Guide | Task |
|---|---|
| Agent Orchestration | Deploy and manage 50+ concurrent AI agents |
| Orchestrating Agents | Advanced coordination patterns |
| Multi-Agent Skills | Agent capabilities and specializations |
| AI Models & Services | DeepSeek, Perplexity, RAGFlow, Z.AI integrations |
🗄️ Neo4j & Data (6 guides)
| Guide | Task |
|---|---|
| Neo4j Integration | Work with graph database operations |
| Neo4j Implementation Roadmap | Migration planning and timeline |
| Neo4j Migration | Step-by-step migration process |
| Local File Sync Strategy | File synchronization patterns |
| GitHub Pagination Fix | Handle large GitHub API responses |
| Pipeline Admin API | Control GitHub sync pipelines |
🦉 Ontology & Reasoning (4 guides)
| Guide | Task |
|---|---|
| Ontology Parser | Parse and validate OWL ontologies |
| Ontology Reasoning Integration | Enable semantic inference with Whelk |
| Ontology Storage Guide | Persist ontologies in Neo4j |
| Ontology Semantic Forces | Visualize constraints as physics forces |
🚀 Deployment & Operations (9 guides)
| Guide | Task |
|---|---|
| Deployment | Production deployment strategies |
| Docker Compose Guide | Multi-container orchestration |
| Docker Environment Setup | Container configuration details |
| Development Workflow | Git, testing, CI/CD process |
| Testing Guide | Unit, integration, E2E testing |
| Security | Authentication, authorization, secrets |
| Telemetry Logging | Observability and monitoring |
| Pipeline Operator Runbook | Operations playbook for production |
| Contributing | Code style, PRs, documentation |
🏢 Infrastructure (6 guides)
| Guide | Task |
|---|---|
| Architecture Overview | Multi-agent Docker system design |
| Docker Environment | Container setup and management |
| Tools | Available MCP tools and integrations |
| Port Configuration | Network and service ports |
| Troubleshooting | Infrastructure-specific issues |
| Goalie Integration | Quality gates and automated testing |
🥽 XR & Multi-User (2 guides)
| Guide | Task |
|---|---|
| Vircadia XR Complete Guide | Meta Quest 3 VR implementation |
| Vircadia Multi-User Guide | Collaborative VR experiences |
👨💻 Developer (10 guides)
| Guide | Priority | Task |
|---|---|---|
| Development Setup | ⭐⭐⭐ | IDE, dependencies, local environment |
| Project Structure | ⭐⭐⭐ | Codebase organization and modules |
| Adding Features | ⭐⭐ | Feature development workflow |
| WebSocket Best Practices | ⭐ | Real-time communication patterns |
| JSON Serialization Patterns | ⭐ | Data serialization strategies |
| Test Execution | ⭐ | Running and debugging tests |
📊 Client Development (3 guides)
| Guide | Task |
|---|---|
| State Management | React state patterns with Zustand |
| Three.js Rendering | 3D visualization pipeline |
| XR Integration | WebXR implementation details |
🔄 Advanced Features (6 guides)
| Guide | Task |
|---|---|
| Semantic Features Implementation | Natural language query system |
| Hierarchy Integration | Hierarchical graph layouts |
| Stress Majorization Guide | Advanced layout algorithm |
| Ontology Sync Enhancement | GitHub ontology sync with HNSW vector search |
| DeepSeek Verification | LLM API integration testing |
| DeepSeek Deployment | Deploy DeepSeek skill container |
🔧 Migration (2 guides)
| Guide | Task |
|---|---|
| GraphServiceActor Migration | Actor system migration patterns |
| JSON to Binary Protocol | WebSocket protocol upgrade |
Deep dives into architecture, design decisions, and theory
🏛️ High-Level Architecture (4 documents)
| Document | Description |
|---|---|
| Architecture Overview | Complete system architecture with diagrams |
| Developer Journey | Step-by-step codebase learning path |
| System Overview | What VisionFlow is and why it exists |
| Technology Choices | Technology stack rationale |
🔷 System Architecture (21 documents)
⭐ NEW Core Architecture Docs (Dec 2025):
| Document | Description |
|---|---|
| Server Architecture | ⭐ 21 actors, ports/adapters, Neo4j |
| Actor System Guide | ⭐ Actor patterns, debugging, best practices |
| Database Architecture | ⭐ Neo4j schema, queries, performance |
System Architecture:
| Document | Description |
|---|---|
| System Overview | Complete architectural blueprint |
| Hexagonal CQRS | Ports & adapters with command/query separation |
| Services Architecture | Business logic layer design |
| Multi-Agent System | AI agent coordination patterns |
| Data Flow Complete | End-to-end data pipeline |
| Pipeline Integration | GitHub → Neo4j → GPU flow |
| Pipeline Sequence Diagrams | Visual interaction flows |
| Integration Patterns | System integration strategies |
| GitHub Sync Service Design | Streaming ontology sync |
| Quick Reference | Architecture cheat sheet |
| Analytics Visualization | UI/UX design patterns |
| Services Layer | Business logic refactoring |
| Ontology Physics Integration | Wire OWL constraints to GPU physics |
| RuVector Integration | 150x faster HNSW vector search |
| API Handlers Reference | Handler patterns and examples |
| CQRS Directive Template | Command/query templates |
| Ontology Analysis | Architecture decision analysis |
| XR Immersive System | Quest 3 WebXR architecture |
🗄️ Database & Persistence (3 documents)
| Document | Description |
|---|---|
| Database Architecture | ⭐ Neo4j schema, queries, performance |
| Adapter Patterns | Repository implementation patterns |
| Ontology Storage Architecture | OWL persistence in Neo4j |
🦉 Ontology & Reasoning (11 documents)
Architecture:
| Document | Description |
|---|---|
| Ontology Reasoning Pipeline | Whelk inference integration |
| Reasoning Data Flow | Inference pipeline stages |
| Reasoning Tests Summary | Test coverage report |
Concepts:
| Document | Description |
|---|---|
| Reasoning Engine | Inference engine concepts |
| Neo4j Integration | Graph database integration |
| Ontology Pipeline Integration | End-to-end OWL processing |
| Ontology Typed System | Type system design |
| Client-Side Hierarchical LOD | Level-of-detail optimization |
| Hierarchical Visualization | Tree and DAG layouts |
| Intelligent Pathfinding System | Graph traversal theory |
| Enhanced Parser | OWL parser v2 design |
⚡ Visualization & Physics (8 documents)
| Document | Description |
|---|---|
| Semantic Physics System | Force-directed layout engine |
| Semantic Forces System | Physics constraint generation |
| Semantic Physics | Theory and algorithms |
| GPU Semantic Forces | 39 CUDA kernels |
| Stress Majorization | Graph layout technique |
| Hierarchical Visualization | DAG and tree layouts |
| Semantic Forces | Physics constraint design |
| Semantic Forces Actor | Actor system integration |
🎮 GPU Acceleration (3 documents)
| Document | Description |
|---|---|
| GPU Communication Flow | CPU-GPU data transfer |
| GPU Optimizations | Performance tuning strategies |
| GPU README | GPU subsystem overview |
💻 Client-Server (4 documents)
| Document | Description |
|---|---|
| Client | React Three.js frontend architecture |
| Server | Rust Actix backend architecture |
| Visualization | 3D rendering pipeline |
| WebSocket Protocol | Binary protocol design |
🔌 Ports (Hexagonal Architecture) (7 documents)
| Document | Description |
|---|---|
| Ports Overview | Interface definitions and contracts |
| Settings Repository | User settings persistence port |
| Knowledge Graph Repository | Graph operations port |
| Ontology Repository | Ontology storage port |
| Inference Engine | Reasoning engine port |
| GPU Physics Adapter | Physics computation port |
| GPU Semantic Analyzer | Semantic processing port |
📐 Architecture Decisions (1 document)
| Document | Description |
|---|---|
| ADR-0001: Neo4j Persistence | Database strategy rationale |
Technical specifications, APIs, and detailed references
🌐 API Documentation (8 references)
| Reference | Type |
|---|---|
| API Complete Reference | All endpoints with examples |
| REST API Complete | HTTP API specification |
| REST API Reference | OpenAPI/Swagger format |
| Authentication | JWT, sessions, Nostr auth |
| WebSocket API | Real-time binary protocol |
| Semantic Features API | Natural language queries |
| Pathfinding Examples | Graph traversal examples |
| API README | API documentation index |
📡 Protocols (2 references)
| Reference | Type |
|---|---|
| Binary WebSocket | 36-byte node format spec |
| WebSocket Protocol | V2 protocol specification |
🗄️ Database (4 references)
| Reference | Type |
|---|---|
| Schemas | Neo4j graph schema |
| Ontology Schema V2 | Advanced ontology schema |
| User Settings Schema | User data model |
| Neo4j Persistence Analysis | Migration analysis |
⚙️ System Status (5 references)
| Reference | Type |
|---|---|
| Error Codes | Complete error code reference |
| Implementation Status | Feature completion matrix |
| Code Quality Status | Build and test health |
| Performance Benchmarks | GPU performance metrics |
| Physics Implementation | Physics system analysis |
| I want to... | Go here → |
|---|---|
| Install VisionFlow | Installation Tutorial |
| Create my first graph | First Graph Tutorial |
| Deploy AI agents | Agent Orchestration Guide |
| Query Neo4j database | Neo4j Integration Guide |
| Add a new feature | Adding Features Guide |
| Set up XR/VR | Vircadia XR Guide |
| Understand the architecture | Architecture Overview |
| Learn the codebase | Developer Journey |
| Deploy to production | Deployment Guide |
| Configure environment | Configuration Guide |
| Fix common issues | Troubleshooting Guide |
| Write tests | Testing Guide |
| Integrate vector search | RuVector Integration |
| Enable ontology physics | Ontology Physics Integration |
| Use the REST API | REST API Complete |
| Use WebSocket API | WebSocket API Reference |
| Understand hexagonal architecture | Hexagonal CQRS |
| Optimize performance | GPU Optimizations |
| Secure the application | Security Guide |
| Contribute code | Contributing Guide |
📊 Neo4j Graph Database
🦀 Rust / Actix Web Backend
⚛️ React / Three.js Frontend
🎮 CUDA / GPU Acceleration
🦉 OWL / Ontologies / Reasoning
🔍 Vector Search / HNSW
- RuVector Integration (150x faster)
- Ontology Sync Enhancement
🤖 AI / MCP / Multi-Agent
🥽 XR / WebXR / VR
🔌 WebSocket / Real-Time
- Archive Overview - Historical docs, completion reports, sprint logs
- 2025-12-02 Reports - Recent completion summaries
- SPARC Architecture - System visualization
- Documentation Scripts - Restructuring and migration utilities
graph TB
Start[Documentation Home]
Start --> NewUser[New Users]
Start --> Developer[Developers]
Start --> Architect[Architects]
Start --> DevOps[DevOps]
NewUser --> Tutorial[Tutorials]
NewUser --> GettingStarted[Getting Started Guides]
Developer --> DevGuides[Developer Guides]
Developer --> HowTo[How-To Guides]
Developer --> API[API Reference]
Architect --> ArchDocs[Architecture Explanations]
Architect --> TechChoices[Technology Choices]
Architect --> Decisions[ADRs]
DevOps --> Deployment[Deployment Guides]
DevOps --> Operations[Operations Runbooks]
DevOps --> Infrastructure[Infrastructure Docs]
Tutorial --> Install[Installation]
Tutorial --> FirstGraph[First Graph]
Tutorial --> Neo4jQS[Neo4j Quick Start]
HowTo --> Features[Features]
HowTo --> Integration[Integration]
HowTo --> Advanced[Advanced Topics]
ArchDocs --> System[System Overview]
ArchDocs --> Components[Components]
ArchDocs --> Patterns[Patterns]
style Start fill:#4A90E2
style Tutorial fill:#7ED321
style ArchDocs fill:#F5A623
style API fill:#BD10E0
We welcome documentation improvements! Follow these guidelines:
Every document must fit one category:
| Category | Purpose | Style |
|---|---|---|
| Tutorial | Learn by doing | Step-by-step, beginner-friendly |
| How-To | Solve a problem | Goal-oriented, practical |
| Explanation | Understand concepts | Deep dive, theory |
| Reference | Look up facts | Dry, precise, complete |
- ✅ Use UK English spelling (colour, organise, analyse)
- ✅ Include code examples with syntax highlighting
- ✅ Add Mermaid diagrams for complex flows
- ✅ Cross-reference related documents
- ✅ Update this index when adding new documents
- ✅ Add "Last Updated" date at bottom
- ✅ Include prerequisites and next steps
docs/
├── tutorials/ # Learning-oriented
├── guides/ # Task-oriented
├── explanations/ # Understanding-oriented
├── reference/ # Information-oriented
├── archive/ # Historical/deprecated
└── working/ # Work-in-progress (not linked)
See Contributing Guide for complete details.
| Issue Type | Where to Go |
|---|---|
| Documentation gaps or errors | File GitHub Issue with documentation label |
| Technical problems | Troubleshooting Guide |
| Infrastructure issues | Infrastructure Troubleshooting |
| Developer setup | Development Setup |
| Feature requests | GitHub Discussions |
- Total Documents: 226 markdown files
- Framework: Diátaxis (Tutorials, How-To, Explanations, Reference)
- Last Full Audit: 2025-12-02
- Documentation Coverage: 95%+ (all major features documented)
- Link Health: 98% valid internal links
- Diagram Format: Mermaid (100% valid syntax)
Last Updated: 2025-12-02 Documentation Version: 2.0 Framework: Diátaxis Maintainer: DreamLab AI Documentation Team