# Vault - Project Documentation

## About

Resilientní úložiště s redundantní strukturou. Program spravuje 2+ kontejnerů (disk image souborů), které obsahují:
- Souborovou strukturu přístupnou přes FUSE mount
- Metadata o lokacích ostatních kontejnerů
- Informace o verzích
- Synchronizované kopie stejného obsahu napříč všemi kontejnery

**Klíčový princip:** Aplikace běží jako tray daemon, mountuje vault jako běžnou složku. Uživatel pracuje se svým oblíbeným file managerem (Nautilus, Dolphin, Thunar). Aplikace na pozadí zajišťuje synchronizaci mezi replikami.

**Platforma:** Pouze Linux (FUSE mount). Windows/Mac možná později.

---

## Specifikace

### Formát úložiště
- **Kontejner:** Raw disk image (.vault) se sparse alokací
- **Filesystem:** exFAT (cross-platform, bez 4GB limitu)
- **Přípona:** `.vault`
- **Velikost:** Uživatel zadá při vytvoření
- **Struktura uvnitř:**
  ```
  myvault.vault (sparse soubor)
  └── [exFAT filesystem]
      ├── .vault/
      │   ├── manifest.json
      │   └── lock            # Lock soubor pro exkluzivní přístup
      ├── documents/
      │   └── file.txt
      └── photos/
          └── image.jpg
  ```

### Mount
- **Metoda:** udisksctl (loop device + mount, bez root)
- **Mount point:** Automatický (udisksctl) nebo uživatelem zvolený
- **Exkluzivní přístup:** Lock soubor s fcntl - pouze jedna instance může mít vault otevřený

### Čitelnost bez aplikace (bez Vault app)
- `sudo mount -o loop myvault.vault /mnt/vault`

### Resize
- Při zaplnění: varování uživateli (notifikace při >90% využití)
- Uživatel rozhodne o zvětšení přes GUI dialog

### Umístění kontejnerů
- Kdekoli s RW přístupem (různé disky, síťová umístění, USB, cloud)
- Každý kontejner obsahuje metadata s cestami k ostatním kontejnerům

### Synchronizace
- **Úroveň:** Jednotlivé soubory (NE celé .vault obrazy)
- **Interní Python implementace** (bez rsync)
- **Hash** (SHA-256) pro detekci změn obsahu
- **Timestamp** pro určení master verze (novější vyhrává)
- Předpoklad: většinou budou všechny kontejnery dostupné → synchronní zápis
- Fallback: při nedostupnosti některého kontejneru se při reconnectu synchronizuje podle timestampu
- Chunked copy s progress callbackem pro velké soubory
- **Background sync:** Změny se detekují přes inotify/watchdog a propagují automaticky

**Jak sync funguje:**
1. Všechny repliky jsou mountnuté současně (každá do jiného temp mount pointu)
2. Uživatel vidí pouze hlavní mount point
3. Při změně souboru → soubor se zkopíruje do všech mountnutých replik
4. Při reconnect nedostupné repliky → porovnání manifestů → kopírování pouze změněných souborů

### GUI
- **Framework:** PySide6
- **Typ:** System tray aplikace (daemon)
- **Jazyk UI:** Čeština
- **Uživatel pracuje:** Se standardním file managerem OS

---

## GUI - System Tray App

### Tray ikona - stavy
| Ikona | Stav |
|-------|------|
| Zelená | Vault otevřen, vše synchronizováno |
| Modrá | Synchronizace probíhá |
| Žlutá | Některé repliky nedostupné |
| Červená | Chyba (vault zaplněn, sync selhala, atd.) |
| Šedá | Žádný vault otevřen |

### Tray menu
```
My Vault (3/3 replik online)          [status]
────────────────────────────────────
Otevřít složku                        [otevře mount point v file manageru]
────────────────────────────────────
Vytvořit nový vault...
Otevřít vault...
Zavřít vault
────────────────────────────────────
Přidat repliku...
Spravovat repliky...
────────────────────────────────────
Synchronizovat
Zvětšit vault...
────────────────────────────────────
Ukončit
```

