Od luźnego pomysłu do mapy na żywo: mój własny „ZONE ONE” z Claude Code i serwerem Mikrus

Piotr Zagorowski / / Porady, Mikroblog

Zbudowanie aplikacji, która rozwiązuje Twój własny problem, jeszcze nigdy nie było tak proste. Miałem tylko link, dwie nazwy stacji i dopisek „jeśli to nie byłoby za dużo”. Z tego powstała szczegółowa specyfikacja, a jedno popołudnie później na własnej domenie działała mapa na żywo mojego zakątka Londynu. Każdy pociąg metra, autobus i samolot na niej jest prawdziwy i się porusza.

Oto jak to wyglądało, od pierwszej mglistej wiadomości do wdrożonej aplikacji. Opowiem o specyfikacji, budowaniu krok po kroku, otwartych danych, które to umożliwiły, i małym polskim serwerze VPS, na którym to wszystko działa.

Zaczęło się, jak większość rzeczy tutaj, od kawy i przewijania ekranu.

Wąchanie ziaren: odkrycie ZONE ONE

Pewnego wieczoru trafiłem na ZONE ONE autorstwa Jamesa Pottera. To mapa centralnego Londynu na żywo, na której każdy pociąg metra, autobus, pociąg dalekobieżny, tramwaj wodny i samolot jest prawdziwy i porusza się w czasie rzeczywistym. Najedź na pociąg, a zobaczysz, dokąd jedzie. Kliknij stację, a dostaniesz tablicę odjazdów. Kliknij kamerę drogową, a zobaczysz obraz na żywo.

Gapiłem się w nią zdecydowanie za długo. A potem pojawiła się oczywista myśl: chcę to mieć, ale dla miejsca, w którym mieszkamy.

Centralny Londyn jest piękny, ale moja rodzina nie czeka na autobusy przy Oxford Circus. Czekamy na nie w Loughton, Buckhurst Hill i Woodford, na samym północno-wschodnim końcu linii Central, tam gdzie Londyn zamienia się w hrabstwo Essex i Las Epping.


Dlaczego tego chcieliśmy: patrzeć, jak „nasz” autobus jedzie (albo nie)

Jest takie bardzo konkretne uczucie, które znamy z Krakowa. Miasto ma aplikację „KRK pod ręką”, która pokazuje na mapie komunikację miejską w ruchu. Kiedy tam jesteśmy, korzystamy z niej cały czas. Stoisz na przystanku, otwierasz mapę i patrzysz, jak Twój tramwaj albo autobus czołga się w Twoją stronę. Czasem jedzie. Czasem stoi na tym samym skrzyżowaniu przez cztery minuty, ale przynajmniej wiesz, dlaczego wciąż stoisz w deszczu. 🙂

Odliczanie na tablicy przystankowej to jedno. Zobaczenie prawdziwego pojazdu na prawdziwej ulicy to coś innego: uspokaja, jest uczciwe, a dzieci to uwielbiają.

Celem nigdy więc nie było „odtworzenie ZONE ONE”. Był prostszy i bardziej osobisty:

Założenie w jednym zdaniu: mapa na żywo naszego kawałka Londynu, zbudowana dla mnie i mojej rodziny, żebyśmy widzieli, jak jedzie nasz autobus i nasz pociąg metra.


Najbardziej mglisty przepis w historii: moja pierwsza „specyfikacja”

Oto wszystko, co na początku dałem Claude Code. To aż trochę wstyd, nie poprawiałem tego na potrzeby bloga:

I wonder what would it take to replicate this project:

https://london.jamespotter.dev/

[ZONE ONE description and data credits pasted from the site]

But done for the section containing:

- Loughton
- Buckhurst Hill
And if that would not be too much
Up to
- South Woodford

I tyle: link, wklejony opis, trzy nazwy stacji i odrobina wahania.


Mielenie ziaren: od mglistego pomysłu do szczegółowej specyfikacji

