HIGI · specyfikacja techniczna

Specyfikacja aplikacji HIGI (higi.com.pl)

25 czerwca 2026 · na potrzeby oceny prawnej (AI Act + RODO) i marketingu · dokument wewnętrzny

1. Streszczenie wykonawcze

HIGI to aplikacja w przeglądarce dla higienistek stomatologicznych. Na podstawie ankiety o stanie zębów i nawykach pacjenta generuje spersonalizowany plan higieny jamy ustnej (co kupić, czego używać, jak często, w jakiej kolejności). Plan powstaje po stronie higienistki, która prowadzi pacjenta przez ankietę, przegląda wynik i przekazuje go pacjentowi (wydruk / PDF).

Cztery fakty kluczowe dla oceny prawnej:

(1) Brak AI. Silnik generujący plan jest w 100% deterministyczny — reguły „jeśli–to” napisane ręcznie w arkuszu kalkulacyjnym. Zero sztucznej inteligencji, uczenia maszynowego, modeli językowych, profilowania czy scoringu ryzyka. Kluczowe dla AI Act.
(2) Dane pacjenta tylko w przeglądarce. Odpowiedzi pacjenta i plan żyją wyłącznie w przeglądarce (pamięć lokalna). Nie są wysyłane na serwer ani do strony trzeciej. Po stronie serwera nie ma danych zdrowotnych pacjenta (art. 9 RODO).
(3) Na serwerze tylko dane firmowe. Serwer przechowuje dane konta higienistki/gabinetu (imię, e-mail, rola; dla gabinetów NIP i adres do faktury) oraz treści szablonów tworzone przez higienistki. To zwykłe dane B2B.
(4) Podprocesorzy uregulowani. Logowanie (Clerk), hosting (Cloudflare), płatności (Stripe), maile (Resend) — na umowach powierzenia; transfery do USA na mechanizmach DPF/SCC. Baza danych (Cloudflare D1) w UE.

2. Czym jest HIGI (opis funkcjonalny)

Dla kogo: higienistka stomatologiczna prowadząca własną praktykę lub pracująca w gabinecie. Pacjent nie jest użytkownikiem konta — jest osobą, dla której higienistka generuje plan.

Przepływ działania:

Higienistka loguje się do aplikacji (konto przez Clerk).
Prowadzi pacjenta przez ankietę: ~50 pytań warunkowych (kolejne pytanie zależnie od wcześniejszej odpowiedzi).
Silnik mechanicznie mapuje odpowiedzi na bloki treści i składa plan w 10 sekcjach: Wstęp, 13 Zasad, Diagnoza, Styl życia, Higiena poranna, Higiena wieczorna, Produkty, Lista zakupów, Wizyty, Kontakt.
Higienistka przegląda plan i przekazuje pacjentowi: kopiuje tekst, drukuje lub zapisuje PDF (wszystko po stronie przeglądarki).

Stan produkcyjny: na produkcji higienistka NIE edytuje treści wygenerowanych bloków planu — zakładka „Edytor” informuje, że funkcja edycji pojawi się w kolejnej iteracji. Higienistka steruje przepływem, przegląda wynik, ustawia dane gabinetu i drukuje. Edytor treści jest w przygotowaniu (środowisko dev).

Role w systemie

Rola	Opis
Higienistka solo	Samodzielna praktyka; własne konto, własny dostęp.
Gabinet (organizacja)	Właściciel + zaproszeni członkowie; dostęp dziedziczony. Funkcja w przygotowaniu (dev).
Super-admin	4 adresy e-mail z listy (twardo w kodzie) + ewentualnie nadani przez panel; zarządzają treścią, dostępem, mailami.

3. Status: produkcja vs środowisko deweloperskie

Rozdzielamy, co działa na produkcji (higi.com.pl), a co jest w przygotowaniu na dev i jeszcze nie zostało wdrożone na produkcję.

Funkcja	Status
Pacjencki silnik ankieta→plan (deterministyczny, w przeglądarce)	PRODUKCJA
Logowanie higienistki + konto + brama dostępu	PRODUKCJA
Konta gabinetów (organizacje Clerk, zaproszenia, dziedziczenie dostępu)	DEV
Edytor treści ankiety/planu zapisywany na serwer (szablony)	DEV
System maili transakcyjnych (Resend) + przypomnienia	DEV (tryb próbny)
NIP gabinetu jako kotwica + dane do faktury	DEV
Weryfikacja telefonu higienistki solo (Clerk SMS) jako kotwica anty-abuse	DEV — przygotowane, NIEAKTYWNE (czeka na konfigurację Clerk SMS)
Płatności kartą (Stripe)	przygotowane, nieaktywne