### Dialogy
- **Nový vault:** Název, cesta, velikost (s quick buttony 1/5/10/50 GB)
- **Otevřít vault:** Výběr .vault souboru
- **Spravovat repliky:** Tabulka replik se statusem a tlačítkem pro odebrání
- **Zvětšit vault:** Aktuální využití, nová velikost
- **Sync progress:** Progress bar, aktuální soubor, log, cancel

---

## Architektura

```
Vault/
├── Vault.py                 # Entry point
├── pyproject.toml           # Poetry konfigurace
├── src/
│   ├── core/                # Business logika (BEZ UI importů!)
│   │   ├── vault.py         # Hlavní třída Vault - orchestrace
│   │   ├── container.py     # Mount/unmount přes udisksctl
│   │   ├── image_manager.py # Vytváření/resize sparse .vault souborů
│   │   ├── lock.py          # Exkluzivní přístup (fcntl)
│   │   ├── sync_manager.py  # Synchronizace mezi replikami
│   │   ├── file_watcher.py  # watchdog/inotify pro detekci změn
│   │   ├── file_sync.py     # Kopírování souborů s progress callback
│   │   ├── manifest.py      # Metadata - lokace, verze, soubory
│   │   └── file_entry.py    # Reprezentace souboru (path, hash, timestamp)
│   └── ui/
│       ├── tray_app.py      # System tray aplikace + menu
│       ├── notifications.py # System notifikace (notify-send)
│       └── dialogs/
│           ├── new_vault.py
│           ├── open_vault.py
│           ├── manage_replicas.py
│           ├── resize_vault.py
│           └── sync_progress.py
└── tests/
    ├── test_file_entry.py
    ├── test_manifest.py
    ├── test_lock.py
    ├── test_image_manager.py
    ├── test_container.py
    ├── test_file_watcher.py
    ├── test_file_sync.py
    ├── test_sync_manager.py
    └── test_vault.py
```

---

## Metadata struktura (.vault/manifest.json)

```json
{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "vault_name": "My Vault",
  "version": 1,
  "created": "2026-01-28T10:30:00Z",
  "last_modified": "2026-01-28T15:45:00Z",
  "image_size_mb": 10240,
  "locations": [
    {
      "path": "/mnt/disk1/myvault.vault",
      "last_seen": "2026-01-28T15:45:00Z",
      "status": "active"
    },
    {
      "path": "/mnt/usb/myvault.vault",
      "last_seen": "2026-01-28T15:45:00Z",
      "status": "active"
    }
  ],
  "files": [
    {
      "path": "documents/file.txt",
      "hash": "sha256:e3b0c44...",
      "size": 1234,
      "created": "2026-01-28T10:30:00Z",
      "modified": "2026-01-28T14:20:00Z"
    }
  ]
}
```

---

## Závislosti

### Python (Poetry)
```
PySide6>=6.10.1        # GUI framework
pyfuse3>=3.4.2         # FUSE binding (nepoužito - udisksctl místo FUSE)
watchdog>=6.0.0        # File system events (inotify)
loguru>=0.7.3          # Logging
python-dotenv>=1.2.1   # Environment variables

# Dev
pytest>=9.0.2
pytest-cov>=7.0.0
ruff>=0.14.14
mypy>=1.19.1
```

### Systémové závislosti (Linux)
```bash
sudo apt install udisks2 exfatprogs
```

---

## Aktuální stav

**Fáze 1-5: Dokončeno**

- Kompletní core logika (vault, container, image_manager, manifest, file_entry, lock, sync_manager, file_watcher, file_sync)
- System tray GUI s menu, notifikacemi, dialogy
- Správa replik (přidání, odebrání, tabulka se statusy)
- Automatická detekce dostupnosti replik (30s polling) s auto-reconnect
- Resize vault přes GUI dialog
- Detekce zaplnění s varováním při >90%
- Graceful shutdown (SIGINT/SIGTERM)
- 130 testů, vše passing
- ruff + mypy clean