To ta część zaskoczyła mnie najbardziej. Dzisiejsze modele są na tyle dobre, że mglista instrukcja i krótka rozmowa zamieniają się w prawdziwą, szczegółową specyfikację. Nie chodzi mi o ogólnikowe „oto plan”. Chodzi o specyfikację, na podstawie której da się coś zbudować.

Claude nie zgadywał. Poszedł i sprawdził działające API, a potem zapisał, co znalazł. Powstały w ten sposób SPEC.md zawiera między innymi:

  • Dokładny obszar: prostokąt o wymiarach około 7,5 km × 5,2 km od Debden do South Woodford, plus 1 km marginesu, żeby pojazdy wjeżdżały z krawędzi zamiast pojawiać się znikąd.
  • Które warstwy ZONE ONE mają tu sens. Pociągi metra, autobusy, samoloty i kamery drogowe: tak. Tramwaje wodne: nie, bo rzeka Roding nie jest żeglowna. Śledzenie statków: „Nie ma czego śledzić”. Przy tym się zaśmiałem.
  • Dziennik badań z prawdziwymi wywołaniami API i zmierzonymi liczbami. Jedno wywołanie endpointu TfL dla linii Central zwróciło 559 prognoz dla 54 pociągów (524 KB). W naszej okolicy znalazł 328 przystanków autobusowych i około 20 regularnych linii, a w całym Londynie około 890 kamer drogowych.
  • Dziwactwa znalezione w prawdziwych danych. Na przykład czasem brakuje pola direction (45 z 559 prognoz), a tekst „obecnej lokalizacji” tego samego pociągu różni się w zależności od tego, o którą stację zapytasz.
  • Najtrudniejsza część, rozpisana krok po kroku: algorytmy pozycjonowania. TfL nie podaje pozycji GPS pociągów metra, tylko prognozy w stylu „przyjedzie na stację X za N sekund”. Specyfikacja wyjaśnia, jak zamienić je na płynną pozycję na prawdziwym torze, łącznie z podchwytliwym rozwidleniem w Woodford, gdzie pociągi na pętlę Hainault odbijają od pociągów do Epping.
  • Ryzyka, kamienie milowe, testy i licencje: w tym zasada, że pociągi nigdy nie mogą jechać do tyłu i nigdy nie mogą być narysowane dalej niż 50 m od toru.

Najpierw rozmowa, potem polecenia

Spisał też otwarte decyzje dla mnie (czy uwzględnić linię Overground, gdzie hostować, czy pokazywać autobusy z Essex spoza TfL), czyli dokładnie to, co zrobiłby dobry kolega z zespołu.

Wskazówka: traktuj model jak doświadczonego inżyniera, któremu przy kawie opowiadasz o zadaniu. Mglisty opis jest w porządku, pod warunkiem że odpowiadasz na jego pytania i pozwalasz mu przyjrzeć się prawdziwym danym, zanim cokolwiek zapisze.

I najważniejsze: specyfikacja wystarczyła do zbudowania aplikacji. Nie musiałem w kółko tłumaczyć, o co mi chodzi. Kiedy wracałem później do projektu, specyfikacja była jedynym źródłem prawdy dla nas obu.


W międzyczasie przy kawiarnianej ladzie: konfiguracja serwera Mikrus

Kiedy Claude był zajęty badaniem i pisaniem specyfikacji, ja zrobiłem swoją część równolegle: zorganizowałem miejsce, w którym to wszystko będzie mieszkać.

Wybrałem Mikrusa, małą usługę VPS prowadzoną przez Jakuba Mrugalskiego. Jeśli interesujesz się technologią w Polsce, prawie na pewno o nim słyszałeś. Mikrus jest tani, prosty i stworzony właśnie do takich hobbystycznych projektów.