Specyfikacja opisuje cały system (produkcja + bliski roadmap), aby prawnik mógł ocenić także funkcje wchodzące (zwłaszcza przechowywanie NIP i maile), będące przedmiotem przygotowywanej klauzuli RODO.

4. Architektura techniczna

Komponenty

Warstwa	Technologia	Rola
Front pacjenta (legacy)	Czysty JavaScript/HTML + SheetJS (xlsx) + html2pdf	Ankieta i generowanie planu w przeglądarce. Bez komunikacji z serwerem poza pobraniem pliku reguł.
Front higienistki/admina	React + TypeScript + Vite	Logowanie, konto, panel gabinetu/admina. Wysyła dane konta do serwera.
Serwer (API)	Cloudflare Workers (Hono)	~40 endpointów: konto, autoryzacja, szablony, organizacje, maile, billing. Każdy wymaga JWT Clerk.
Baza danych	Cloudflare D1 (SQLite) — region Europa Wschodnia (EEUR)	Dane konta/gabinetu, szablony treści, konfiguracja, logi maili, audyt. Bez danych pacjenta. Szczegóły rezydencji: sekcja 6.6.
Sesje / cache	Cloudflare KV	Dane techniczne sesji/cache.
Tożsamość/logowanie	Clerk (zewn.)	Hasła, 2FA, sesje, organizacje. JWT RS256/JWKS, weryfikowany offline na Workerze.
Płatności	Stripe (zewn.)	Billing, webhooki (nieaktywne na produkcji).
Maile	Resend (zewn.)	Maile transakcyjne (tryb próbny na dev).

Granica danych (kluczowa)

PRZEGLĄDARKA PACJENTA → [ankieta + plan: pamięć lokalna, wydruk/PDF] ✗ nie wychodzi na serwer

PRZEGLĄDARKA HIGIENISTKI → [dane konta, NIP, szablony] → SERWER (Worker → D1, region Europa Wschodnia) + Clerk (USA) / Stripe / Resend

5. Silnik planu — analiza pod AI Act

Jak działa silnik (fakty z kodu)

Determinizm: te same odpowiedzi zawsze dają ten sam plan. Logika to czyste funkcje dopasowujące warunki (wzorce „P*.* → wartość”). Brak losowości, brak adaptacji. Dowód: apps/legacy/lib/app.js:160–181, 264–291.
Źródło reguł: cała logika z arkusza Excel (ANKIETA-FINAL-2026-05-03-v7-ZATWIERDZONA-DOMI.xlsx) napisanego ręcznie przez zespół; wczytywany lokalnie w przeglądarce (SheetJS). Dowód: apps/legacy/lib/excel-parser.js:247–272.
Brak ML/LLM: brak wywołań do modeli AI, brak sieci neuronowych, brak uczenia. Jedyne połączenie sieciowe to pobranie pliku z regułami.
Brak profilowania/scoringu: brak punktacji, oceny ryzyka choroby, budowania profilu. Tylko reguły „jeśli wybrano opcję X, pokaż blok Y”.

Analiza pomocnicza pod AI Act (do potwierdzenia przez prawnika)

Rozporządzenie (UE) 2024/1689 (AI Act), art. 3 ust. 1, definiuje „system AI” jako system maszynowy, który WNIOSKUJE (infers) na podstawie danych wejściowych, jak generować wyniki, i może wykazywać zdolność adaptacji. Motyw 12 oraz wytyczne Komisji (luty 2025) wyłączają z tej definicji systemy oparte wyłącznie na regułach zdefiniowanych przez człowieka — klasyczne systemy regułowe bez „wnioskowania” w sensie uczenia maszynowego.

Wniosek pomocniczy: silnik HIGI NIE spełnia definicji „systemu AI” i pozostaje poza zakresem AI Act — nie wymaga klasyfikacji ryzyka ani obowiązków z AI Act. Reguły napisane przez człowieka, brak wnioskowania ML, brak adaptacji, brak autonomii (higienistka steruje całym przepływem). Decyzja ostateczna należy do prawnika.

Co mogłoby to zmienić: dodanie modelu ML/LLM do generowania lub personalizacji planu, automatyczna ocena ryzyka choroby, albo element uczący się na danych. Dopóki silnik pozostaje deterministycznym drzewem reguł — analiza się nie zmienia.

6. Dane osobowe — analiza pod RODO

Mapa danych

