# Tagger - Project Documentation

**Version:** 1.1.0 | **Status:** Stable | **GUI:** PySide6/Qt6

---

## About

Desktop app for organizing files using hierarchical tags (category/name).

**Features:** Folder scanning, tag filtering, rename/merge tags, CSFD.cz integration, hardlink structure, 3-level config (global/folder/file).

---

## Structure

```
Tagger/
├── Tagger.py              # Entry point
├── src/core/              # Business logic (NO UI imports!)
│   ├── tag.py             # Tag value object (immutable)
│   ├── tag_manager.py     # Tag/category management
│   ├── file.py            # File with metadata
│   ├── file_manager.py    # File management, filtering
│   ├── config.py          # 3-level config system
│   ├── hardlink_manager.py
│   ├── csfd.py            # CSFD scraper
│   ├── constants.py       # APP_NAME, VERSION
│   └── _version.py        # Version fallback for PyInstaller
├── src/ui/
│   ├── gui.py             # Qt6 GUI (MainWindow)
│   └── utils.py           # load_icon()
└── tests/                 # 274 tests
```

---

## Architecture Rules

1. **UI must not contain business logic** - call FileManager/TagManager
2. **Core must not import UI** - no PySide6/tkinter in src/core/
3. **Dependency injection** - pass via constructor
4. **UTF-8 everywhere** - `encoding='utf-8'`, `ensure_ascii=False`

---

## Config Files

| Level | File | Contents |
|-------|------|----------|
| Global | `.Tagger.!gtag` | window geometry, last folder |
| Folder | `.Tagger.!ftag` | ignore patterns, hardlink settings |
| File | `.filename.!tag` | tags, date, state |

---

## Key Components

**Tag** - immutable, `Tag(category, name)`, `Tag.from_string("cat/name")`

**File** - `file_path`, `tags[]`, `date`, `csfd_url`, metadata in `.filename.!tag`

**TagManager** - `add_tag()`, `get_categories()`, `rename_tag()`, `merge_tag()`

**FileManager** - `append(folder)`, `filter_files_by_tags()`, `close_folder()`

**HardlinkManager** - `create_structure_for_files()`, `sync_structure()`

---

## Running

```bash
poetry run python Tagger.py      # GUI
poetry run pytest -q             # Tests
poetry run pyinstaller --onefile Tagger.py  # Build
```

---

## Shortcuts

`Ctrl+O` Open | `Ctrl+T` Tags | `Ctrl+D` Date | `F5` Refresh | `Del` Remove

---

## Debugging

**Version 0.0.0 in build:** Run app once from source to update `_version.py`, then rebuild.

**Cannot import:** Use `poetry run python Tagger.py`

**Metadata corrupted:** Auto-recovers with defaults.

---

## Metrics

- **Tests:** 274 ✅
- **Python:** 3.13+
- **Dependencies:** PySide6, Pillow, requests, beautifulsoup4