# MovieMapper Agent Guidelines

## Project Overview
MovieMapper is an Electron-based desktop application for organizing and managing movie and TV show collections. It provides features for browsing media files, searching TV shows using TheTVDB API, and managing file metadata.

## Build/Lint/Test Commands

### Build Commands
- `npm install` - Install project dependencies
- `npm start` - Run the application using Electron
- `electron .` - Alternative way to run the application

### Test Commands
- `npm test` - Currently outputs "Error: no test specified" (default test script)
- `node test-api.js` - Run API connectivity test for TheTVDB

### Linting
- No explicit linting tools configured in package.json
- Code style follows JavaScript/Node.js conventions

## Code Style Guidelines

### Imports
- Use standard Node.js `require()` syntax for modules
- Import modules at the top of files
- Group imports by standard library, external modules, then local modules

### Formatting
- Use 2-space indentation
- Use single quotes for strings
- Place opening braces on the same line as the statement
- Add spaces around operators and after commas
- No semicolons required (follows JavaScript convention)

### Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for constructors
- Use UPPER_CASE for constants
- Use descriptive variable names
- Function names should be verbs (e.g., `scanDirectory`, `extractFileMetadata`)

### Types
- This is a JavaScript project without TypeScript
- Use JSDoc comments to document function parameters and return values
- Use descriptive parameter names

### Error Handling
- Use try/catch blocks for async operations
- Handle file system errors gracefully
- Log warnings for problematic files but don't crash the application
- Return consistent error structures from async functions

### File Structure
- `main.js` - Electron main process handling IPC and application lifecycle
- `renderer.js` - Electron renderer process managing UI interactions
- `index.html` - Main HTML structure
- `utils/fileUtils.js` - File scanning and metadata extraction utilities
- `.env` - Environment configuration file for API keys

### API Integration
- TheTVDB v4 API integration using bearer token authentication
- Proper error handling for API calls
- Fallback mechanisms when metadata extraction fails
- Environment variables for API keys

### Code Patterns
- Use async/await for handling asynchronous operations
- Handle permission errors gracefully when scanning directories
- Provide user feedback through console warnings for problematic files
- Use descriptive variable names that reflect their purpose

### Debugging
- Built-in debugging utilities for problematic files
- Console logging for development and debugging
- Error messages include context information