**feat(docs): add comprehensive architecture documentation for Brainy**
- **Documentation Additions**:
- Created `brainy_architecture_diagram.md` to detail Brainy's architecture using diagrams and structured descriptions:
- Added overviews of the system, core architecture, and augmentation pipeline.
- Defined data models, graph structures, storage architecture, and performance optimizations.
- Explained vector search engine design, HNSW index structure, and usage flow examples.
- Developed `brainy_architecture_visual.md` to complement the architecture with visual aids in Mermaid.js:
- Provided detailed flowcharts, mind maps, and sequence diagrams for system components and data flow.
- **Purpose**:
- Provide in-depth technical insights into Brainy's architecture for developers and stakeholders.
- Enhance understanding of the system's core design principles with easy-to-follow diagrams and examples.
This commit is contained in:
parent
672be32bea
commit
5f9e807952
10 changed files with 2842 additions and 2 deletions
313
dev/docs/brainy_architecture_diagram.md
Normal file
313
dev/docs/brainy_architecture_diagram.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
# Brainy Architecture Diagram
|
||||
|
||||
## System Overview
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ BRAINY PLATFORM │
|
||||
│ Vector Graph Database with AI Pipeline │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ENVIRONMENT DETECTION │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Browser │ Node.js │ Serverless │ Container │ Server │
|
||||
│ (OPFS) │ (File System) │ (In-Memory) │ (Adaptive) │ (S3/Cloud) │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
```
|
||||
|
||||
## Core Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ BRAINY DATA API │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ add() │ search() │ addVerb() │ get() │ delete() │ backup() │ restore() │ etc. │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ AUGMENTATION PIPELINE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ SENSE → MEMORY → COGNITION → CONDUIT → ACTIVATION → PERCEPTION → DIALOG → WS │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ DATA PROCESSING │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Text/JSON → Embedding → Vector Storage │
|
||||
│ │ │
|
||||
│ ┌─────────────────────────┼─────────────────────────┐ │
|
||||
│ │ EMBEDDING │ VECTOR INDEX │ │
|
||||
│ │ │ │ │
|
||||
│ │ TensorFlow.js │ HNSW Algorithm │ │
|
||||
│ │ Universal Sentence │ - Hierarchical │ │
|
||||
│ │ Encoder (USE) │ - Fast Similarity │ │
|
||||
│ │ - GPU Acceleration │ - Configurable │ │
|
||||
│ │ - Batch Processing │ - Memory Efficient │ │
|
||||
│ │ - Worker Threads │ - Product Quantized │ │
|
||||
│ └─────────────────────────┼─────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
```
|
||||
|
||||
## Data Model & Graph Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ GRAPH DATA MODEL │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ NOUNS (Entities/Nodes) │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Core Entity Types: │ Digital/Content Types: │ │
|
||||
│ │ • Person │ • Document │ │
|
||||
│ │ • Organization │ • Media │ │
|
||||
│ │ • Location │ • File │ │
|
||||
│ │ • Thing │ • Message │ │
|
||||
│ │ • Concept │ • Content │ │
|
||||
│ │ • Event │ │ │
|
||||
│ │ │ Collection Types: │ │
|
||||
│ │ Business/App Types: │ • Collection │ │
|
||||
│ │ • Product │ • Dataset │ │
|
||||
│ │ • Service │ │ │
|
||||
│ │ • User │ Descriptive Types: │ │
|
||||
│ │ • Task │ • Process, State, Role │ │
|
||||
│ │ • Project │ • Topic, Language, Currency, Measurement │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ VERBS (Relationships/Edges) │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Core Relationships: │ Social/Organizational: │ │
|
||||
│ │ • RelatedTo │ • MemberOf, WorksWith │ │
|
||||
│ │ • Contains, PartOf │ • FriendOf, Follows, Likes │ │
|
||||
│ │ • LocatedAt, References │ • ReportsTo, Supervises, Mentors │ │
|
||||
│ │ │ • Communicates │ │
|
||||
│ │ Temporal/Causal: │ │ │
|
||||
│ │ • Precedes, Succeeds │ Descriptive/Functional: │ │
|
||||
│ │ • Causes, DependsOn │ • Describes, Defines, Categorizes │ │
|
||||
│ │ • Requires │ • Measures, Evaluates │ │
|
||||
│ │ │ • Uses, Implements, Extends │ │
|
||||
│ │ Creation/Transformation: │ │ │
|
||||
│ │ • Creates, Transforms │ Ownership/Attribution: │ │
|
||||
│ │ • Becomes, Modifies │ • Owns, AttributedTo │ │
|
||||
│ │ • Consumes │ • CreatedBy, BelongsTo │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Vector Storage & Search Engine
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ VECTOR SEARCH ENGINE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Query Text/Vector → Embedding → HNSW Search → Ranked Results │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ HNSW INDEX STRUCTURE │ │
|
||||
│ │ │ │
|
||||
│ │ Layer 2: ●────────●────────● (Sparse connections) │ │
|
||||
│ │ ╱│ │ │╲ │ │
|
||||
│ │ Layer 1: ●─●──●─●─●─●──●─●─●─● (Medium density) │ │
|
||||
│ │ ╱│││││││││││││││││││││╲ │ │
|
||||
│ │ Layer 0: ●●●●●●●●●●●●●●●●●●●●●●● (Dense connections) │ │
|
||||
│ │ │ │
|
||||
│ │ • Hierarchical navigation for fast search │ │
|
||||
│ │ • Configurable M (max connections), efConstruction, efSearch │ │
|
||||
│ │ • Memory-efficient with disk-based storage for large datasets │ │
|
||||
│ │ • Product quantization for dimensionality reduction │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Storage Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ADAPTIVE STORAGE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─ Hot Cache (RAM) ──┐ │
|
||||
│ │ Most accessed │ │
|
||||
│ │ LRU eviction │ │
|
||||
│ │ Auto-tuned size │ │
|
||||
│ └─────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─ Warm Cache (Storage) ─┐ │
|
||||
│ │ Recent nodes │ │
|
||||
│ │ OPFS/Filesystem/S3 │ │
|
||||
│ │ TTL-based │ │
|
||||
│ └─────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─ Cold Storage (Persistent) ─┐ │
|
||||
│ │ All nodes │ │
|
||||
│ │ OPFS/Filesystem/S3 │ │
|
||||
│ │ Batch operations │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ Environment-Specific Storage Adapters: │
|
||||
│ ┌─────────────┬─────────────┬─────────────┬─────────────┬─────────────┐ │
|
||||
│ │ Browser │ Node.js │ Serverless │ Container │ Server │ │
|
||||
│ │ OPFS │ FileSystem │ In-Memory │ Adaptive │ S3/Cloud │ │
|
||||
│ │ (Fallback: │ (Backup: │ (Optional: │ (Auto- │ (Multi- │ │
|
||||
│ │ IndexedDB) │ S3/Cloud) │ S3/Cloud) │ Detect) │ Provider) │ │
|
||||
│ └─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Augmentation Pipeline System
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ AUGMENTATION PIPELINE FLOW │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Raw Data → [SENSE] → [MEMORY] → [COGNITION] → [CONDUIT] → [ACTIVATION] → │
|
||||
│ │ │ │ │ │ │
|
||||
│ ▼ ▼ ▼ ▼ ▼ │
|
||||
│ Process Storage Reasoning Data Sync Actions │
|
||||
│ Input Persist Inference External Triggers │
|
||||
│ Convert Retrieve Logic Ops Systems Responses │
|
||||
│ │
|
||||
│ → [PERCEPTION] → [DIALOG] → [WEBSOCKET] → │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ Visualization NLP/Chat Real-time │
|
||||
│ Interpretation Response Streaming │
|
||||
│ Organization Context Communication │
|
||||
│ │
|
||||
│ Execution Modes: │
|
||||
│ • SEQUENTIAL: Step-by-step processing │
|
||||
│ • PARALLEL: Concurrent augmentation execution │
|
||||
│ • THREADED: Multi-threaded with worker pools │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Performance & Scaling Features
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PERFORMANCE OPTIMIZATIONS │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ MULTITHREADING │ │
|
||||
│ │ │ │
|
||||
│ │ Main Thread ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
||||
│ │ ├──────→ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │ │
|
||||
│ │ │ │Embedding │ │ Search │ │ Batch │ │ │
|
||||
│ │ │ │Generation│ │Operations│ │Processing│ │ │
|
||||
│ │ ←──────── └──────────┘ └──────────┘ └──────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ • Web Workers (Browser) / Worker Threads (Node.js) │ │
|
||||
│ │ • Model caching and reuse across workers │ │
|
||||
│ │ • Batch embedding for better performance │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ GPU ACCELERATION │ │
|
||||
│ │ │ │
|
||||
│ │ TensorFlow.js → WebGL Backend → GPU │ │
|
||||
│ │ ↓ │ │
|
||||
│ │ Fallback: CPU Backend for compatibility │ │
|
||||
│ │ │ │
|
||||
│ │ • Vector similarity calculations │ │
|
||||
│ │ • Embedding generation │ │
|
||||
│ │ • Tensor operations │ │
|
||||
│ │ • Automatic memory management │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ INTELLIGENT CACHING │ │
|
||||
│ │ │ │
|
||||
│ │ • Auto-tuning based on usage patterns │ │
|
||||
│ │ • Memory-aware cache sizing │ │
|
||||
│ │ • Prefetching strategies │ │
|
||||
│ │ • LRU eviction with batch processing │ │
|
||||
│ │ • Read-only mode optimizations │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Cross-Platform Integration
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ SYNCHRONIZATION & SCALING │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Browser ←→ WebSocket ←→ Server ←→ S3/Cloud Storage │
|
||||
│ ↓ ↓ │
|
||||
│ Browser ←→ WebRTC ←→ Browser (Peer-to-Peer) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ CONDUIT AUGMENTATIONS │ │
|
||||
│ │ │ │
|
||||
│ │ WebSocket iConduit: │ │
|
||||
│ │ • Browser ↔ Server sync │ │
|
||||
│ │ • Server ↔ Server sync │ │
|
||||
│ │ • Real-time data streaming │ │
|
||||
│ │ │ │
|
||||
│ │ WebRTC iConduit: │ │
|
||||
│ │ • Direct browser ↔ browser sync │ │
|
||||
│ │ • Peer-to-peer without server │ │
|
||||
│ │ • Decentralized data sharing │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ MODEL CONTROL PROTOCOL (MCP) │ │
|
||||
│ │ │ │
|
||||
│ │ External AI Models ←→ MCP Server ←→ Brainy Data & Tools │ │
|
||||
│ │ │ │
|
||||
│ │ • BrainyMCPAdapter: Data access for external models │ │
|
||||
│ │ • MCPAugmentationToolset: Pipeline tools for models │ │
|
||||
│ │ • BrainyMCPService: WebSocket & REST integration │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Data Flow Example
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ DATA FLOW EXAMPLE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. Input: "Cats are independent pets" │
|
||||
│ ↓ │
|
||||
│ 2. SENSE Augmentation: Process raw text │
|
||||
│ ↓ │
|
||||
│ 3. Embedding: TensorFlow USE → [0.123, -0.456, 0.789, ...] │
|
||||
│ ↓ │
|
||||
│ 4. MEMORY Augmentation: Store with metadata │
|
||||
│ ↓ │
|
||||
│ 5. HNSW Index: Add vector to hierarchical graph │
|
||||
│ ↓ │
|
||||
│ 6. Storage: Persist to OPFS/FileSystem/S3 │
|
||||
│ │
|
||||
│ Query: "feline pets" → Embedding → HNSW Search → Ranked Results │
|
||||
│ Result: [{text: "Cats are independent pets", similarity: 0.89, id: "123"}] │
|
||||
│ │
|
||||
│ Relationship Example: │
|
||||
│ addVerb(catId, dogId, VerbType.RelatedTo, {description: "Both are pets"}) │
|
||||
│ ↓ │
|
||||
│ Graph: [Cat] ──RelatedTo──→ [Dog] │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Key Architecture Principles:**
|
||||
|
||||
1. **Environment Agnostic**: Automatically adapts to browser, Node.js, serverless, container, or server environments
|
||||
2. **Intelligent Storage**: Multi-tier caching with automatic storage selection (OPFS, filesystem, S3, memory)
|
||||
3. **Vector + Graph**: Combines semantic vector search with graph relationships in a unified model
|
||||
4. **Extensible Pipeline**: Modular augmentation system for custom processing and integration
|
||||
5. **Performance Optimized**: GPU acceleration, multithreading, intelligent caching, and memory management
|
||||
6. **Scalable Sync**: WebSocket and WebRTC conduits for real-time synchronization across instances
|
||||
7. **AI Integration**: MCP protocol for external AI model integration and tool access
|
||||
Loading…
Add table
Add a link
Reference in a new issue