FindMyShitV2/DEVELOPMENT.md

Data Hound Development Guide

This document provides detailed technical information for developers working on the Data Hound project. It covers architecture, development workflows, and best practices.

Architecture Overview

Main Process (Electron)

The main process (electron/) handles:

• File system operations (services/fileSystem.ts)
• LLM service integration (services/llmService.ts, services/ollamaService.ts)
• Vector store management (services/vectorStore.ts)
• IPC communication (ipc/handlers.ts)
• Application state persistence (store.ts)

Key Services

1. File System Service (fileSystem.ts)

   • Handles file indexing and monitoring
   • Manages file metadata extraction
   • Implements file type detection and parsing

2. LLM Service (llmService.ts)

   • Manages LLM provider connections
   • Handles prompt engineering
   • Implements response streaming

3. Vector Store (vectorStore.ts)

   • Manages ChromaDB integration
   • Handles document embeddings
   • Implements semantic search functionality

Renderer Process (React)

The renderer process (src/) is organized into:

• Components (components/)
• Contexts (contexts/)
• Custom hooks (hooks/)
• Type definitions (electron.d.ts)

Key Components

1. ChatPanel

   • Handles user queries and LLM responses
   • Manages conversation history
   • Implements message rendering

2. FileExplorer

   • Directory selection and navigation
   • File list visualization
   • File metadata display

3. ScanningPanel

   • Progress visualization for file scanning
   • Status updates
   • Error handling

Adding New Features

Adding a New LLM Provider

1. Create a new service in electron/services/
2. Implement the provider interface:

   interface LLMProvider {
     initialize(): Promise<void>;
     query(prompt: string): Promise<string>;
     streamResponse(prompt: string): AsyncGenerator<string>;
   }
   

3. Add provider configuration to store.ts
4. Update the settings UI in SettingsPanel
5. Add the provider to the LLM service factory

Adding File Type Support

1. Update fileSystem.ts with new file type detection
2. Implement parsing logic in a new service
3. Add metadata extraction
4. Update the vector store schema if needed
5. Add UI support in FileExplorer

Adding a New Panel

1. Create component in src/components/
2. Add routing in App.tsx
3. Implement required hooks
4. Add IPC handlers if needed
5. Update navigation

Development Workflows

Local Development

1. Start Electron development:

   npm run dev
   

   This runs:

   • Vite dev server for React
   • Electron with hot reload
   • TypeScript compilation in watch mode

2. Debug main process:

   • Use VSCode launch configuration
   • Console logs appear in terminal
   • Break points work in VSCode

3. Debug renderer process:

   • Use Chrome DevTools (Cmd/Ctrl+Shift+I)
   • React DevTools available
   • Network tab shows IPC calls

Testing

1. Unit Tests:

   • Located in __tests__ directories
   • Run with npm test
   • Focus on service logic

2. Integration Tests:

   • Test IPC communication
   • Verify file system operations
   • Check LLM integration

3. E2E Tests:

   • Use Playwright
   • Test full user workflows
   • Verify cross-platform behavior

Best Practices

TypeScript

1. Use strict type checking
2. Define interfaces for all IPC messages
3. Avoid any - use proper types
4. Use discriminated unions for state

React Components

1. Use functional components
2. Implement proper error boundaries
3. Memoize expensive computations
4. Use proper prop types

Electron

1. Validate IPC messages
2. Handle window state properly
3. Implement proper error handling
4. Use proper security practices

State Management

1. Use contexts for shared state
2. Implement proper loading states
3. Handle errors gracefully
4. Use proper TypeScript types

Common Tasks

Adding an IPC Handler

1. Define types in preload-types.ts:

   interface IPCHandlers {
     newHandler: (arg: ArgType) => Promise<ReturnType>;
   }
   

2. Implement handler in ipc/handlers.ts:

   ipcMain.handle('newHandler', async (event, arg: ArgType) => {
     // Implementation
   });
   

3. Add to preload script:

   newHandler: (arg: ArgType) => ipcRenderer.invoke('newHandler', arg)
   

4. Use in renderer:

   const result = await window.electron.newHandler(arg);
   

Updating the Database Schema

1. Create migration in electron/services/vectorStore.ts
2. Update type definitions
3. Implement data migration
4. Update queries
5. Test migration

Adding Settings

1. Add to store schema in store.ts
2. Update settings component
3. Implement validation
4. Add migration if needed
5. Update relevant services

Troubleshooting

Common Issues

1. IPC Communication Failures

   • Check handler registration
   • Verify type definitions
   • Check error handling

2. File System Issues

   • Verify permissions
   • Check path handling
   • Validate file operations

3. LLM Integration

   • Verify API keys
   • Check network connectivity
   • Validate response handling

Performance Optimization

1. Main Process

   • Profile file system operations
   • Optimize database queries
   • Implement proper caching

2. Renderer Process

   • Use React.memo for expensive components
   • Implement virtual scrolling
   • Optimize re-renders

Release Process

1. Update version in package.json
2. Run full test suite
3. Build production version
4. Test packaged application
5. Create release notes
6. Tag release in git
7. Build installers
8. Publish release

Contributing

1. Fork the repository
2. Create feature branch
3. Follow code style
4. Add tests
5. Submit pull request

Remember to:

• Follow TypeScript best practices
• Add proper documentation
• Include tests
• Update this guide as needed