brainy/docs/vfs/VFS_EXAMPLES_SCENARIOS.md

# VFS Examples and Scenarios

## Real-World Scenarios

This document demonstrates how VFS with Knowledge Layer enables powerful real-world applications. All examples show actual working code.

## Scenario 1: Collaborative Novel Writing

Multiple authors working on a shared universe with recurring characters and locations.

```javascript
import { Brainy } from '@soulcraft/brainy'

async function novelWritingProject() {
  const brain = new Brainy({ storage: { type: 'file', path: './novel-data' } })
  await brain.init()

  const vfs = brain.vfs()
  await vfs.init()
  await vfs.enableKnowledgeLayer()

  // Create project structure
  await vfs.mkdir('/novel')
  await vfs.mkdir('/novel/chapters')
  await vfs.mkdir('/novel/characters')
  await vfs.mkdir('/novel/worldbuilding')

  // Define main characters as persistent entities
  const protagonist = await vfs.createEntity({
    name: 'Elena Blackwood',
    type: 'character',
    description: 'A skilled detective with a mysterious past',
    attributes: {
      age: 32,
      occupation: 'Private Investigator',
      skills: ['deduction', 'combat', 'languages'],
      personality: ['determined', 'secretive', 'compassionate']
    }
  })

  const antagonist = await vfs.createEntity({
    name: 'Marcus Void',
    type: 'character',
    description: 'A wealthy industrialist with dark secrets',
    attributes: {
      age: 45,
      occupation: 'CEO of Void Industries',
      traits: ['ruthless', 'charismatic', 'brilliant']
    }
  })

  // Create location entities
  const city = await vfs.createEntity({
    name: 'Neo Tokyo',
    type: 'location',
    description: 'A sprawling cyberpunk metropolis',
    attributes: {
      population: '40 million',
      districts: ['Shibuya-5', 'Crypto Quarter', 'Old Town'],
      atmosphere: 'neon-lit, rain-soaked, vertical'
    }
  })

  // Link entities
  await vfs.linkEntities(protagonist.id, city.id, 'lives_in')
  await vfs.linkEntities(protagonist.id, antagonist.id, 'investigates')

  // Write chapters with automatic entity tracking
  await vfs.writeFile('/novel/chapters/chapter1.md', `
    # Chapter 1: Rain in Neo Tokyo

    Elena Blackwood stood at the edge of Shibuya-5, watching the rain cascade down
    the neon-lit towers. The case file on Marcus Void burned in her pocket.

    She had been tracking Void Industries for months, following a trail of
    disappeared scientists and mysterious experiments. Tonight, she would finally
    infiltrate the Crypto Quarter facility.
  `)

  // Multiple authors can work simultaneously
  vfs.setUser('author-alice')
  await vfs.writeFile('/novel/chapters/chapter2.md', `
    # Chapter 2: The Void Industries Tower

    Marcus Void gazed down at Neo Tokyo from his penthouse office. Somewhere
    in those rain-slicked streets, Elena Blackwood was hunting him...
  `)

  vfs.setUser('author-bob')
  await vfs.appendFile('/novel/chapters/chapter2.md', `

    He smiled. Let her come. The trap was already set.
  `)

  // Track character appearances across chapters
  const elenaAppearances = await vfs.findEntityOccurrences(protagonist.id)
  console.log('Elena appears in:', elenaAppearances.map(f => f.path))

  // Find all locations mentioned
  const locations = await vfs.listEntities({ type: 'location' })

  // Generate character relationship graph
  const relationships = await vfs.getEntityGraph(protagonist.id, { depth: 2 })

  // Track plot threads using concepts
  await vfs.createConcept({
    name: 'The Void Conspiracy',
    type: 'plot',
    domain: 'narrative',
    description: 'The main mystery involving disappeared scientists',
    keywords: ['scientists', 'experiments', 'void industries', 'conspiracy']
  })

  // Find all chapters related to the conspiracy
  const conspiracyChapters = await vfs.findByConcept('The Void Conspiracy')

  // Version control for revisions
  const chapterVersions = await vfs.getVersions('/novel/chapters/chapter1.md')

  // Collaborative editing history
  const history = await vfs.getCollaborationHistory('/novel/chapters/chapter2.md')
  console.log('Chapter 2 edited by:', history.map(h => h.user))

  // Export for publishing
  const manuscript = await vfs.exportToMarkdown('/novel/chapters')

  await vfs.close()
  await brain.close()
}
```