Kategoria danych	Gdzie	Na serwerze?	Podstawa (wstępnie)
Odpowiedzi pacjenta + plan (dane o zdrowiu, art. 9)	Wyłącznie przeglądarka	NIE	Nie dotyczy serwera — nie przetwarzamy serwerowo
Imię pacjenta + data wizyty (wpisane przez higienistkę)	Wyłącznie przeglądarka	NIE	Pozostają u higienistki (administrator: gabinet)
Konto higienistki: imię, e-mail	Serwer (D1) + Clerk	TAK	art. 6 ust. 1 lit. b (umowa)
Gabinet: nazwa, adres, NIP	Serwer (D1)	TAK (dev)	art. 6 ust. 1 lit. c (podatki) + lit. f (anty-abuse)
Telefon higienistki solo (weryfikacja + anty-abuse)	Clerk (SMS/OTP) + serwer (D1: numer E.164)	TAK (dev, planowane)	art. 6 ust. 1 lit. b (dostęp do usługi) + lit. f (anty-abuse)
Treść szablonów ankiet/planów (higienistki)	Serwer (D1)	TAK (dev)	art. 6 ust. 1 lit. b
Dane techniczne: identyfikatory Clerk/Stripe, sesje, audyt	Serwer + Clerk/Stripe	TAK	art. 6 ust. 1 lit. b/f
Logi maili (do higienistek, nie pacjentów)	Serwer (D1) + Resend	TAK (dev)	art. 6 ust. 1 lit. b/f

Dane szczególnej kategorii (art. 9 — zdrowie)

Najtrudniejsza część RODO — dane o zdrowiu pacjenta — NIE jest przetwarzana po stronie serwera HIGI. Odpowiedzi ankiety i plan żyją tylko w przeglądarce higienistki. Żadna z 8 tabel bazy nie przechowuje danych pacjenta (zweryfikowano w migracjach schematu). To architektonicznie wycina obowiązki z art. 9 po stronie operatora (brak rejestru czynności na danych zdrowotnych, brak DPIA dla danych pacjenta, brak powierzenia danych zdrowotnych pacjenta podprocesorom).

Administratorem danych pacjenta (trzymanych lokalnie przez higienistkę) jest higienistka/gabinet w ramach własnej praktyki, nie HIGI — do potwierdzenia w regulaminie przez prawnika.

Podprocesorzy

Podprocesor	Funkcja	Jakie dane widzi	Transfer / lokalizacja
Cloudflare	Hosting, Workers, D1, KV, Pages	Dane konta/gabinetu, szablony, logi	D1: region Europa Wschodnia (bez twardej blokady UE); KV: globalny; firma USA — DPA + SCC (patrz 6.6)
Clerk	Logowanie, tożsamość, organizacje, weryfikacja telefonu (SMS/OTP)	E-mail, imię, identyfikator, rola, struktura gabinetu, numer telefonu (przy weryfikacji solo)	USA — DPF/SCC + DPA
Stripe	Płatności (nieaktywne na prod)	Dane rozliczeniowe, identyfikator klienta	USA — DPF/SCC + DPA
Resend	Maile transakcyjne (dev, próbny)	E-mail higienistki/gabinetu + treść maila	USA — DPF/SCC + DPA

Do potwierdzenia z prawnikiem

Umowy powierzenia (DPA) z podprocesorami + rejestr czynności przetwarzania (art. 30).
Polityka prywatności wymieniająca podprocesorów i transfery do USA (DPF/SCC).
Klauzula informacyjna + test równowagi (uzasadniony interes) dla NIP — projekt już przygotowany (dokument KLAUZULA-RODO-NIP).
Okresy retencji: NIP/faktury — wg prawa podatkowego (zasadniczo 5 lat); audyt — do ustalenia.
Potwierdzenie ról: HIGI = administrator danych konta; higienistka/gabinet = administrator danych pacjenta (lokalnie).

Weryfikacja tożsamości i przeciwdziałanie nadużyciom (telefon + NIP)

Aby jeden podmiot nie zakładał wielu kont w celu wielokrotnego wykorzystania darmowego okresu, HIGI stosuje model „jednej kotwicy” — różny dla dwóch typów klienta. To świadoma decyzja o przetwarzaniu danych, istotna dla oceny RODO.

Higienistka solo — kotwica = numer telefonu:

