# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

NetCatClient is a Ruby Sinatra Web Application for network device management and task execution. It connects to network devices via Telnet/SSH to execute scripts and manage device configurations.

- **Ruby Version**: 3.0.2
- **Framework**: Sinatra 4.2
- **Database**: SQLite3 with Sequel ORM
- **Web Server**: Puma
- **Default Port**: 4567

## Common Commands

### Installation and Setup
```bash
# Install dependencies
bundle install
```

### Running the Application
```bash
# Development mode with code reloading
RACK_ENV=development bundle exec ruby app.rb

# Default mode
bundle exec ruby app.rb

# Via rackup
rackup config.ru
```

### Testing
```bash
# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/local_task_execution_spec.rb

# Run with documentation format
bundle exec rspec --format documentation
```

## Architecture

### Directory Structure
```
net_cat_client/
├── app.rb                          # Main Sinatra application
├── config/
│   ├── boot.rb                    # Bootstrap and dependency loading
│   ├── database.rb                # Database connection and migrations
│   ├── settings.rb                # Configuration management (Singleton)
│   └── settings.yml               # YAML configuration
├── models/                         # Sequel ORM models
│   ├── local_device.rb            # Network device model
│   ├── local_task.rb              # Task model
│   ├── local_task_execution.rb    # Task execution tracking
│   ├── cached_script.rb           # Script cache
│   └── system_setting.rb          # System settings
├── routes/                         # Sinatra route modules
│   ├── device_routes.rb
│   ├── task_routes.rb
│   ├── task_execution_routes.rb
│   ├── setting_routes.rb
│   └── script_routes.rb
├── services/                       # Business logic
│   ├── cloud_client.rb            # Cloud API sync
│   ├── log_service.rb             # Logging
│   └── password_encryptor.rb      # Password encryption
├── lib/                            # Core libraries
│   ├── telnet_device.rb           # Telnet device communication
│   ├── task_execution_manager.rb  # Task execution coordination
│   ├── task_execution_coordinator.rb
│   ├── thread_pool_executor.rb    # Thread management
│   ├── script_executor.rb         # Script execution
│   └── [other utilities]
├── views/                          # ERB templates (Vue.js enabled)
├── public/                         # Static assets
└── spec/                           # RSpec tests
```

### Key Architectural Components

1. **Models**: Sequel::Model subclasses with timestamps, validation_helpers, and json_serializer plugins
2. **Routes**: Sinatra modules registered in the main app using the `registered` pattern
3. **Services**: Plain Ruby classes, often using Singleton pattern
4. **Lib**: Core execution engine for task/script execution on network devices
5. **Views**: ERB templates with Vue.js for interactive UI components

### Configuration

- **Settings**: Singleton `Settings` class loads from `config/settings.yml`
- **Database**: SQLite database at `db/client.db` (configurable in settings)
- **Encryption**: Passwords encrypted via `PasswordEncryptor` service

### Task Execution Flow

The task execution system is multi-threaded and coordinated:
1. `TaskExecutionCoordinator` - Manages overall execution state
2. `ThreadPoolExecutor` - Manages thread pool for parallel execution
3. `DeviceExecutionProcessor` - Handles execution on individual devices
4. `ScriptExecutor` - Executes scripts on devices via Telnet
5. `TaskFinalizer` - Cleans up and completes tasks

## Code Style Guidelines

- **Indentation**: 2 spaces (no tabs)
- **Naming**:
  - Classes/Modules: `PascalCase`
  - Methods/Variables: `snake_case`
  - Constants: `UPPER_SNAKE_CASE`
- **Comments**: Business logic in Chinese, explaining "why" not "what"
- **String Literals**: `# frozen_string_literal: true` at top of all Ruby files
- **Require Pattern**: Use `require` for gems, `require_relative` for local files, `require_all` for directories

## Development Workflow

1. **Models**: Create in `models/` as Sequel::Model subclasses
2. **Routes**: Create in `routes/` as Sinatra modules, register in `app.rb`
3. **Services**: Create in `services/` as plain Ruby classes
4. **Views**: Create in `views/` as ERB templates
5. **Tests**: Create in `spec/` with RSpec