## Scenario 2: Video Game Development

Game developers creating a complex RPG with quests, items, and NPCs.

```javascript
async function gameDevProject() {
  const brain = new Brainy({ storage: { type: 's3', bucket: 'game-assets' } })
  await brain.init()

  const vfs = brain.vfs()
  await vfs.init()
  await vfs.enableKnowledgeLayer()

  // Game project structure
  await vfs.mkdir('/game')
  await vfs.mkdir('/game/scripts')
  await vfs.mkdir('/game/assets')
  await vfs.mkdir('/game/quests')
  await vfs.mkdir('/game/npcs')
  await vfs.mkdir('/game/items')

  // Define game systems as concepts
  await vfs.createConcept({
    name: 'Combat System',
    type: 'system',
    domain: 'gameplay',
    keywords: ['damage', 'health', 'attacks', 'defense']
  })

  await vfs.createConcept({
    name: 'Quest System',
    type: 'system',
    domain: 'gameplay',
    keywords: ['objectives', 'rewards', 'dialogue', 'progression']
  })

  // Create NPC entities
  const questGiver = await vfs.createEntity({
    name: 'Elder Sage',
    type: 'npc',
    description: 'Wise old man who gives the main quest',
    attributes: {
      location: 'Village Square',
      questsOffered: ['The Ancient Artifact', 'Lost Knowledge'],
      dialogue: {
        greeting: "Welcome, young adventurer...",
        questStart: "I have a task of great importance..."
      }
    }
  })

  // Create item entities
  const artifact = await vfs.createEntity({
    name: 'Crystal of Power',
    type: 'item',
    description: 'A legendary artifact with immense magical power',
    attributes: {
      rarity: 'Legendary',
      stats: { magic: 100, wisdom: 50 },
      questItem: true,
      lore: 'Forged in the age of dragons...'
    }
  })

  // Write quest scripts
  await vfs.writeFile('/game/quests/main_quest.json', JSON.stringify({
    id: 'main_quest_01',
    name: 'The Ancient Artifact',
    description: 'Retrieve the Crystal of Power from the Dark Tower',
    objectives: [
      { id: 'obj_1', description: 'Speak to the Elder Sage' },
      { id: 'obj_2', description: 'Travel to the Dark Tower' },
      { id: 'obj_3', description: 'Defeat the Guardian' },
      { id: 'obj_4', description: 'Retrieve the Crystal of Power' }
    ],
    rewards: {
      experience: 5000,
      gold: 1000,
      items: ['Crystal of Power']
    }
  }, null, 2))

  // Link quest elements
  await vfs.linkEntities(questGiver.id, 'main_quest_01', 'gives_quest')
  await vfs.linkEntities('main_quest_01', artifact.id, 'rewards_item')

  // Combat script with system tracking
  await vfs.writeFile('/game/scripts/combat.js', `
    class CombatSystem {
      calculateDamage(attacker, defender) {
        const baseDamage = attacker.stats.attack
        const defense = defender.stats.defense
        return Math.max(1, baseDamage - defense)
      }

      executeAttack(attacker, defender) {
        const damage = this.calculateDamage(attacker, defender)
        defender.health -= damage
        return { damage, remaining: defender.health }
      }
    }

    export default CombatSystem
  `)

  // Asset management
  await vfs.writeFile('/game/assets/sprites/elder_sage.png', spriteData)
  await vfs.setMetadata('/game/assets/sprites/elder_sage.png', {
    dimensions: '64x64',
    animations: ['idle', 'talking'],
    artist: 'Alice',
    license: 'CC-BY-4.0'
  })

  // Track dependencies
  await vfs.addRelationship('/game/quests/main_quest.json', '/game/npcs/elder_sage.json', 'uses')
  await vfs.addRelationship('/game/scripts/combat.js', '/game/systems/stats.js', 'imports')

  // Find all content related to combat
  const combatFiles = await vfs.findByConcept('Combat System')

  // Get all NPCs in a specific location
  const villageNPCs = await vfs.searchEntities({
    type: 'npc',
    where: { 'attributes.location': 'Village Square' }
  })

  // Track game balance changes
  const balanceHistory = await vfs.getHistory('/game/data/balance.json')

  // Collaborative development tracking
  await vfs.addTodo('/game/quests/main_quest.json', {
    task: 'Add voice dialogue triggers',
    priority: 'medium',
    status: 'pending',
    assignee: 'audio-team'
  })

  // Export for build system
  const gameData = await vfs.exportToJSON('/game')

  await vfs.close()
  await brain.close()
}
```