Mechanizm: weryfikacja numeru kodem SMS (jednorazowy kod) realizowana przez Clerk. Clerk przechowuje numer i potwierdza poprawność; nasz serwer odczytuje status „zweryfikowany”.
Zasada dostępu: jeśli numer nie został potwierdzony, konto NIE otrzymuje darmowego dostępu (wariant „twardy”) — zabezpieczenie przed wieloma kontami na ten sam numer.
Co trafia na serwer: w naszej bazie (tabela trial_anchor) zapisywany jest ZNORMALIZOWANY numer w formacie międzynarodowym (E.164, np. +48XXXXXXXXX) jako klucz „jeden numer = jeden darmowy okres”. Uwaga dla prawnika: numer jest przechowywany jawnie (nie zahaszowany) — do rozważenia zapis wyłącznie skrótu (hash) numeru dla minimalizacji danych.
Podstawa: art. 6 ust. 1 lit. b (umowa) + lit. f (anty-abuse). Wymaga klauzuli informacyjnej i testu równowagi.
Status: funkcja PRZYGOTOWANA, ale NIEAKTYWNA — flaga wyłączona, czeka na konfigurację SMS w Clerk. Na produkcji jeszcze nie działa.

Gabinet — kotwica = NIP: NIP identyfikuje gabinet i służy jako kotwica „jeden NIP = jeden darmowy okres” (unikalny indeks) oraz dana do faktury. Podstawa: art. 6 ust. 1 lit. c (podatki) + lit. f (anty-abuse). Projekt klauzuli informacyjnej dla NIP — osobny dokument KLAUZULA-RODO-NIP.

Telefon (solo) i NIP (gabinet) to dwie kotwice tego samego mechanizmu anty-abuse. Oba to dane osobowe / identyfikujące i wymagają podstawy prawnej oraz klauzuli informacyjnej — do potwierdzenia przez prawnika.

Rezydencja danych — gdzie fizycznie leżą dane (zweryfikowane 25.06.2026)

Zweryfikowaliśmy region przechowywania każdego systemu — z konfiguracji (nasza baza) i z aktualnej dokumentacji dostawców.

Najważniejsze: żaden system nie przechowuje danych „tylko w Polsce”. Dane konta są dziś w regionie Cloudflare „Europa Wschodnia” (UE), logowanie (Clerk) fizycznie w USA, a dane pacjenta — nigdzie na serwerze (tylko w przeglądarce).

System	Jakie dane	Gdzie fizycznie	W UE?	Jak wymusić UE / uwaga
Cloudflare D1	Konto, NIP, kotwica-telefon, szablony	Region „Europa Wschodnia” (EEUR)	Dziś TAK, bez twardej blokady	Odtworzyć bazę z `jurisdiction='eu'` (tylko przy tworzeniu, nieodwracalne) — twarda gwarancja UE
Cloudflare KV	Snapshot treści, cache	Globalnie (cały świat)	NIE	Brak opcji UE — nie trzymać tam danych osobowych (trzymać w D1)
Cloudflare Workers	Przetwarzanie przejściowe (nic nie składuje)	Brzeg sieci najbliżej użytkownika	ZALEŻY — dla PL w UE	Regional Services (Enterprise) — dotyczy ruchu, nie składowania
Cloudflare Pages	Statyczny front (bez danych osobowych)	Globalny CDN	bez znaczenia	n/d — brak danych osobowych
Clerk	Logowanie: e-mail, imię, hasło, telefon	USA (San Francisco; GCP w USA)	NIE — USA	Brak opcji UE na żadnym planie; transfer na DPF + SCC + DPA
Stripe (nieaktywne)	Dane rozliczeniowe (gdy włączone)	USA (rdzeń); kontrakt przez Irlandię	NIE	Brak opcji UE; nadzór: irlandzki DPC; DPF + SCC
Resend (nieaktywne)	E-mail higienistki + treść maila (gdy włączone)	USA (AWS w USA)	NIE	Region wysyłki ≠ składowanie; brak rezydencji UE; DPF + SCC

Wnioski i rekomendacje (do decyzji prawnika / Bartosza)

(1) D1 — utwardzić rezydencję: dane konta (NIP, kotwica-telefon) są dziś w UE z preferencji lokalizacji, ale Cloudflare nie zobowiązał się umownie utrzymać ich w UE. Dla twardej gwarancji RODO rozważyć odtworzenie bazy z jurisdiction='eu' (nieodwracalne — nowa baza + migracja).
(2) KV — nie dla danych osobowych: KV jest globalny i nie da się go zamknąć w UE. Trzymać tam tylko dane nie-osobowe (publiczny snapshot treści), wszystkie dane osobowe w D1.
(3) Clerk — USA: logowanie (w tym numer telefonu z weryfikacji) leży w USA bez opcji rezydencji UE. Albo akceptujemy transfer na DPF + SCC (standard), albo — jeśli wymagana rezydencja wyłącznie w UE — rozważyć dostawcę tożsamości z europejską rezydencją.
(4) Stripe / Resend — przy włączeniu: oba to firmy z USA, dane w USA. Dziś nieaktywne. Przed włączeniem: DPA + opis transferu w polityce prywatności.
(5) Podstawa transferów do USA: wszyscy czterej dostawcy to firmy z USA (m.in. CLOUD Act). Podstawa EU→USA: EU-U.S. Data Privacy Framework (DPF) + Standardowe Klauzule Umowne (SCC) + umowy powierzenia (DPA) — standard, do udokumentowania w rejestrze czynności i polityce prywatności.

