# 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:
   ```typescript
   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:
   ```bash
   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`:
   ```typescript
   interface IPCHandlers {
     newHandler: (arg: ArgType) => Promise<ReturnType>;
   }
   ```

2. Implement handler in `ipc/handlers.ts`:
   ```typescript
   ipcMain.handle('newHandler', async (event, arg: ArgType) => {
     // Implementation
   });
   ```

3. Add to preload script:
   ```typescript
   newHandler: (arg: ArgType) => ipcRenderer.invoke('newHandler', arg)
   ```

4. Use in renderer:
   ```typescript
   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