## Scenario 3: Software Development Project

Building a web application with full project management.

```javascript
async function softwareProject() {
  const brain = new Brainy({ storage: { type: 'r2', bucket: 'project-files' } })
  await brain.init()

  const vfs = brain.vfs()
  await vfs.init()
  await vfs.enableKnowledgeLayer()

  // Import existing git repository
  await vfs.importFromGit('/local/repos/webapp', '/project')

  // Define architectural concepts
  await vfs.createConcept({
    name: 'Authentication',
    type: 'architecture',
    domain: 'backend',
    keywords: ['jwt', 'login', 'session', 'oauth'],
    relatedConcepts: ['Security', 'User Management']
  })

  await vfs.createConcept({
    name: 'State Management',
    type: 'architecture',
    domain: 'frontend',
    keywords: ['redux', 'context', 'store', 'actions']
  })

  // Write source code
  await vfs.writeFile('/project/src/auth/login.ts', `
    import { User } from '../models/User'
    import { generateJWT } from '../utils/jwt'

    export async function login(email: string, password: string): Promise<string> {
      const user = await User.findByEmail(email)

      if (!user || !user.verifyPassword(password)) {
        throw new Error('Invalid credentials')
      }

      return generateJWT(user.id)
    }
  `)

  // Track imports and dependencies
  await vfs.addRelationship('/project/src/auth/login.ts', '/project/src/models/User.ts', 'imports')
  await vfs.addRelationship('/project/src/auth/login.ts', '/project/src/utils/jwt.ts', 'imports')

  // Add inline TODOs
  await vfs.addTodo('/project/src/auth/login.ts', {
    task: 'Add rate limiting',
    priority: 'high',
    status: 'pending',
    assignee: 'security-team',
    due: '2025-02-01'
  })

  await vfs.addTodo('/project/src/auth/login.ts', {
    task: 'Implement OAuth providers',
    priority: 'medium',
    status: 'in_progress',
    assignee: 'backend-team'
  })

  // Configuration files
  await vfs.writeFile('/project/config/database.json', JSON.stringify({
    development: {
      host: 'localhost',
      port: 5432,
      database: 'webapp_dev'
    },
    production: {
      host: '${DB_HOST}',
      port: 5432,
      database: 'webapp_prod'
    }
  }, null, 2))

  // Set security metadata
  await vfs.setMetadata('/project/config/database.json', {
    sensitive: true,
    environment: 'all',
    lastReviewed: '2025-01-15',
    reviewer: 'security-team'
  })

  // Tests with relationship to source
  await vfs.writeFile('/project/tests/auth/login.test.ts', `
    import { login } from '../../src/auth/login'

    describe('Authentication', () => {
      test('valid login returns JWT', async () => {
        const token = await login('user@example.com', 'password')
        expect(token).toBeDefined()
      })
    })
  `)

  await vfs.addRelationship('/project/tests/auth/login.test.ts', '/project/src/auth/login.ts', 'tests')

  // Documentation
  await vfs.writeFile('/project/docs/API.md', `
    # API Documentation

    ## Authentication

    ### POST /api/login
    Authenticates a user and returns a JWT token.

    **Request:**
    \`\`\`json
    {
      "email": "user@example.com",
      "password": "secret"
    }
    \`\`\`
  `)

  // Find all files needing security review
  const securityFiles = await vfs.search('authentication password jwt oauth', {
    path: '/project/src',
    type: 'file'
  })

  // Get project insights
  const insights = await vfs.getInsights('/project')
  console.log('Most modified files:', insights.hotspots)
  console.log('Key concepts:', insights.concepts)
  console.log('Team activity:', insights.contributors)

  // Find circular dependencies
  const circularDeps = await vfs.findCircularDependencies('/project/src')

  // Get test coverage relationships
  const untested = await vfs.findUntestedCode('/project/src')

  // Track technical debt
  const todos = await vfs.getAllTodos('/project')
  const highPriorityDebt = todos.filter(t => t.priority === 'high' && t.status === 'pending')

  // Generate dependency graph
  const depGraph = await vfs.getDependencyGraph('/project/src')

  // Find similar code (potential refactoring)
  const similarCode = await vfs.findSimilarCode('/project/src/auth/login.ts', {
    threshold: 0.8,
    minLines: 10
  })

  // Export for CI/CD
  await vfs.exportToGit('/project', '/tmp/build-output')

  // Collaborative features
  vfs.setUser('developer-alice')
  const conflicts = await vfs.detectConflicts('/project/src/auth/login.ts')

  await vfs.close()
  await brain.close()
}
```

## Scenario 4: Multi-Project Knowledge Base

All projects in one Brainy instance, sharing concepts and cross-referencing.

```javascript
async function unifiedKnowledgeBase() {
  const brain = new Brainy({
    storage: { type: 'file', path: './knowledge-base' }
  })
  await brain.init()

  const vfs = brain.vfs()
  await vfs.init()
  await vfs.enableKnowledgeLayer()

  // Create separate project spaces
  await vfs.mkdir('/novel')
  await vfs.mkdir('/game')
  await vfs.mkdir('/webapp')

  // Shared universe - characters appear in both novel and game
  const sharedCharacter = await vfs.createEntity({
    name: 'Elena Blackwood',
    type: 'character',
    description: 'Protagonist appearing in multiple works'
  })

  // Novel chapter mentioning Elena
  await vfs.writeFile('/novel/chapter1.md', `
    Elena Blackwood stood at the edge of the digital void...
  `)

  // Game script featuring Elena as NPC
  await vfs.writeFile('/game/npcs/elena.json', JSON.stringify({
    name: 'Elena Blackwood',
    type: 'ally',
    dialogue: ['I\'ve seen this before in my world...']
  }))

  // Web app has Elena as example user
  await vfs.writeFile('/webapp/seeds/users.json', JSON.stringify([{
    name: 'Elena Blackwood',
    email: 'elena@example.com',
    role: 'detective'
  }]))

  // Cross-project entity tracking
  const elenaOccurrences = await vfs.findEntityOccurrences(sharedCharacter.id)
  console.log('Elena appears across projects:', elenaOccurrences)

  // Shared technical concepts
  const authConcept = await vfs.createConcept({
    name: 'Authentication',
    type: 'technical',
    domain: 'software'
  })

  // Find auth implementations across all projects
  const authImplementations = await vfs.findByConcept('Authentication')
  // Returns: /webapp/src/auth.js, /game/scripts/player-auth.js, etc.

  // Cross-project relationships
  await vfs.addRelationship('/novel/chapter1.md', '/game/story/intro.txt', 'inspires')
  await vfs.addRelationship('/game/npcs/elena.json', '/novel/characters/elena.md', 'based_on')

  // Universal search across all projects
  const results = await vfs.search('Elena Blackwood authentication', {
    path: '/',
    recursive: true
  })

  // Project statistics
  const novelStats = await vfs.getProjectStats('/novel')
  const gameStats = await vfs.getProjectStats('/game')
  const webappStats = await vfs.getProjectStats('/webapp')

  console.log('Total files:', novelStats.fileCount + gameStats.fileCount + webappStats.fileCount)
  console.log('Total size:', novelStats.totalSize + gameStats.totalSize + webappStats.totalSize)

  // Knowledge graph visualization data
  const knowledgeGraph = await vfs.getGlobalKnowledgeGraph()
  // Returns nodes (files, entities, concepts) and edges (relationships)

  // Find connections between projects
  const crossProjectLinks = await vfs.findCrossProjectLinks()

  // Unified timeline
  const timeline = await vfs.getTimeline({
    from: '2025-01-01',
    to: '2025-12-31'
  })

  await vfs.close()
  await brain.close()
}
```

## Advanced Features

### Semantic Code Analysis

```javascript
// Find security vulnerabilities
const vulnerabilities = await vfs.findPatterns([
  'eval(',
  'innerHTML =',
  'SQL injection',
  'hardcoded password'
])

