# VILMAL — wymagania sprzętowe i środowiskowe

Stan na 2026-09-24. Liczby oznaczone „zmierzone" pochodzą z bieżącego repo/środowiska
dev; reszta to wymagania projektowe wynikające z architektury.

## 1. Co w ogóle wymaga sprzętu

System składa się z trzech elementów runtime:

| Komponent | Technologia | Gdzie działa |
|---|---|---|
| Aplikacja (API + panel + worker + baza) | Node.js ≥ 22.12, Fastify, React (build statyczny serwowany przez Fastify), SQLite `node:sqlite` w trybie WAL | serwer, jeden proces |
| Silnik rekoloru wariantów `fabric_recolor` v7 | Python 3.11–3.14, PyTorch 2.11, BiRefNet + GroundingDINO + SAM + Depth-Anything-V2 | ten sam serwer albo osobna maszyna; wywoływany jako CLI na wariant |
| Generatywne AI (galeria, Maciuś, I2V) | RunComfy Model API, Groq (vision LLM), BaseLinker API | **chmura** — lokalny GPU nie jest wymagany do generacji |

Nie ma osobnego serwera bazy danych, Redis ani kolejki — SQLite i worker są
wbudowane w proces aplikacji. To świadoma decyzja: jeden host wystarczy.

## 2. Serwer produkcyjny — zalecane

| Zasób | Zalecane | Minimum |
|---|---|---|
| CPU | 8 rdzeni | 4 rdzeni (sharp/pdfkit + Python jednocześnie) |
| RAM | 16 GB | 8 GB |
| GPU | NVIDIA ≥ 8 GB VRAM (np. RTX 3060 12 GB / RTX 4060) | NVIDIA ≥ 4 GB VRAM, CUDA 12.8 — patrz §3 |
| Dysk | 250 GB SSD/NVMe | 100 GB SSD — patrz §5 |
| System | Linux (Debian/Ubuntu LTS) lub Windows Server; Docker Compose opcjonalnie | dowolny OS z Node 22+ i Python 3.11+ |
| Sieć | stałe IP/domena, TLS, łącze ≥ 50 Mb/s | wychodzący HTTPS do API zewnętrznych |

Jeden host obejmuje aplikację i rekolor. Przy większym obciążeniu usługę
recolor można wynieść na osobną maszynę z GPU — kontrakt to już izolowany
proces (CLI/FastAPI na `:8000`), nie wymaga zmian architektury.

## 3. GPU — tylko dla rekoloru tkanin

Generacja obrazów i wideo odbywa się w chmurze (RunComfy). Lokalny GPU
obsługuje wyłącznie deterministyczny silnik segmentacji/rekoloru v7:

- **Zmierzony punkt odniesienia:** GTX 1650 4 GB — szczyt ~3,5 GB VRAM
  (BiRefNet ~3,2 GB + DINO/SAM; Depth-Anything ~95 MB, leniwe ładowanie +
  `empty_cache()` po każdej segmentacji). Build torch `+cu128`.
- **Minimum:** 4 GB VRAM — działa, ale bez zapasu; nowsze modele lub większe
  kadry mogą nie wejść.
- **Zalecane:** 8–12 GB VRAM — zapas na większe rozdzielczości masterów
  i równoległe utrzymanie modeli w pamięci.
- **Tryb CPU:** obsługiwany (`device=cpu/auto`), ale czas na wariant nie jest
  zmierzony i będzie istotnie dłuższy — przy macierzy 34 wariantów (L/P × 17
  odcieni) to różnica między partią a czekaniem. CPU-only traktować jako tryb
  awaryjny, nie docelowy. Wymaga wtedy ~8 GB wolnego RAM na modele.
- **Bez GPU w ogóle:** rekolor wariantów niedostępny; reszta systemu (upload,
  galeria z chmury, dokumenty, eksport) działa — funkcja powinna być wtedy
  jawnie oznaczona jako niedostępna, zgodnie z zasadą braku pozorowania.

## 4. Stacja operatora / klient

- Dowolny desktop/laptop z aktualną przeglądarką (Chrome/Edge/Firefox) — panel
  jest SPA serwowaną z serwera, brak instalacji.
- Tablet działa; upload zdjęć z telefonu na hali przez przeglądarkę.
- Limity uploadu: ≤ 25 MB na plik, ≤ 30 plików na żądanie.

## 5. Magazyn danych i wzrost

Zmierzone na dev (2 produkty, OSKAR z 34 wariantami):

- `data/` — **~870 MB** łącznie: media 816 MB (oryginały + derived + cache
  rekoloru), źródła 41 MB, baza SQLite ~18 MB.
- Prognoza: ~0,5–1 GB na produkt z pełną macierzą wariantów i wersjami
  (oryginały są niezmienne, wersje nie są nadpisywane — dane rosną).
- 100 produktów ≈ 50–100 GB + backup. Backup musi obejmować **bazę i media**
  razem (snapshot spójny: `vilmal.db` + `data/media` + `data/sources`).

## 6. Sieć i zależności zewnętrzne

Wychodzący HTTPS (brak wymogu portów przychodzących poza dostępem operatorów):

- `model-api.runcomfy.net` — generacja/edycja obrazów, I2V (klucz `RUNCOMFY_API_KEY`)
- `api.groq.com` — vision LLM Maciusia (klucz `GROQ_API_KEY`)
- `api.baselinker.com` — eksport ofert (token w ustawieniach aplikacji)
- pobrania modeli Hugging Face przy pierwszym starcie rekoloru (~kilka GB cache)

Przychodzący: HTTPS 443 (reverse proxy/ TLS przed Fastify) albo port aplikacji
w sieci wewnętrznej. Domyślny bind `127.0.0.1:8788` — za proxy ustawić host.

## 7. Środowisko deweloperskie (zmierzone, referencja)

| Element | Wartość |
|---|---|
| Node.js | 24.15.0 (wymagane ≥ 22.12 ze względu na `node:sqlite`) |
| Python | 3.14.4 (zakres 3.11–3.14) |
| GPU | GTX 1650 4 GB, CUDA 12.8 — rekolor działa na styk |
| OS | Windows 10/11 + XAMPP jako katalog roboczy (aplikacja jest samodzielna, nie używa Apache/MySQL z XAMPP) |

## 8. Czego NIE trzeba kupować

- Farmy GPU / serwera inferencji do generacji — modele generatywne są w chmurze.
- PostgreSQL/MySQL, Redis, RabbitMQ — SQLite WAL i worker w procesie wystarczą
  na skalę jednego działu przygotowania ofert.
- Osobnego serwera plików/CDN — media serwuje aplikacja z lokalnego wolumenu.

## 9. Otwarte do potwierdzenia z Vilmax (etap wdrożenia)

- Docelowy system serwera (Linux/Windows), domena, polityka TLS i backupu.
- Czy serwer ma/mieć będzie GPU, czy rekolor idzie na osobną maszynę/stację.
- Polityka wysyłania zdjęć hali do chmury AI (RunComfy/Groq) — formalna zgoda.
- Przepustowość łącza na hali (upload surowych zdjęć z telefonu).