Jest kilka dziwactw, o których warto wiedzieć:

  • Każdy serwer to nieuprzywilejowany kontener LXC, więc nie ma modułów jądra ani zmian w sysctl.
  • Działa przede wszystkim na IPv6. Na współdzielonym IPv4 dostajesz kilka przydzielonych portów (na przykład 20000+ID i 30000+ID) zamiast 80 i 443.
  • W zamian dostajesz darmową subdomenę *.mikrus.cloud z HTTPS, a z Cytrusem możesz podpiąć własną domenę.

Prawdziwą rewolucją jest jednak serwer MCP Mikrusa.

Co to jest MCP? Model Context Protocol to standardowy sposób na danie asystentowi AI narzędzi. Serwer MCP Mikrusa daje Claude’owi narzędzia takie jak exec (uruchom polecenie na serwerze), upload, porty (sprawdź swoje publiczne porty) i domains.

Oto kolejność wydarzeń, wszystko w czasie, gdy Claude pisał specyfikację:

  1. Kupiłem nowy VPS.
  2. Włączyłem serwer MCP w panelu Mikrusa.
  3. Dodałem go do Claude Code razem ze skillem Mikrusa (krótkim przewodnikiem po zasadach platformy: ograniczenia LXC, IPv6, który port odpowiada któremu adresowi URL).

Zanim więc specyfikacja była gotowa, Claude miał już dostęp do serwera. Nie musiałem niczego kopiować ani łączyć się nigdzie przez SSH. Wdrożenie było po prostu kolejnym krokiem w planie.

Pierwsze wdrożenie wylądowało 15 minut po pierwszym commicie. Usługa w Node działa pod systemd, a mały skrypt scripts/deploy.py buduje aplikację, wysyła ją przez MCP, przełącza wersję i restartuje usługę. Później dodałem własną domenę, map.zagor.org, przez Cytrusa Mikrusa, z DNS w Cloudflare. Sprawdziliśmy też restart serwera: mapa wróciła sama około 7 sekund po uruchomieniu.

Moje zdanie: MCP od dostawcy hostingu to dar z nieba. Zamienia „a potem spędzę wieczór na wdrożeniu” w „wdrożone, oto link”. Jeśli Twój dostawca VPS jeszcze go nie oferuje, poproś o to.


Single origin: dlaczego Londyn to raj otwartych danych transportowych

Krótkie wyrazy uznania, bo bez tego nic by nie zadziałało: Londyn ma jedno z najlepszych na świecie cyfrowych pokryć komunikacji miejskiej. Prawie wszystko, czego można chcieć, jest otwarte, udokumentowane i darmowe:

  • TfL Unified API: metro, autobusy, Overground, kolejność przystanków i kamery drogowe (JamCams). Darmowy klucz daje 500 zapytań na minutę. Jedno wywołanie zwraca wszystkie prognozy dla całej linii Central. Aplikacja wykonuje łącznie około 12 zapytań do TfL na minutę, bez względu na to, czy patrzy na nią jedna osoba, czy sto, bo serwer wszystko buforuje i przesyła strumieniem do przeglądarek.
  • Bus Open Data Service (BODS): krajowe dane autobusowe Ministerstwa Transportu dla Anglii, z prawdziwymi pozycjami GPS. Specyfikacja oznaczyła jako otwarte pytanie, czy londyńskie autobusy w ogóle tam są. Szybki test dał odpowiedź: są. Jedno wywołanie dla naszego obszaru zwróciło około 160 autobusów. Ich numery rejestracyjne zgadzają się z identyfikatorami pojazdów w TfL, więc oba źródła łączą się bezpośrednio. Dzięki temu pojawili się też przewoźnicy z Essex spoza TfL (Arriva, Stephensons, autokary National Express), których TfL nie obejmuje.
  • OpenStreetMap: prawdziwa geometria torów, z osobno zmapowanymi torami linii Central w kierunku wschodnim i zachodnim, ponumerowanymi peronami, a nawet bocznicami w Loughton.
  • adsb.lol + adsbdb: społecznościowe śledzenie samolotów. Nad naszą okolicą jest duży ruch do Stansted, City i Heathrow, a strefa oczekiwania Lambourne dla Heathrow leży tuż na wschód od kadru.

