From 2d3f59ef0560e605a89c0de04ba8fcaa559969be Mon Sep 17 00:00:00 2001 From: David Snelling Date: Tue, 11 Nov 2025 09:51:16 -0800 Subject: [PATCH] docs: restructure README for better new user flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add '3 Paths' navigation to guide users based on their goal - Move Quick Start section up (line 299 β†’ 94) for faster onboarding - Reorganize Documentation section with API Reference prominent - Condense 'From Prototype to Planet Scale' section (94 β†’ 48 lines) - Add inline links to API documentation throughout - Remove duplicate Quick Start section Makes docs/api/README.md path obvious - it's the most powerful starting resource with 1,870 lines of copy-paste ready code. --- README.md | 241 +++++++++++++++++++++++++++--------------------------- 1 file changed, 119 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 37e8dd0e..955de841 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,25 @@ await brain.init() --- +## πŸ‘‰ Choose Your Path + +**New to Brainy? Pick your starting point:** + +### πŸš€ Path 1: I want to build something NOW +**β†’ [Complete API Reference](docs/api/README.md)** ⭐ **Most developers start here** ⭐ +- Every method documented with examples +- Quick start in 60 seconds +- 1,870 lines of copy-paste ready code +- **This is your primary resource** + +### 🧠 Path 2: I want to understand the big picture first +**β†’ Keep reading below** for demos, architecture, and use cases + +### πŸ“Š Path 3: I'm evaluating database options +**β†’ Jump to [Why Revolutionary](#why-brainy-is-revolutionary)** or **[Benchmarks](#benchmarks)** + +--- + ## See It In Action **30 seconds to understand why Brainy is different:** @@ -72,98 +91,96 @@ const results = await brain.find({ --- +## Quick Start + +```bash +npm install @soulcraft/brainy +``` + +### Your First Knowledge Graph (60 seconds) + +```javascript +import { Brainy, NounType, VerbType } from '@soulcraft/brainy' + +const brain = new Brainy() +await brain.init() + +// Add knowledge +const jsId = await brain.add({ + data: "JavaScript is a programming language", + type: NounType.Concept, + metadata: { category: "language", year: 1995 } +}) + +const nodeId = await brain.add({ + data: "Node.js runtime environment", + type: NounType.Concept, + metadata: { category: "runtime", year: 2009 } +}) + +// Create relationships +await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes }) + +// Query with Triple Intelligence +const results = await brain.find({ + query: "JavaScript", // πŸ” Vector + where: { category: "language" }, // πŸ“Š Document + connected: { from: nodeId, depth: 1 } // πŸ•ΈοΈ Graph +}) +``` + +**Done.** No configuration. No complexity. Production-ready from day one. + +**β†’ Ready to dive deeper? [Complete API Documentation](docs/api/README.md)** has every method with examples. + +--- + ## From Prototype to Planet Scale **The same API. Zero rewrites. Any scale.** -### πŸ‘€ **Individual Developer** β†’ Weekend Prototype - +### πŸ‘€ Individual Developer β†’ Weekend Prototype ```javascript -// Zero configuration - starts in memory -const brain = new Brainy() +const brain = new Brainy() // Zero config, starts in memory await brain.init() - -// Build your prototype in minutes -// Change nothing when ready to scale ``` +**Perfect for:** Hackathons, side projects, prototyping, learning -**Perfect for:** Hackathons, side projects, rapid prototyping, learning AI concepts - -### πŸ‘₯ **Small Team** β†’ Production MVP (Thousands of Entities) - +### πŸ‘₯ Small Team β†’ Production MVP ```javascript -// Add persistence - one line const brain = new Brainy({ - storage: { - type: 'filesystem', - path: './brainy-data', - compression: true // 60-80% space savings - } + storage: { type: 'filesystem', path: './data', compression: true } }) ``` +**Scale:** Thousands to hundreds of thousands β€’ **Performance:** <5ms queries -**Perfect for:** Startups, MVPs, internal tools, team knowledge bases -**Scale:** Thousands to hundreds of thousands of entities -**Performance:** <5ms queries, sub-second imports - -### 🏒 **Growing Company** β†’ Multi-Million Entity Scale - +### 🏒 Growing Company β†’ Multi-Million Scale ```javascript -// Scale to cloud - same API const brain = new Brainy({ - storage: { - type: 's3', - s3Storage: { - bucketName: 'my-knowledge-base', - region: 'us-east-1' - } - }, + storage: { type: 's3', s3Storage: { bucketName: 'my-kb', region: 'us-east-1' } }, hnsw: { typeAware: true } // 87% memory reduction }) ``` +**Scale:** Millions of entities β€’ **Performance:** <10ms queries, 12GB @ 10M entities -**Perfect for:** SaaS products, e-commerce, content platforms, enterprise apps -**Scale:** Millions of entities -**Performance:** <10ms queries, 12GB memory @ 10M entities -**Features:** Auto-scaling, distributed storage, cost optimization (96% savings) - -### 🌍 **Enterprise / Planet Scale** β†’ Billion+ Entities - +### 🌍 Enterprise β†’ Billion+ Scale ```javascript -// Billion-scale - STILL the same API const brain = new Brainy({ - storage: { - type: 'gcs', - gcsStorage: { bucketName: 'global-knowledge' } - }, - hnsw: { - typeAware: true, - M: 32, - efConstruction: 400 - } -}) - -// Enable intelligent archival -await brain.storage.enableAutoclass({ - terminalStorageClass: 'ARCHIVE' + storage: { type: 'gcs', gcsStorage: { bucketName: 'global-kb' } }, + hnsw: { typeAware: true, M: 32, efConstruction: 400 } }) ``` - -**Perfect for:** Fortune 500, global platforms, research institutions, government -**Scale:** Billions of entities (tested at 1B+) -**Performance:** 18ms queries @ 1B scale, 50GB memory (87% reduction) +**Scale:** Billions (tested @ 1B+) β€’ **Performance:** 18ms queries, 50GB memory **Cost:** $138k/year β†’ $6k/year with intelligent tiering (96% savings) -**Features:** Sharding, replication, monitoring, enterprise SLAs -### 🎯 **The Point** +**β†’ [Capacity Planning Guide](docs/operations/capacity-planning.md)** | **[Cost Optimization](docs/operations/)** + +### 🎯 The Point **Start simple. Scale infinitely. Never rewrite.** -Most systems force you to choose: -- Simple but doesn't scale (SQLite, Redis) -- Scales but complex (Kubernetes + 7 databases) - -**Brainy gives you both:** Starts simple as SQLite. Scales like Google. +Most systems make you choose: Simple (SQLite) OR Scalable (Kubernetes + 7 databases). +**Brainy gives you both.** Starts simple as SQLite. Scales like Google. --- @@ -296,48 +313,6 @@ Every asset knows its relationships. Intelligent tagging, similarity-based disco --- -## Quick Start - -```bash -npm install @soulcraft/brainy -``` - -### Your First Knowledge Graph (60 seconds) - -```javascript -import { Brainy, NounType, VerbType } from '@soulcraft/brainy' - -const brain = new Brainy() -await brain.init() - -// Add knowledge -const jsId = await brain.add({ - data: "JavaScript is a programming language", - type: NounType.Concept, - metadata: { category: "language", year: 1995 } -}) - -const nodeId = await brain.add({ - data: "Node.js runtime environment", - type: NounType.Concept, - metadata: { category: "runtime", year: 2009 } -}) - -// Create relationships -await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes }) - -// Query with Triple Intelligence -const results = await brain.find({ - query: "JavaScript", // πŸ” Vector - where: { category: "language" }, // πŸ“Š Document - connected: { from: nodeId, depth: 1 } // πŸ•ΈοΈ Graph -}) -``` - -**Done.** No configuration. No complexity. Production-ready from day one. - ---- - ## Core Features ### 🧠 **Natural Language Queries** @@ -355,6 +330,8 @@ await brain.find({ }) ``` +**β†’ [See all query methods in API Reference](docs/api/README.md#search--query)** + ### 🌐 **Virtual Filesystem** β€” Intelligent File Management Build file explorers and IDEs that never crash: @@ -566,40 +543,60 @@ brainy search "programming" --- -## Documentation +## πŸ“– Complete Documentation -### πŸš€ Getting Started -- **[API Reference](docs/api/README.md)** β€” Complete API documentation for all features -- **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)** β€” Upgrade from v3 (backward compatible) +**For most developers:** Start with the **[Complete API Reference](docs/api/README.md)** ⭐ + +This comprehensive guide includes: +- βœ… Every method with parameters, returns, and examples +- βœ… Quick start in 60 seconds +- βœ… Core CRUD β†’ Advanced features (branching, versioning, time-travel) +- βœ… TypeScript types and patterns +- βœ… 1,870 lines of copy-paste ready code + +--- + +### 🎯 Essential Reading (Start Here) + +1. **[πŸ“– Complete API Reference](docs/api/README.md)** ⭐ **START HERE** ⭐ + - Your primary resource for building with Brainy + - Every method documented with working examples + +2. **[Natural Language Queries](docs/guides/natural-language.md)** + - Master the `find()` method and Triple Intelligence queries + +3. **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)** + - Upgrading from v3 (100% backward compatible) + +### 🧠 Core Concepts & Architecture -### 🧠 Core Concepts - **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** β€” How vector + graph + document work together -- **[Natural Language Queries](docs/guides/natural-language.md)** β€” Using find() effectively -- **[API Reference](docs/api/README.md)** β€” Complete API documentation -- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** β€” The universal type system - -### πŸ—οΈ Architecture & Scaling +- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** β€” The universal type system (42 nouns Γ— 127 verbs) - **[Architecture Overview](docs/architecture/overview.md)** β€” System design and components - **[Data Storage Architecture](docs/architecture/data-storage-architecture.md)** β€” Type-aware indexing and HNSW -- **[Capacity Planning](docs/operations/capacity-planning.md)** β€” Memory, storage, and scaling guidelines ### ☁️ Production & Operations + - **[Cloud Deployment Guide](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** β€” Deploy to AWS, GCS, Azure -- **[AWS Cost Optimization](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)** +- **[Capacity Planning](docs/operations/capacity-planning.md)** β€” Memory, storage, and scaling to billions +- **Cost Optimization:** **[AWS S3](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)** ### 🌐 Framework Integration + - **[Framework Integration Guide](docs/guides/framework-integration.md)** β€” React, Vue, Angular, Svelte - **[Next.js Integration](docs/guides/nextjs-integration.md)** - **[Vue.js Integration](docs/guides/vue-integration.md)** -### 🌳 Virtual Filesystem +### 🌳 Virtual Filesystem (VFS) + - **[VFS Quick Start](docs/vfs/QUICK_START.md)** β€” Build file explorers that never crash - **[VFS Core Documentation](docs/vfs/VFS_CORE.md)** -- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)** +- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)** β€” AI-powered file navigation - **[Neural Extraction API](docs/vfs/NEURAL_EXTRACTION.md)** -### πŸ“¦ Data Import -- **[Import Anything Guide](docs/guides/import-anything.md)** β€” CSV, Excel, PDF, URLs +### πŸ“¦ Data Import & Processing + +- **[Import Anything Guide](docs/guides/import-anything.md)** β€” CSV, Excel, PDF, URLs with auto-detection ---