# CLAUDE.md

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

## Project Overview

This is a **File System Browser** - a Python desktop application built with PySide6 that displays files and folders from a specified directory in a table format. The default target directory is `C://OEM` (Windows).

## Architecture

The application follows a simple two-layer architecture:

### Layer 1: File System Reading (`src/file_system.py`)
- **FileSystemReader**: Core utility class that handles OS-level file operations
  - Reads directory contents using `pathlib.Path`
  - Handles permission errors gracefully (skips inaccessible files)
  - Returns sorted list of `FileInfo` objects (folders first, then alphabetically)
  - Extracts file metadata: name, size, type, modification timestamp

- **FileInfo**: Data class that represents a single file/folder entry
  - Includes `size_readable` property for human-readable file sizes (B, KB, MB, GB)
  - Distinguishes between folders and files via `is_dir` flag

### Layer 2: PySide6 GUI (`src/main.py`)
- **FileSystemBrowser**: Main window that integrates file reading with UI display
  - Initializes UI layout with path label, refresh button, table widget, and status bar
  - Calls `FileSystemReader.get_files_and_folders()` to populate the table
  - Renders file metadata in 4-column table: Name, Type, Size, Modified
  - Visual feedback: folders displayed in blue, alternating row colors
  - Status bar updates with total item count and current path
  - `load_files()` method handles UI updates with exception handling

### Entry Point (`run.py`)
- Imports and runs the `main()` function from `src/main.py`
- Creates a `FileSystemBrowser` instance with default path `C://OEM`

## Common Commands

### Running the Application
```bash
python run.py
```

### Installing Dependencies
```bash
pip install -r requirements.txt
```

### Development Setup
```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python run.py
```

## Key Design Decisions

1. **Path Handling**: Uses `pathlib.Path` for cross-platform compatibility (Windows, macOS, Linux)
2. **Error Handling**: Files/folders that cannot be read due to permissions are silently skipped rather than throwing exceptions
3. **Sorting**: Folders are displayed first, followed by files, all sorted alphabetically (case-insensitive)
4. **File Type Detection**: Uses file extension (suffix) or labels as "File" if no extension; folders labeled as "Folder"
5. **Size Display**: Folders show "—" for size since folder size isn't meaningful; files show converted size with unit
6. **UI Responsiveness**: `QApplication.processEvents()` called during `load_files()` to prevent UI freezing

## Modifying the Target Directory

To browse a different directory, change the `target_path` parameter in [run.py](run.py):
```python
window = FileSystemBrowser(target_path="Your/Custom/Path")
```

Or modify the default in [src/main.py:14](src/main.py#L14).

## Dependencies

- **PySide6 6.7.1**: Official Python bindings for Qt framework (GUI framework)

## Notes for Future Development

- The application currently only reads one directory level (non-recursive)
- File I/O is synchronous; large directories may cause brief UI pause during initial load
- No persistent state is saved between sessions