Korzystałem z aplikacji transportowych w kilku krajach i mogę powiedzieć, że to nie jest normalne. To prawdziwy prezent dla majsterkowiczów. 🙏


Jeden shot na raz: budowanie cienkimi plasterkami

Na początku ustaliliśmy jedną zasadę: budujemy iteracyjnie, zaczynając od najprostszej wersji, i wdrażamy każdy plasterek, zanim zaczniemy następny. Bez wielkiego wybuchu. Każdy krok musiał być czymś, co mogę otworzyć na telefonie i używać.

Oto jak naprawdę wyglądało to weekendowe popołudnie (godziny z historii gita, wszystko jednego dnia):

GodzinaKrokCo dodał
14:571. Metro na żywoCiemna mapa, budynki 3D, tor linii Central z OSM, animowane pociągi na żywo, tablice odjazdów na stacjach
15:122. WdrożenieDziała na serwerze Mikrus po HTTPS
15:173. SamolotySamoloty z adsb.lol, z linią lotniczą, trasą i zdjęciem po najechaniu
15:384. Autobusy12 głównych linii TfL, rozmieszczonych na podstawie prognoz przyjazdów, z tablicami przystankowymi
17:444a. Prawdziwy GPS autobusówPozycje z BODS przyciągnięte do linii trasy, docierające na przystanki zgodnie z prognozami TfL
18:035. Kamery drogowe27 kamer TfL JamCams wokół ronda Charlie Brown’s i drogi A406, ze zdjęciami i klipami wideo
18:427. Strona „O projekcie” i wygląd „tycoon”Przełączany wygląd retro z pikselowymi pojazdami rysowanymi w kodzie (oryginalna grafika, nic pożyczonego)
19:028. OvergroundPociągi linii Weaver w Chingford

Sączyć, nie pędzić

Krok 6 (budynki z Overture, szlify, autobusy z Essex) wciąż czeka na liście zadań i to jest w porządku. Na tym polegają plasterki.

Kilka rzeczy, które podobały mi się w takiej pracy:

  • Pierwsza wersja była przydatna w ciągu kilku minut. Widok pociągów linii Central sunących między Loughton a Buckhurst Hill to już było dokładnie to, czego chciałem.
  • Odstępstwa były zapisywane, a nie ukrywane. Na przykład w kroku 1 użyliśmy zwykłych warstw MapLibre zamiast deck.gl, bo przy około 15 pociągach nie był potrzebny. Specyfikacja zapisuje dlaczego.
  • Prawdziwe problemy wyszły wcześnie. adsb.lol zaczął ograniczać zapytania z serwera (błędy HTTP 429) wkrótce po starcie. Dodaliśmy wycofywanie się, respektowanie nagłówka Retry-After, rzadsze odpytywanie i pozwoliliśmy przeglądarce szacować pozycję każdego samolotu nawet przez 60 s między aktualizacjami. Poprawka i jej uzasadnienie trafiły do tabeli ryzyk w specyfikacji.

Zasada kciuka: wdrożony plasterek jest lepszy niż idealny plan. Każdy plasterek, który wyląduje, to plasterek, który możesz pokazać rodzinie.


Nuty smakowe: co to właściwie robi