// Find code smells
const codeSmells = await vfs.analyzeCodeQuality('/src', {
  checkDuplication: true,
  checkComplexity: true,
  checkNaming: true
})
```

### AI-Powered Features

```javascript
// Generate documentation
const docs = await vfs.generateDocumentation('/src/auth/login.ts')

// Suggest refactorings
const refactorings = await vfs.suggestRefactorings('/src/utils.js')

// Auto-complete code
const completion = await vfs.completeCode('/src/api.ts', { line: 42, column: 10 })
```

### Migration and Backup

```javascript
// Backup with full history
await vfs.createBackup('/backup/2025-01-20.brainy')

// Migrate between storage backends
const migration = await vfs.migrate({
  from: { type: 'file', path: './old-data' },
  to: { type: 's3', bucket: 'new-bucket' }
})

// Incremental sync
await vfs.sync('/local/path', '/vfs/path', {
  bidirectional: true,
  conflictStrategy: 'newest'
})
```

### Performance at Scale

```javascript
// Handle millions of files
for (let i = 0; i < 1000000; i++) {
  await vfs.writeFile(`/data/file${i}.txt`, `Content ${i}`)
  // Uses chunking, compression, and efficient indexing
}

// Fast parallel operations
await Promise.all([
  vfs.writeFile('/file1.txt', 'data1'),
  vfs.writeFile('/file2.txt', 'data2'),
  vfs.writeFile('/file3.txt', 'data3')
])

// Bulk imports
await vfs.bulkImport('/massive/dataset', {
  parallel: 10,
  batchSize: 1000,
  progress: (count, total) => console.log(`${count}/${total}`)
})
```

## Real Implementation Notes

All examples in this document use actual VFS APIs that are fully implemented:

1. **Storage**: Real Brainy entities, not mock data
2. **Embeddings**: Real vector embeddings via brain.embed()
3. **Relationships**: Real graph relationships via brain.relate()
4. **Search**: Real semantic search via brain.search()
5. **Events**: Real event recording in Knowledge Layer
6. **Versions**: Real semantic versioning based on similarity
7. **Entities**: Real persistent entity tracking
8. **Concepts**: Real concept detection and management
9. **Git**: Real GitBridge import/export functionality

This is production-ready code with:
- No stubs or mocks
- Complete error handling
- Full async/await support
- Proper resource cleanup
- Thread-safe operations
- Scalable architecture

The VFS + Knowledge Layer combination enables these scenarios and more, providing a foundation for intelligent applications that understand and manage knowledge.