watch-finished-turbo/.cursorrules

# Cursor Rules for Watch Finished Turbo

## Repository Overview
This is a Turborepo monorepo containing a full-stack video processing system with automatic file watching, HandBrake integration, and a web interface for management.

## Project Structure

### Apps (`/apps`)
- **`web/`**: Next.js 14 application with TypeScript, Tailwind CSS
  - Real-time dashboard for monitoring video processing
  - WebSocket integration for live updates
  - Located at `apps/web/`
- **`service/`**: NestJS API server with TypeScript
  - REST API endpoints for file management
  - WebSocket gateway for real-time events
  - SQLite database integration
  - Located at `apps/service/`
- **`cli/`**: Node.js command-line interface
  - Interactive CLI for system management
  - Direct command execution capabilities
  - Located at `apps/cli/`

### Packages (`/packages`)
- **`eslint-config/`**: Shared ESLint configurations
  - Base config, Next.js config, React internal config
  - Used across all TypeScript projects
- **`typescript-config/`**: Shared TypeScript configurations
  - Base config, Next.js config, React library config
  - Extended by all TypeScript packages
- **`ui/`**: Shared React components (currently a stub)
  - Future shared UI components
  - Tailwind CSS integration

### Data (`/data`)
- SQLite database files
- Schema documentation in `data/README.md`
- Contains processed video metadata, tasks, and settings

### Documentation (`/docs`)
- `DEVELOPMENT_NOTES.md`: Setup and development guide
- Architecture documentation
- Additional technical documentation

### Scripts (`/scripts`)
- Build and deployment scripts
- Automation tools

## Technology Stack

### Frontend (Web App)
- **Framework**: Next.js 14 with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **State Management**: React hooks + WebSocket
- **Testing**: Jest + Playwright

### Backend (Service)
- **Framework**: NestJS
- **Language**: TypeScript
- **Database**: SQLite with custom service layer
- **WebSocket**: Socket.IO integration
- **Testing**: Jest

### CLI
- **Runtime**: Node.js
- **Language**: TypeScript
- **Interface**: Commander.js or similar

### Build & Development
- **Monorepo**: Turborepo
- **Package Manager**: pnpm
- **Linting**: ESLint (shared configs)
- **Type Checking**: TypeScript (shared configs)
- **Container**: Docker + Docker Compose

## Development Workflow

### Getting Started
```bash
pnpm install
pnpm run dev  # Starts all services
```

### Individual Services
```bash
pnpm run web      # Next.js on :3000
pnpm run service  # NestJS on :3001
pnpm run cli      # Interactive CLI
```

### Key Scripts
- `pnpm run build` - Build all apps
- `pnpm run lint` - Run ESLint
- `pnpm run test` - Run tests

## Code Organization Principles

### File Naming
- Use kebab-case for directories (e.g., `file-watcher.service.ts`)
- Use PascalCase for classes and components
- Use camelCase for variables and functions
- Use kebab-case for file names (e.g., `app.controller.ts`)

### Import Structure
- Relative imports for same-package files
- Absolute imports for cross-package dependencies
- Group imports: Node.js built-ins, external packages, internal packages

### Database Schema
- SQLite with tables: files, tasks, settings
- Custom service layer for data access
- Migration system for schema updates

## Architecture Patterns

### Service Layer Pattern
- Controllers handle HTTP/WebSocket requests
- Services contain business logic
- Database operations abstracted through services

### Event-Driven Architecture
- WebSocket events for real-time updates
- File system watching triggers processing
- Background task queue for video processing

### Configuration Management
- Environment-based configuration
- Database-stored settings for datasets
- Shared config packages for consistency

## Common Development Tasks

### Adding a New API Endpoint
1. Add route in controller (`apps/service/src/app.controller.ts`)
2. Implement business logic in service
3. Update WebSocket events if needed
4. Update API documentation

### Adding a New Web Page
1. Create page in `apps/web/src/app/`
2. Add components in appropriate directories
3. Connect to API endpoints
4. Update navigation if needed

### Adding Shared Components
1. Add to `packages/ui/src/`
2. Export from `packages/ui/src/index.ts`
3. Import in consuming apps

## Testing Strategy

### Unit Tests
- Service methods and utilities
- Component logic (where applicable)
- Database operations

### Integration Tests
- API endpoints
- WebSocket connections
- CLI commands

### E2E Tests
- Full user workflows
- Critical path testing
- Playwright for web interface

## Deployment

### Docker
- Multi-stage builds for optimization
- Separate containers for web, service, and database
- Docker Compose for local development

### Production Considerations
- Environment variable management
- Database backups and migrations
- Monitoring and logging
- CDN for static assets

## Contributing Guidelines

1. Follow existing code patterns and naming conventions
2. Add tests for new functionality
3. Update documentation for API changes
4. Use conventional commits
5. Run full test suite before submitting PRs

## Troubleshooting

### Common Issues
- Port conflicts: Check if services are already running
- Database errors: Verify SQLite file permissions
- Build failures: Clear node_modules and reinstall
- WebSocket issues: Check CORS and firewall settings

### Debug Commands
```bash
# Check service status
pnpm run service:status

# View logs
pnpm run logs

# Reset database
pnpm run db:reset
```