Projekt własnyAplikacja webowaPWAWebAssembly5 językówBez backendu
Szachmaty.pl, aplikacja do nauki szachów
To nie jest realizacja dla klienta. To projekt, który zbudowałem dla siebie, a potem udostępniłem za darmo: szachmaty.pl, aplikacja do nauki szachów po polsku, która działa w całości w przeglądarce. Silnik szachowy liczy na Twoim urządzeniu, partie nigdzie nie wychodzą, konta nie ma. Opisuję ją tutaj, bo najuczciwiej pokazuje, co potrafię zrobić z kodem, kiedy nikt nie stawia terminu ani budżetu.
Poniżej cała droga: skąd pomysł, jakie decyzje techniczne podjąłem i dlaczego, co ostatecznie jest w środku, ile mnie to kosztowało błędów oraz co z tego wynika dla firm, które zamawiają u mnie strony.
Ciemny motyw, jedna dominująca ścieżka („Zacznij karierę") i liczby, które od razu mówią, ile tu jest treści. Przewiń całą stronę w ramie albo przełącz na widok telefonu.
Podgląd strony szachmaty.pl na komputerze i telefonie, z możliwością przewinięcia całej strony
Wracałem do szachów jako dorosły, po latach przerwy. Grałem partię, przegrywałem, klikałem „analizuj" i dostawałem ścianę liczb: minus 2,7 piona, potem minus 4,1, potem mat. Wiedziałem, że coś zrobiłem źle. Nie wiedziałem co.
Duże serwisy robią to świetnie dla ludzi, którzy już rozumieją szachy. Dla kogoś, kto zaczyna, są jak kokpit samolotu. Do tego prawie wszystko jest po angielsku, a polskie materiały to zwykle statyczne artykuły: przeczytasz o widełkach i dalej nie umiesz ich zagrać.
Chciałem czegoś prostego: żeby po partii ktoś powiedział mi po polsku jednym zdaniem, gdzie był najdroższy moment, dlaczego to był błąd i dał trzy zadania na dokładnie ten motyw. Nie znalazłem. Więc zbudowałem.
● Zasada prywatności
Zero kont, zero e-maili, pełna swoboda
Nauka szachów nie wymaga oddawania nikomu swoich danych. Wszystkie postępy, partie i statystyki działają w 100% lokalnie na urządzeniu użytkownika.
Decyzje techniczne
Trzy decyzje, które ustawiły cały projekt
Każda z nich była podjęta na starcie i żadnej nie cofałem. To one sprawiły, że projekt w ogóle dowiozłem, zamiast utonąć w infrastrukturze.
01 · ARCHITEKTURA0 zł kosztów stałych
Zero backendu i bazy danych
Postęp lekcji, historia i statystyki siedzą w pamięci przeglądarki (localStorage). Nie da się wyciec danymi, których się nie zbiera. Utrzymanie kosztuje tyle, co hosting plików statycznych.
02 · SILNIK AIWASM · 7 MB
Silnik liczy w przeglądarce
Stockfish 18 (lite z siecią NNUE) działa jako WebAssembly w osobnym wątku roboczym. Liczy na Twoim procesorze, nie obciąża serwera i pozwala na pełną grę offline bez internetu.
03 · DŁUGOWIECZNOŚĆPure ES Modules
Czysty JS bez build stepu
Zero Reacta, zero webpacka. Projekt, którego nie trzeba kompilować, nie przestaje działać za 3 lata przez zdezaktualizowane zależności npm. Kod jest odporny na upływ czasu.
Zakres
Co ostatecznie jest w środku
Kilka modułów, każdy działa samodzielnie, wszystkie dzielą jeden silnik lekcji i jedną szachownicę. Poniżej zrzuty z działającej aplikacji, nie makiety.
Kariera szachisty: 55 przeciwników, siedem rozdziałów
Zamiast suwaka „poziom trudności od 1 do 10" jest drabina postaci. Zaczynasz przy ławce w parku od przeciwnika o sile około 150 punktów Elo, kończysz w panteonie mistrzów powyżej 2750. Każda postać ma charakter i konkretną słabość: jedna bije wszystko, co się rusza, inna wyprowadza hetmana w trzecim ruchu i liczy na mata szewskiego. Boty nie grają losowo, tylko popełniają ludzkie błędy, bo losowy ruch od razu czuć sztucznością.
Wejście do kariery. Trzy ścieżki (początkujący, amator, mistrz) dobierają startowy rozdział do poziomu gracza.
Nauka: 49 lekcji w ośmiu rozdziałach
Od tego, jak chodzą figury, przez matowanie, taktykę, debiuty i końcówki, po podstawy strategii. Lekcja nie jest artykułem: każdy krok to albo pozycja do obejrzenia, albo figura do swobodnego poprzesuwania, albo zadanie do rozwiązania na planszy, albo pytanie. Po dwóch nieudanych próbach dostajesz podpowiedź, a postęp zapisuje się sam.
Nad lekcjami stoi Kurs: dziewięć bloków ułożonych w jedną kolejność, od nawyków przy szachownicy po końcówki. Kolejny blok otwiera się po zaliczeniu poprzedniego, ale nic nie zamyka się z powrotem, bo powtórki są tu całą metodą. Kurs nie ma własnej pamięci postępu, tylko czyta tę samą, z której korzysta reszta aplikacji, więc nie da się doprowadzić do sytuacji, w której dwa ekrany pokazują sprzeczny stan.
Pierwsza lekcja pierwszego rozdziału. Plansza jest aktywna od razu, tekst jest obok, nie zamiast.
Analiza partii z wyjaśnieniami po polsku
Wklejasz zapis partii, wskazujesz plik albo podajesz nazwę użytkownika z Lichess, a aplikacja pobiera ostatnie publiczne partie. Silnik przechodzi partię ruch po ruchu, klasyfikuje każdy ruch, liczy celność (z szansy na wygraną, nie z surowych centypionów) i rysuje wykres przebiegu.
Najważniejsza część jest po prawej: aplikacja wybiera jeden najdroższy moment partii, tłumaczy go jednym zdaniem po polsku („pionek bije na b5, ale ta wymiana jest dla ciebie niekorzystna: tracisz na niej materiał") i proponuje trzy zadania na ten sam motyw. To jest ta funkcja, dla której zacząłem cały projekt.
Analiza jednej partii mówi jednak tylko o tej partii. Dlatego doszedł profil powtarzalnych błędów: aplikacja zbiera wyniki wielu analiz i układa je w jeden ranking według taksonomii 27 typowych pomyłek gracza na poziomie 400–1200 Elo. Zamiast czterdziestu osobnych uwag dostajesz zdanie w rodzaju „trzeci raz w tej partii ruszasz figurą, która już stała dobrze" i kolejność pracy. Ta sama taksonomia karmi potem dobór lekcji i zadań.
Analiza klasycznej partii operowej Morphy'ego. Po prawej: plan nauki wygenerowany z tej konkretnej partii.
Trening: 432 zadania w 69 kategoriach
Zadania pogrupowane po motywach: maty, widełki, związania, szpile, przeciążenie, zugzwang, niedopromocja i kilkadziesiąt innych. Doszły też kategorie, które nie są czystą taktyką: kalkulacja, wybór planu, partie modelowe i końcówki. Rozwiązujesz w dowolnej kolejności i dowolną liczbę razy. Jest też tryb rankingowy, w którym aplikacja sama dobiera trudność do poziomu, oraz osobna kolejka powtórek. Każde zadanie jest sprawdzone programowo: legalność pozycji, legalność rozwiązania i jednoznaczność odpowiedzi.
Przegląd treningu. Każdy kafel pokazuje realną pozycję z puli i postęp w kategorii.
Trener debiutów: 16 repertuarów
System Londyński, Partia Włoska, Caro-Kann, Obrona Słowiańska, Gambit Hetmański i jedenaście innych. Uczysz się ich tak, jak potem zagrasz: Ty wykonujesz swoje ruchy, przeciwnik odpowiada, a błędny ruch jest poprawiany bez przerywania linii. Zamiast zapamiętywania sekwencji dostajesz też krótkie wyjaśnienie, o co w danym otwarciu chodzi.
Repertuary oznaczone kolorem, którym się gra, i poziomem zaawansowania.
Do tego
Gra swobodna i lokalna
Partia z silnikiem na dowolnej sile bez rankingu oraz tryb dwóch osób przy jednym ekranie, na przykład rodzic z dzieckiem.
Pomoce w trakcie gry
Pasek oceny na żywo, podpowiedź w postaci strzałki i jednego zdania, ostrzeżenie przy poważnym błędzie z możliwością cofnięcia. Wszystko wyłączalne.
Historia i statystyki
Wszystkie partie z wynikiem i linkiem do analizy, średnia celność w czasie, rozkład jakości ruchów i sugestia, nad czym popracować.
Działa offline
Po pierwszym wczytaniu aplikacja instaluje się jak program: da się ją dodać do ekranu telefonu i grać w pociągu bez zasięgu, razem z silnikiem.
Własna szachownica
Bez gotowych bibliotek planszy. Autorski zestaw figur w SVG (dwa warianty), przeciąganie i klikanie, trzy motywy kolorystyczne, dźwięki generowane na żywo, bez plików audio.
Pięć wersji językowych
Polski, angielski, francuski, rosyjski i ukraiński. Cała aplikacja, nie tylko menu.
Pakiet dla trenera
23 arkusze i 184 pozycje treningowe ze scenariuszem zajęć na 45 minut i programem na osiem tygodni. Bezpłatny pilotaż, żeby zebrać uwagi od prowadzących, zanim powstanie cokolwiek płatnego.
Galeria mistrzów
20 przystępnych biografii, oś czasu i zestawienia najważniejszych rywalizacji. Każda sylwetka prowadzi do partii z botem zbudowanym wokół podobnej idei gry.
Kopia danych w Twoich rękach
Eksport całego postępu do pliku i import na innym urządzeniu. To jedyna „synchronizacja", jakiej potrzeba, kiedy nie ma kont.
Prywatność i bezpieczeństwo
Najlepszy sposób na ochronę danych to ich nie zbierać
Ta sama zasada, którą stosuję na stronach klientów, tylko doprowadzona do końca, bo tu nikt mi nie kazał iść na kompromis.
Bez konta i bez profilowania
Nie ma rejestracji, logowania ani hasła. Postęp, partie i analizy zostają w pamięci Twojej przeglądarki. Kopia zapasowa to plik, który sam pobierasz.
Statystyki tylko za zgodą
Analityka włącza się dopiero po kliknięciu „Zgadzam się". Bez zgody aplikacja działa tak samo, po prostu nic nie mierzy. Odmowa jest równie łatwa jak zgoda, w jednym kliknięciu.
Twarda polityka treści (CSP)
Zestaw nagłówków bezpieczeństwa opisany w jednym pliku i pilnowany testem automatycznym, który uruchamia prawdziwy silnik pod prawdziwym CSP. Skrypty inline mają liczone skróty, zamiast rozluźniania polityki.
Fonty i silnik na własnym serwerze
Bez Google Fonts i bez zewnętrznych CDN w ścieżce krytycznej. Przeglądarka użytkownika nie melduje się nikomu trzeciemu.
Cały projekt jest pilnowany zestawem 36 plików testów end to end (Playwright), które przeklikują aplikację w przeglądarce: kampanię, lekcje, analizę, tryb offline, dostępność, nagłówki bezpieczeństwa i wersje językowe. Pod nimi stoi jeszcze 128 plików testów jednostkowych na samą logikę: reguły gry, klasyfikację ruchów, detektory błędów, stan kursu. Nie dlatego, że lubię testy, tylko dlatego, że przy projekcie tej wielkości bez nich każda zmiana jest ruletką.
Treść i widoczność
Aplikacja to połowa projektu. Druga połowa to treść.
Najlepsze narzędzie jest nic niewarte, jeśli nikt go nie znajdzie. Obok samej aplikacji powstało kilkadziesiąt stron poradnikowych po polsku: zasady gry, ustawienie szachownicy, roszada, bicie w przelocie, pat i remis, wartość figur, mat szewski, ranking Elo, historia gry, sylwetki mistrzów.
Każda z nich ma jedną rzecz, której nie mają zwykłe artykuły: żywą szachownicę w treści. Nie czytasz o roszadzie, tylko ją wykonujesz na stronie o roszadzie. Jest też arkusz zadań gotowy do wydruku, dla nauczycieli i rodziców.
Do tego doszły cztery katalogi tematyczne: 27 pojęć (powtarzalne błędy początkującego), 15 wzorców matowych, 13 obowiązkowych końcówek i 14 motywów taktycznych. Nie pisałem ich ręcznie: są generowane z tych samych rejestrów, na których pracuje aplikacja, więc nie mogą rozjechać się z jej treścią. Każdy diagram to realna pozycja z lekcji albo zadania, a twierdzenie o niej (że to mat, że to pat, że pion przechodzi) jest przy generowaniu przeliczane programowo, nie przepisywane z pamięci.
Osobno stoi biblioteka wiedzy: 40 autorskich syntez o kalkulacji, końcówkach, strategii i metodyce nauczania, plus dwa przewodniki po ideach z klasyków w domenie publicznej (Capablanca 1921, Steinitz 1889). To syntezy z linkami do skanów w bibliotekach cyfrowych, a nie tłumaczenia ani kopie. Granicę między „przeczytałem i napisałem swoje" a „przepisałem" trzeba przy takim materiale trzymać świadomie i na piśmie.
Razem z wersjami językowymi to 797 adresów w mapie strony. Do tego opis serwisu dla asystentów AI w pliku llms.txt, bo coraz częściej pierwszą odpowiedź na pytanie „jak nauczyć się szachów" daje model, a nie lista wyników.
Przykładowa strona poradnikowa. Treść prowadzi wprost do odpowiedniego modułu aplikacji.
797
adresów w mapie strony
5
wersji językowych całego serwisu
0 zł
koszt dla użytkownika, bez reklam
Uczciwie o błędach
Cztery rzeczy, które poszły źle i czego mnie nauczyły
Case studies zwykle pokazują tylko finał. Ten projekt był mój, więc mogę pokazać też koszty. Wszystkie cztery błędy przełożyły się potem na pracę u klientów.
1. Tłumaczenie maszynowe przetłumaczyło protokół silnika
Cztery wersje językowe powstały skryptem. Skrypt tłumaczył wszystko, co wyglądało na tekst, w tym komendy, którymi aplikacja rozmawia z silnikiem szachowym. Efekt: w wersji francuskiej, rosyjskiej i ukraińskiej silnik przez pewien czas „grał", ale nie widział planszy, bo dostawał polecenia w przetłumaczonym języku. Wyglądało to jak dziwnie słaby przeciwnik, nie jak awaria.
Wniosek: automat nie odróżnia treści od kodu. Od tamtej pory tłumaczenia propaguję ręcznie, a plik z protokołem jest na stałe wyłączony z tłumaczenia. Ta sama lekcja dotyczy każdej wielojęzycznej strony klienta.
2. Tryb offline nie działał, choć wyglądał, że działa
Aplikacja miała mechanizm pracy offline od początku. Podczas audytu okazało się, że lista plików do zapisania w pamięci była niekompletna: pomijała 89 obrazów i ponad połowę modułów. Aplikacja uruchamiała się bez internetu, ale rozsypywała się przy pierwszym wejściu głębiej. Nikt tego nie zgłosił, bo nikt nie testuje offline'u specjalnie.
Wniosek: „działa" i „działa w warunkach, dla których to zbudowano" to dwie różne rzeczy. Dziś tryb offline ma osobny test, który wyłącza sieć i przechodzi aplikację od nowa.
3. Dwa testy świeciły na zielono, nie sprawdzając niczego
W dwóch testach wzorzec wyszukiwania zawierał niewidzialny znak sterujący zamiast zamierzonego symbolu. Testy przechodziły zawsze, niezależnie od tego, co robiła aplikacja. Żadne standardowe narzędzie tego nie pokazuje, bo znak jest niewidoczny w edytorze i w podglądzie różnic.
Wniosek: zielony test to nie dowód. Dowodem jest test, który potrafisz celowo zepsuć i zobaczyć, że zapala się na czerwono. Sprawdzam tak teraz każdy nowy test, u siebie i u klientów.
4. Nowe strony wyglądały poprawnie w kodzie i ładowały się bez stylów
Katalog pojęć powstał generatorem. Generator wstawiał odnośniki do arkuszy stylów i skryptów tak, jak wyglądały na stronach o jeden poziom płycej w strukturze adresów. Nowe strony leżały o poziom głębiej, więc każdy z tych odnośników trafiał w pustkę. Kilkadziesiąt stron wchodziło jako goły tekst, bez wyglądu i bez działających plansz. Testy tego nie widziały, bo sprawdzały treść strony, a nie to, czy zasoby, o które prosi, faktycznie istnieją.
Wniosek: generowanie stron oszczędza czas i dokładnie tak samo skaluje pomyłkę. Każdy generator ma teraz test, który po wygenerowaniu odpytuje realny serwer o każdy zasób z wygenerowanej strony i wymaga odpowiedzi 200. Ta sama zasada dotyczy każdej strony klienta, która powstaje z szablonu.
Projekt w liczbach
Skala, bez zaokrągleń w górę
49
interaktywnych lekcji w 8 rozdziałach
432
zadania treningowe w 69 kategoriach
55
przeciwników z własnym charakterem
16
repertuarów debiutowych
40
autorskich syntez w bibliotece wiedzy
188
modułów JavaScript, około 30 tys. linii
36
plików testów end to end
128
plików testów jednostkowych
797
adresów w mapie strony
Zrealizowane elementy
Autorska szachownica (SVG, bez bibliotek)Stockfish 18 w WebAssembly10 poziomów siły gryKampania 55 przeciwników49 lekcji interaktywnychKurs w 9 blokach z miękką bramką432 zadania w 69 kategoriachTrening rankingowy i powtórki16 repertuarów debiutowychAnaliza partii z klasyfikacją ruchówWyjaśnienia błędów po polskuProfil 27 powtarzalnych błędówImport PGN i import z LichessWykres przebiegu oceny partiiHistoria partii i statystykiEksport i import kopii danychTryb offline (PWA)Instalacja na ekranie telefonuDźwięki generowane w Web Audio3 motywy planszy, 2 zestawy figur5 wersji językowychKilkadziesiąt stron poradnikowych4 klastry tematyczne generowane z danychBiblioteka 40 syntez wiedzy20 biografii mistrzów i oś czasuArkusz zadań do drukuPakiet dla trenera (23 arkusze)Zgoda na statystyki (opt-in)Nagłówki bezpieczeństwa i CSP36 plików testów Playwright128 plików testów jednostkowych
Wsparcie
Aplikacja jest darmowa i taka zostanie
Nie ma reklam, nie ma wersji premium, nie ma sprzedaży danych, bo nie ma żadnych danych do sprzedania. Utrzymanie to hosting i domena, a rozwój to mój czas po godzinach.
Jeśli komuś ta aplikacja realnie pomogła i chce, żeby powstawało więcej lekcji i zadań, może wesprzeć projekt na Patronite. To dobrowolne i nic nie odblokowuje: wszystko, co jest w aplikacji, zostaje dostępne dla wszystkich za darmo.
Portfolio pełne stron wizytówkowych nie mówi, co się stanie, gdy projekt zrobi się trudny. Szachmaty mówią. To był projekt bez klienta, bez terminu i bez litości: własny silnik prezentacji planszy, obliczenia w przeglądarce, pięć języków, tryb offline i kilkaset stron treści, wszystko utrzymane bez frameworka i bez serwera aplikacji.
Te same zasady wchodzą do każdego projektu komercyjnego: kod bez zbędnych zależności, dane traktowane poważnie, wydajność mierzona, a nie deklarowana, treść pisana pod realne pytania ludzi. Różnica polega tylko na tym, że u klienta celem jest telefon albo rezerwacja, a nie nauczenie kogoś roszady.
Jeśli szukasz kogoś, kto potrafi zbudować nie tylko stronę, ale też działające narzędzie, to jest mój najlepszy dowód.
Strona firmowa zaczyna się u mnie od 2 499 zł netto, prosta wizytówka od 1 299 zł netto, a własny system (rezerwacje, kartoteka klientów, kalkulatory) wyceniam indywidualnie.