Otwórz map.zagor.org, a zobaczysz:

  • Pociągi linii Central jadące właściwym torem, wschodnim albo zachodnim, skręcające we właściwą odnogę w Woodford i nigdy niecofające się.
  • Pociągi Overground na linii Weaver w Chingford.
  • Autobusy, w większości według prawdziwego GPS, płynnie sterujące w stronę następnego przystanku, tak że korekty je spowalniają, zamiast powodować skoki. Przewoźnicy spoza TfL są pokazani na niebiesko.
  • Samoloty z krótkimi znikającymi śladami, a po najechaniu z linią lotniczą, trasą i zdjęciem.
  • Tablice odjazdów po kliknięciu stacji albo przystanku.
  • Kamery drogowe z najnowszym zdjęciem i przyciskiem odtwarzania klipu.
  • Wygląd retro „tycoon”, który można włączyć i który według dzieci jest jedynym słusznym sposobem oglądania mapy.

Mapa Forest Edge Live: kamera

Zrzut ekranu

Mapa Forest Edge Live: samoloty

Zrzut ekranu

Mapa Forest Edge Live: stacja

Zrzut ekranu

Mapa Forest Edge Live

I tak, pierwotny cel działa. Teraz stoimy na przystanku i patrzymy, jak W14 stoi na światłach. 🙂


Przydatne linki

KategoriaOpisLink
InspiracjaZONE ONE, autor James Potterhttps://london.jamespotter.dev/
EfektMoja mapa na żywohttps://map.zagor.org/
HostingMikrus VPS, Jakub Mrugalskihttps://mikr.us/
Asystent AIClaude Codehttps://claude.com/claude-code
Metro, autobusy, kameryTfL Unified APIhttps://api.tfl.gov.uk/
GPS autobusówBus Open Data Service (DfT)https://data.bus-data.dft.gov.uk/
Geometria torówOpenStreetMaphttps://www.openstreetmap.org/
Samolotyadsb.lol / adsbdbhttps://adsb.lol/ · https://www.adsbdb.com/
Renderowanie mapyMapLibre GL JS + OpenFreeMaphttps://maplibre.org/ · https://openfreemap.org/

Czego nauczyła mnie ta kawowa podróż

  • Mglisty pomysł wystarczy, żeby zacząć. Kilka linijek i szczera wymiana zdań dały specyfikację, którą chętnie dostałbym od kolegi z zespołu.
  • Pozwól modelowi przyjrzeć się prawdziwym danym, zanim zacznie planować. Zmierzone liczby i zaobserwowane dziwactwa sprawiły, że specyfikacja nadawała się do budowania, a nie tylko do marzeń.
  • Specyfikacja to pamięć produktu. Decyzje, odstępstwa i lekcje (jak ograniczanie zapytań przez adsb.lol) wracały do niej, więc nic nie żyło tylko w historii czatu.
  • Zacznij od czegoś zawstydzająco małego i wdrażaj każdy plasterek. Jedna linia kolejowa na ciemnej mapie była pierwszym sukcesem. Cała reszta to bonus.
  • Hosting nie jest już nudną przeszkodą. Z MCP Mikrusa wdrożenie stało się krokiem, który asystent po prostu wykonuje.
  • Prawdziwym bohaterem są otwarte dane. TfL, BODS i OpenStreetMap sprawiły, że rodzinny projekt poboczny dało się zrobić w jedno popołudnie.

Kiedy na stacji Chingford pojawiły się pociągi linii Weaver, moja kawa była dawno zimna, ale mapa żyła. Mały VPS gdzieś w Polsce co kilka sekund odpytuje londyńskie dane transportowe, żeby moja rodzina mogła sprawdzić, czy autobus już jedzie.

Nigdy nie było lepszego czasu na zbudowanie małego, trochę zwariowanego narzędzia, którego potrzebujesz tylko Ty. Znajdź swój problem, napisz pierwszą mglistą wiadomość i zobacz, jak daleko Cię to zaprowadzi.

Co umieściłbyś na swojej mapie na żywo? Swoje miasto, drogę do pracy, autobus, który nigdy nie przyjeżdża? Napisz do mnie.


Ten wpis ukazał się pierwotnie po angielsku na moim blogu Coffee Journeys.

Coffee JourneysTechnologieRodzina