wifi-densepose/docs/REPO_STRUCTURE.md

Repository Structure

Clean and organized structure for the RuVector project.

Root Directory

ruvector/
├── README.md                 # Main project README
├── CHANGELOG.md             # Version history and changes
├── CLAUDE.md                # Claude Code configuration
├── LICENSE                  # MIT License
├── Cargo.toml              # Rust workspace configuration
├── Cargo.lock              # Rust dependency lock
├── package.json            # NPM workspace configuration
├── .gitignore              # Git ignore rules
│
├── crates/                 # Rust crates
│   ├── ruvector-core/      # Core vector database
│   ├── ruvector-node/      # Node.js bindings
│   ├── ruvector-wasm/      # WebAssembly bindings
│   ├── ruvector-cli/       # Command-line interface
│   ├── ruvector-bench/     # Benchmarking suite
│   ├── ruvllm/             # LLM inference engine
│   ├── sona/               # Self-Optimizing Neural Architecture
│   ├── router-core/        # Neural routing
│   └── ...                 # Additional crates
│
├── npm/                    # NPM packages
│   └── packages/
│       ├── ruvector/       # Core bindings
│       ├── ruvllm/         # LLM package
│       ├── raft/           # Consensus implementation
│       ├── replication/    # Data replication
│       └── scipix/         # OCR client
│
├── docs/                   # 📚 Documentation (organized)
│   ├── README.md           # Documentation index
│   ├── INDEX.md            # Complete file index
│   ├── REPO_STRUCTURE.md   # This file
│   ├── adr/                # Architecture Decision Records
│   ├── analysis/           # Research & analysis
│   ├── api/                # API documentation
│   ├── architecture/       # System architecture
│   ├── benchmarks/         # Performance benchmarks
│   ├── cloud-architecture/ # Cloud deployment
│   ├── code-reviews/       # Code reviews
│   ├── development/        # Contributing guides
│   ├── gnn/                # GNN documentation
│   ├── guides/             # User guides
│   ├── hnsw/               # HNSW documentation
│   ├── hooks/              # Hooks system
│   ├── implementation/     # Implementation details
│   ├── integration/        # Integration guides
│   ├── nervous-system/     # Nervous system arch
│   ├── optimization/       # Performance tuning
│   ├── postgres/           # PostgreSQL extension
│   ├── project-phases/     # Historical phases
│   ├── publishing/         # NPM publishing
│   ├── research/           # Research documentation
│   ├── ruvllm/             # RuVLLM docs
│   ├── security/           # Security audits
│   ├── testing/            # Testing docs
│   └── training/           # Training & LoRA
│
├── src/                    # 🚀 Cloud deployment source
│   ├── cloud-run/         # Cloud Run services
│   ├── agentic-integration/ # Agent coordination
│   └── burst-scaling/     # Auto-scaling system
│
├── benchmarks/            # Load testing and benchmarks
├── tests/                 # Rust integration tests
├── examples/             # Example code
│   ├── rust/            # Rust examples
│   ├── nodejs/          # Node.js examples
│   └── wasm-*/         # WASM examples
│
└── .claude/             # Claude Code helpers

Documentation Organization

All documentation is organized in /docs with clear categories:

📖 Guides & Tutorials

• guides/ - Getting started, tutorials, installation
• api/ - Rust, Node.js, Cypher API references

🏗️ Architecture & Design

• adr/ - Architecture Decision Records
• architecture/ - System design documents
• cloud-architecture/ - Global cloud deployment
• nervous-system/ - Nervous system architecture

⚡ Performance

• benchmarks/ - Performance benchmarks & results
• optimization/ - Performance tuning guides
• analysis/ - Research & analysis documents

🔐 Security

• security/ - Security audits & reports

💻 Implementation

• implementation/ - Implementation details & summaries
• integration/ - Integration guides
• code-reviews/ - Code review documentation

🔬 Specialized Topics

• gnn/ - Graph Neural Networks
• hnsw/ - HNSW index documentation
• postgres/ - PostgreSQL extension
• ruvllm/ - RuVLLM documentation
• training/ - Training & LoRA guides

👨‍💻 Development

• development/ - Contributing, migration, troubleshooting
• testing/ - Testing documentation
• publishing/ - NPM publishing guides
• hooks/ - Hooks system documentation

🔬 Research

• research/ - Research documentation
  • cognitive-frontier/ - Advanced AI research
  • gnn-v2/ - GNN v2 plans
  • latent-space/ - HNSW & attention research
  • mincut/ - MinCut algorithm research

📜 Historical

• project-phases/ - Project phase documentation

Source Code Organization

/crates - Rust Crates

Core Rust implementation organized as workspace:

• ruvector-core - Core vector database
• ruvllm - LLM inference engine
• sona - Self-Optimizing Neural Architecture
• Platform bindings (Node.js, WASM, FFI)
• CLI and benchmarking tools

/npm/packages - NPM Packages

TypeScript packages for Node.js:

• @ruvector/ruvector - Core bindings
• @ruvector/ruvllm - LLM inference
• @ruvector/raft - Consensus implementation
• @ruvector/replication - Data replication
• @ruvector/scipix - OCR client

/src - Cloud Deployment Code

Global streaming implementation:

• cloud-run/ - Cloud Run services
• agentic-integration/ - Distributed agent coordination
• burst-scaling/ - Auto-scaling and capacity management

/benchmarks - Load Testing

Comprehensive benchmarking suite for performance testing

File Counts

• Documentation: 170+ markdown files (organized in 25+ directories)
• Rust Crates: 15+ crates
• NPM Packages: 5 packages
• Root Files: 8 essential files only

Clean Root Directory

Only essential files in root:

• ✅ README.md - Project overview
• ✅ CHANGELOG.md - Version history
• ✅ CLAUDE.md - Development configuration
• ✅ LICENSE - MIT license
• ✅ Cargo.toml - Rust workspace
• ✅ Cargo.lock - Dependencies
• ✅ package.json - NPM workspace
• ✅ .gitignore - Git rules

No test files, temporary files, or duplicate docs in root!

Navigation Tips

1. New users: Start at docs/README.md
2. Quick start: See docs/guides/
3. Cloud deployment: Check docs/cloud-architecture/
4. Contributing: Read docs/development/CONTRIBUTING.md
5. API docs: Browse docs/api/
6. Architecture decisions: Review docs/adr/

---

Last Updated: 2026-01-21 Status: ✅ Clean and Organized Total Documentation: 170+ files properly categorized