Źródła (zweryfikowane 25.06.2026): Cloudflare D1 Data location + changelog jurisdykcji (2025-11-05), Workers KV (how-kv-works/FAQ), Cloudflare Trust Hub; Clerk GDPR/DPA/Subprocessors; Stripe Privacy Center/DPA/DPF; Resend Regions/DPA/Subprocessors.

7. Bezpieczeństwo i dostęp

Uwierzytelnianie: Clerk, token JWT RS256, weryfikowany na serwerze (JWKS). Każdy endpoint API wymaga ważnego tokenu.
Autoryzacja: brama dostępu rozstrzygana po stronie serwera (dostęp / wybór planu / płatność), nie w przeglądarce — nie do obejścia z front-endu.
Admin: rola super-admina = lista 4 adresów e-mail twardo w kodzie (plus ewentualnie z panelu). Brak automatycznego nadawania uprawnień.
Sekrety: klucze (Clerk, Stripe, Resend) jako sekrety platformy (wrangler secret), nie w repozytorium.
Brak śledzenia: zero analityki i trackerów po stronie pacjenta; jedyne zasoby zewnętrzne to biblioteki techniczne z CDN.
Transmisja: HTTPS; dane pacjenta nie opuszczają urządzenia.

8. Aplikacja a wyrób medyczny (skrót)

Osobna kwestia od AI Act. Wstępna analiza (osobny dokument — research wejścia na rynki): przy pozycjonowaniu EDUKACYJNO-PROFILAKTYCZNYM, z higienistką jako profesjonalistą prowadzącym proces i bez treści diagnostycznych, HIGI najprawdopodobniej pozostaje POZA definicją wyrobu medycznego. W UE (MDR) jest to jednak „szare pole” — zalecana pisemna opinia prawnika MedTech przed marketingiem o charakterze klinicznym. Co przesuwa w stronę wyrobu: claimy diagnozy/leczenia, ocena ryzyka jako wynik kliniczny, albo plan trafiający do pacjenta bez udziału higienistki.

9. Wskazówki dla marketingu

Sposób komunikacji wpływa na kwalifikację prawną (wyrób medyczny) i na uczciwość przekazu. Zasada: pozycjonujemy HIGI jako narzędzie EDUKACYJNO-PROFILAKTYCZNE i organizacyjne dla higienistki, nie diagnostyczne/lecznicze.

Co MOŻNA mówić

„Spersonalizowany plan higieny jamy ustnej / profilaktyki” przygotowywany przez higienistkę.
„Narzędzie, które pomaga higienistce ułożyć i przekazać pacjentowi zalecenia higieniczne (co kupić, jak myć, jak często).”
„Edukacja i profilaktyka”, „wsparcie pracy higienistki”, „oszczędność czasu”.
„Dane pacjenta zostają w przeglądarce — nie wysyłamy ich na serwer” (prawda i mocny atut).

Czego UNIKAĆ

„Diagnoza”, „wykrywa próchnicę/paradontozę”, „leczy”, „ocena ryzyka choroby” — przesuwa w stronę wyrobu medycznego.
Sugestii, że aplikacja zastępuje higienistkę/stomatologa, albo że plan idzie wprost do pacjenta bez profesjonalisty.
Słowa „sztuczna inteligencja / AI” jako cechy silnika — bo to nieprawda (silnik jest regułowy) i niepotrzebnie wzbudza pytania o AI Act.

10. Wykaz źródeł (pliki kodu)

Dokument oparto na odczycie m.in.: apps/legacy/lib/app.js, apps/legacy/lib/excel-parser.js, apps/legacy/ankieta/, apps/workers/migrations/0001–0008 (pełny schemat D1 — zweryfikowano brak danych pacjenta), apps/workers/src/features/ (account, auth, admin, billing, content, email, org, templates), apps/web/src, wrangler.toml. Stan na 25 czerwca 2026.