@golemio/pid 6.0.1-dev.2901184022 → 6.0.1-dev.2912471131

package/docs/index.md

@@ -0,0 +1,382 @@
+# PID Polohy
+
+PID Polohy je soubor služeb datové platformy [Golemio](https://golemio.cz/) navržený pro příjem, zpracování a publikaci dat Pražské integrované dopravy (PID) – poloh vozidel v reálném čase, jízdních řádů (GTFS), odjezdových a přestupních tabulí, událostí (mimořádností, výluk, trvalých změn i událostí interních) a infotextů – s důrazem na aktuálnost, spolehlivost, strojovou čitelnost a otevřené standardy (GTFS, GTFS Realtime). Data přijímá od dopravců, ze systému MPVnet, z ROPID a z aplikací VYMI a Tabulátor. Poskytuje je odjezdovým či přestupním tabulím, aplikacím a otevřeným datům prostřednictvím REST API a GTFS-RT feedů.
+
+## Rozcestník
+
+- Dokumentace API:
+  - [OpenAPI/Swagger dokumentace výstupního API]
+    - [OpenAPI/Swagger dokumentace výstupního API testovacího prostředí Rabín]
+    - [Zdrojový soubor OpenAPI výstupního API]
+  - [OpenAPI/Swagger dokumentace vstupního API]
+    - [OpenAPI/Swagger dokumentace vstupního API testovacího prostředí Rabín]
+    - [Zdrojový soubor OpenAPI vstupního API]
+- Repozitáře a issues:
+  - [PID Polohy issues]
+  - [Repozitář modulu pid]
+  - [Repozitář modulu core]
+  - [Repozitář VP Input Gateway]
+  - [Repozitář TCP Input Gateway]
+  - [Repozitář VP Integration Engine]
+  - [Repozitář VP Output Gateway]
+  - [Repozitář URL Proxy]
+  - [Repozitář Data Proxy]
+  - [Repozitář Cron Tasks]
+- Architektura:
+  - [Architektura PID Poloh]
+  - [Architektura platformy Golemio]
+  - [Upřesňující popis architektury platformy Golemio]
+- Podrobná dokumentace:
+  - [Dokumentace propisu VYMI dat do datové platformy Golemio]
+  - [Dokumentace zpracování RT dat](./processing/index.md)
+    - [Vstupní data HTTP MPVnet (autobusy mimo DPP, přívozy, vlaky)](./processing/input_realtime_data/http_mpvnet.md)
+    - [Vstupní data TCP DPP tramvaje](./processing/input_realtime_data/tcp_dpp_tram.md)
+    - [Vstupní data TCP DPP autobusy a trolejbusy](./processing/input_realtime_data/tcp_dpp_bus.md)
+    - [Vstupní data TCP DPP metro](./processing/input_realtime_data/tcp_dpp_metro.md)
+    - [Určení stavu vozidla na trase – HTTP MPVnet](./processing/state_position_tracking/http_mpvnet.md)
+    - [Určení stavu vozidla na trase – TCP DPP](./processing/state_position_tracking/tcp_dpp_common.md)
+    - [Určení stavu vozidla na trase – TCP DPP metro](./processing/state_position_tracking/tcp_dpp_metro.md)
+    - [Vstupní data](./processing/input_realtime_data/tcp_telmax_arriva_city.md) a [určení stavu vozidla](./processing/state_position_tracking/tcp_telmax_arriva_city.md) TCP Telmax Arriva City (integrace je v produkci vypnutá, Arriva City přichází přes MPVnet)
+  - [Párování MPVnet spojů na spoje GTFS](./processing/trip_matching.md)
+  - [Trip context – stav spoje mezi polohami](./processing/trip_context/index.md)
+  - [Mapování typů vozidel MPVnet na GTFS](./processing/vehicle_types.md)
+  - [Filtrování přestupních tabulí /v4/pid/transferboards](./processing/transferboards_filtering.md)
+  - [Chybějící odjezdy (MISSING) v API odjezdových tabulí](./jis/missing.md)
+  - [Dokumentace cache]
+    - [Redis (Valkey) cache](./cache/types/redis.md)
+    - [In-memory cache](./cache/types/in_memory.md)
+    - [PostgreSQL cache](./cache/types/psql.md)
+  - [Implementační dokumentace]
+    - [Vstupní data a zdrojové systémy](./implementation_documentation.md#vstupní-data)
+    - [Workery, tasky a fronty](./implementation_documentation.md#zpracování-dat-transformace)
+    - [Uložení a retence dat](./implementation_documentation.md#uložení-dat) (obsahuje i ERD diagramy databáze)
+    - [Výstupní API](./implementation_documentation.md#output-api)
+    - [Vstupní API](./implementation_documentation.md#input-api)
+  - [AsyncAPI front RabbitMQ – zdrojový soubor]
+
+[OpenAPI/Swagger dokumentace výstupního API]: https://api.golemio.cz/pid/docs/openapi/
+[OpenAPI/Swagger dokumentace výstupního API testovacího prostředí Rabín]: https://rabin.golemio.cz/pid/docs/openapi/
+[Zdrojový soubor OpenAPI výstupního API]: ./openapi-output.yaml
+[OpenAPI/Swagger dokumentace vstupního API]: https://api.golemio.cz/pid/input-gateway/docs/openapi/
+[OpenAPI/Swagger dokumentace vstupního API testovacího prostředí Rabín]: https://rabin.golemio.cz/pid/input-gateway/docs/openapi/
+[Zdrojový soubor OpenAPI vstupního API]: ./openapi-input.yaml
+[PID Polohy issues]: https://gitlab.com/operator-ict/golemio/code/modules/pid/-/work_items
+[Repozitář modulu pid]: https://gitlab.com/operator-ict/golemio/code/modules/pid
+[Repozitář modulu core]: https://gitlab.com/operator-ict/golemio/code/modules/core
+[Repozitář Cron Tasks]: https://gitlab.com/operator-ict/golemio/code/cron-tasks
+[Repozitář VP Input Gateway]: https://gitlab.com/operator-ict/golemio/code/vp/input-gateway
+[Repozitář TCP Input Gateway]: https://gitlab.com/operator-ict/golemio/code/tcp-input-gateway
+[Repozitář VP Integration Engine]: https://gitlab.com/operator-ict/golemio/code/vp/integration-engine
+[Repozitář VP Output Gateway]: https://gitlab.com/operator-ict/golemio/code/vp/output-gateway
+[Repozitář URL Proxy]: https://gitlab.com/operator-ict/golemio/code/url-proxy
+[Repozitář Data Proxy]: https://gitlab.com/operator-ict/golemio/code/data-proxy
+[Architektura PID Poloh]: ./architecture/index.md
+[Architektura platformy Golemio]: https://operator-ict.gitlab.io/golemio/documentation/cs/architektura/architektura/
+[Upřesňující popis architektury platformy Golemio]: https://operator-ict.gitlab.io/golemio/documentation/cs/architektura/architektura-systemu/
+[Dokumentace propisu VYMI dat do datové platformy Golemio]: ./jis/index.md
+[Dokumentace cache]: ./cache/index.md
+[Implementační dokumentace]: ./implementation_documentation.md
+[AsyncAPI front RabbitMQ – zdrojový soubor]: ./asyncapi.yaml
+
+## Komponenty
+
+Systém PID Polohy se skládá z následujících komponent.
+
+### Modul pid
+
+Modul `@golemio/pid` (tento repozitář) obsahuje sdílenou doménovou logiku PID Poloh – endpointy vstupního a výstupního API, workery a tasky pro zpracování dat, validační schémata a datový model. Služby VP Input Gateway, VP Integration Engine, VP Output Gateway a URL Proxy ho instalují jako npm balíček. TCP Input Gateway a Data Proxy modul pid nepoužívají. Zahrnuje zejména následující funkce:
+- Endpointy vstupního API pro VP Input Gateway (polohy vozidel z MPVnetu, presety tabulí z Tabulátoru, události a infotexty z VYMI).
+- Workery a tasky pro VP Integration Engine podle subdomén: jízdní řády, statická data a presety tabulí ROPID (`ropid-gtfs`), polohy vozidel, oběhy, GTFS-RT feedy a popis vozidel (`vehicle-positions`), události a infotexty VYMI (`jis`) a retence dat (`data-retention`).
+- Routery výstupního API pro VP Output Gateway: odjezdové a přestupní tabule, infotexty a presety (`pid`), veřejné API (`public`), jízdní řády GTFS (`ropid-gtfs`), polohy vozidel a GTFS-RT feedy (`vehicle-positions`) a události VYMI (`jis`).
+- Validační schémata vstupních dat a datový model ve schématu `pid`.
+- Databázové migrace PostgreSQL.
+- Dokumentace OpenAPI vstupního a výstupního API a AsyncAPI front.
+
+Klíčové technické komponenty:
+- Jazyk TypeScript.
+- Správa závislostí s npm a distribuce jako npm balíček `@golemio/pid`.
+- Modul core (peer dependency).
+- GTFS Realtime (Protocol Buffers) pomocí @golemio/ovapi-gtfs-realtime-bindings.
+- Geometrické výpočty pomocí Turf a cheap-ruler.
+- Zpracování CSV pomocí csv-parser a csv-stringify a hromadný import do PostgreSQL pomocí pg-copy-streams.
+- XML výstup odjezdových tabulí pomocí fast-xml-builder.
+- Podpora migrací databáze za pomoci Golemio CLI.
+- Pokrytí testy pomocí Mocha, Chai, Sinon, Supertest a Portman.
+
+[Repozitář modulu pid].
+
+### Modul core
+
+Modul core (`@golemio/core`) je společný základ služeb datové platformy Golemio. Používají ho všechny služby PID Poloh, Cron Tasks i modul pid. Zahrnuje zejména následující funkce:
+- Základ aplikací Input Gateway, Integration Engine a Output Gateway (Express server, routery, workery, tasky a zpracování front).
+- Připojení k PostgreSQL, RabbitMQ a Valkey (Redis API), včetně pub/sub a distribuovaných zámků.
+- DI kontejnery pro jednotlivé služby.
+- Přístup k Azure Blob Storage a Azure Table Storage.
+- Datové zdroje (HTTP, FTP/FTPS) s parsováním CSV, JSON, XML a ZIP.
+- Validace dat pomocí JSON schémat.
+- Konfigurace služeb.
+- Logování, health check a řízené ukončení služby, metriky a trasování.
+- Jednotné zpracování chyb.
+
+Klíčové technické komponenty:
+- Jazyk TypeScript.
+- Správa závislostí s npm a distribuce jako npm balíček `@golemio/core`.
+- Framework Express.
+- Integrace databáze PostgreSQL s ORM Sequelize.
+- Klient RabbitMQ amqplib a klient Redis API ioredis.
+- Injekce závislostí s TSyringe.
+- Azure SDK pro Blob Storage a Table Storage.
+- Validace JSON schémat pomocí AJV.
+- Logování pomocí Pino, health check pomocí Lightship, metriky pomocí prom-client a trasování pomocí OpenTelemetry.
+
+[Repozitář modulu core].
+
+### VP Input Gateway
+
+VP Input Gateway (VP IG) je varianta Golemio Input Gateway vyhrazená pro data veřejné dopravy. Vystavuje neveřejné REST API pro příjem (push) dat a přijatá data předává ke zpracování do fronty RabbitMQ. Endpointy poskytuje modul pid. Zahrnuje zejména následující funkce:
+- Příjem poloh vozidel ze systému MPVnet ve formátu XML (`POST /vehiclepositions`).
+- Příjem presetů odjezdových tabulí z aplikace Tabulátor (`POST /ropidgtfs/presets`).
+- Příjem událostí a infotextů z aplikace VYMI (`POST /jis/events`, `POST /jis/infotexts`), viz [Dokumentace propisu VYMI dat do datové platformy Golemio].
+- Validace vstupních dat a omezení velikosti požadavků (JSON, XML).
+- Archivace surových vstupních dat do Azure Blob Storage.
+- Odesílání zpráv do fronty RabbitMQ.
+- Health check, metriky a trasování pro monitoring.
+- Dokumentace OpenAPI/Swagger ([OpenAPI/Swagger dokumentace vstupního API] a [OpenAPI/Swagger dokumentace vstupního API testovacího prostředí Rabín]).
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Framework Express (prostřednictvím modulu core).
+- Modul core a modul `@golemio/pid`.
+- Zpracování JSON a XML požadavků pomocí body-parser a body-parser-xml.
+- Dokumentace OpenAPI pomocí swagger-ui-express.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář VP Input Gateway].
+
+### TCP Input Gateway
+
+TCP Input Gateway (TCP IG) přijímá surová RT data o obězích vozidel DPP, která přicházejí po TCP, a předává je do fronty RabbitMQ. Modul pid nepoužívá, využívá pouze modul core. Zahrnuje zejména následující funkce:
+- TCP přijímače zpráv o obězích tramvají, autobusů a trolejbusů a metra DPP (XML).
+- Skládání zpráv z TCP streamu, jejich filtrování a parsování.
+- Archivace surových dat do Azure Table Storage.
+- Odesílání zpráv do fronty RabbitMQ ke zpracování ve VP Integration Engine.
+- Přijímač TCP zpráv Telmax (Arriva City) – v kódu existuje, v produkci se nevyužívá.
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Modul core (RabbitMQ, Azure Table Storage, logování).
+- Injekce závislostí s TSyringe (prostřednictvím modulu core).
+- Parsování XML pomocí xml2js.
+- Pokrytí testy pomocí Jest.
+
+[Repozitář TCP Input Gateway].
+
+### VP Integration Engine
+
+VP Integration Engine (VP IE) je varianta Golemio Integration Engine vyhrazená pro polohy vozidel. Spouští workery modulu pid, které zpracovávají zprávy z front RabbitMQ, stahují externí data a výsledky ukládají do PostgreSQL a Valkey. Zahrnuje zejména následující funkce:
+- Načtení workerů a definic front z modulů Golemio (`@golemio/pid` a další moduly platformy) a konzumace front RabbitMQ.
+- Stahování a zpracování jízdních řádů GTFS a statických dat z ROPID.
+- Zpracování poloh vozidel a oběhů, párování na spoje GTFS, výpočet a propagace zpoždění ([Dokumentace zpracování RT dat](./processing/index.md)).
+- Generování GTFS-RT feedů a obnova cache pro výstupní API.
+- Zpracování událostí a infotextů z aplikace VYMI a odchozí webhook událostí.
+- Presety odjezdových tabulí a hlášení pro Dohledové centrum ROPID (DCIP).
+- Popis vozidel a retence dat.
+- Health check (PostgreSQL, Valkey, RabbitMQ), metriky a trasování pro monitoring.
+- Dokumentace front ve formátu AsyncAPI.
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Modul core, Golemio DB Common module a modul `@golemio/pid`.
+- Integrace databáze PostgreSQL s ORM Sequelize (prostřednictvím modulu core).
+- Injekce závislostí s TSyringe (prostřednictvím modulu core).
+- Sloučení a generování AsyncAPI dokumentace pomocí Golemio CLI a AsyncAPI CLI.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář VP Integration Engine].
+
+### VP Output Gateway
+
+VP Output Gateway (VP OG) je varianta Golemio Output Gateway vyhrazená pro data veřejné dopravy. Vystavuje REST API pro čtení dat uložených v PostgreSQL a Valkey. Endpointy PID Poloh poskytuje modul pid. Zahrnuje zejména následující funkce:
+- REST API jízdních řádů GTFS (`/v2/gtfs/*`), ze kterého čtou data mj. aplikace VYMI a Tabulátor.
+- REST API poloh vozidel (`/v2/vehiclepositions`) a GTFS-RT feedy (`/v2/vehiclepositions/gtfsrt/*.pb`).
+- REST API odjezdových a přestupních tabulí, infotextů a presetů tabulí (`/v2/pid/*`, `/v3/pid/*`, `/v4/pid/*`).
+- Veřejné REST API poloh vozidel a odjezdů (`/v2/public/*`).
+- Interní REST API událostí z aplikace VYMI (`/v1/jis/events/custom-format`).
+- Komprese odpovědí.
+- Health check, metriky a trasování pro monitoring.
+- Dokumentace OpenAPI/Swagger ([OpenAPI/Swagger dokumentace výstupního API] a [OpenAPI/Swagger dokumentace výstupního API testovacího prostředí Rabín]).
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Framework Express (prostřednictvím modulu core).
+- Modul core, modul `@golemio/pid` a další moduly platformy.
+- Integrace databáze PostgreSQL s ORM Sequelize a Valkey (prostřednictvím modulu core).
+- Komprese odpovědí pomocí compression.
+- Dokumentace OpenAPI pomocí swagger-ui-express.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář VP Output Gateway].
+
+### URL Proxy
+
+URL Proxy překládá krátké URL odjezdových tabulí (presety) na volání API odjezdových tabulí ve VP Output Gateway. Zahrnuje zejména následující funkce:
+- Načítání definic presetů z PostgreSQL (tabulka presetů modulu pid) a jejich pravidelná obnova cronem.
+- Překlad krátké URL `https://s.golemio.cz/pid/<název presetu>` na adresu API s parametry presetu.
+- Přeposílání požadavků (reverse proxy) na API s API klíčem služby.
+- Logy požadavků, ze kterých modul pid přes Grafana Loki sestavuje hlášení pro Dohledové centrum ROPID (DCIP).
+- Health check (PostgreSQL).
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Framework Express (prostřednictvím modulu core).
+- Modul core a modul `@golemio/pid` (datový model presetů).
+- Reverse proxy pomocí http-proxy-middleware.
+- Spouštění cron tasků za pomoci knihovny cron.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář URL Proxy].
+
+### Data Proxy
+
+Data Proxy přijímá RT data před VP IG / TCP IG a rozesílá je na nakonfigurované cíle. Modul pid nepoužívá, využívá pouze modul core. Zahrnuje zejména následující funkce:
+- HTTP, TCP a UDP proxy servery podle konfigurace.
+- Rozesílání každé přijaté zprávy na více cílů (např. vstupní brány a přeposílání TCP toků tramvají a autobusů DPP do MPVnetu).
+- Sdílené keep-alive spojení na cíle HTTP proxy.
+- Volitelné statistiky provozu cílů, pravidelně ukládané do Azure Blob Storage.
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Modul core (Azure Blob Storage, logování).
+- HTTP proxy pomocí http-proxy-3 a rozesílání streamů pomocí multi-write-stream.
+- Spouštění cron tasků za pomoci knihovny croner.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář Data Proxy].
+
+### Cron Tasks
+
+Cron Tasks je služba datové platformy Golemio, která v nastavených časech posílá zprávy do RabbitMQ a tím spouští pravidelné úlohy ve VP Integration Engine. Data sama nezpracovává. Zahrnuje zejména následující funkce:
+- Definice úloh v konfiguraci (čas ve formátu cron, exchange, routing key, obsah zprávy) s možností úlohu dočasně vypnout.
+- Odeslání zprávy do RabbitMQ v nastavený čas.
+
+Klíčové technické komponenty:
+- Docker pro kontejnerizaci aplikace.
+- Runtime Node.js.
+- Správa závislostí s npm.
+- Jazyk TypeScript.
+- Modul core (RabbitMQ, trasování).
+- Spouštění cron tasků za pomoci knihovny cron.
+- Logování pomocí Pino a debug.
+- Pokrytí testy pomocí Mocha, Chai, Sinon a Supertest.
+
+[Repozitář Cron Tasks].
+
+## Podpůrné komponenty
+
+Podrobnosti ke všem podpůrným komponentám popisuje [Architektura PID Poloh].
+
+### Databáze a cache
+
+- **PostgreSQL + PostGIS** - Hlavní databáze modulu pid:
+  - Ukládá jízdní řády, polohy vozidel, presety tabulí a události a infotexty z VYMI ve schématu `pid`.
+  - Datový model popisují ERD diagramy v implementační dokumentaci.
+
+- **Valkey (Redis API)** - In-memory key-value databáze (cache):
+  - Slouží jako cache pro zpracování RT dat a pro výstupní API.
+  - Uchovává vygenerované GTFS-RT feedy a zajišťuje pub/sub.
+  - Klíče popisuje [Dokumentace cache].
+
+### Fronty a úložiště
+
+- **RabbitMQ** - Fronta zpráv:
+  - Předává zprávy mezi vstupními branami, Cron Tasks a VP Integration Engine.
+  - Fronty popisuje [AsyncAPI front RabbitMQ – zdrojový soubor].
+
+- **Azure Blob Storage, Azure Table Storage** - Úložiště souborů a tabulek:
+  - Archivuje surová vstupní data (HTTP v Blob Storage, TCP v Table Storage).
+  - Uchovává soubory statických dat.
+
+### Přístupová vrstva
+
+- **Access Proxy** - Ověřování a autorizace požadavků:
+  - Ověřuje API klíče a role před vstupním i výstupním API.
+
+- **Permission Management, API Key Management, Admin panel** - Správa oprávnění:
+  - Spravují role uživatelů a API klíče, které ověřuje Access Proxy.
+
+- **Envoy Gateway** - Ingress do clusteru:
+  - Přijímá HTTP i TCP provoz.
+
+- **Cloudflare** - CDN a DNS proxy před veřejným API:
+  - Cache GTFS-RT feedů maže VP Integration Engine po jejich vygenerování.
+
+- **Varnish** - HTTP cache:
+  - Cachuje vybrané endpointy VP Output Gateway.
+
+### Běhové prostředí a monitoring
+
+- **Azure Kubernetes Service** - Běhové prostředí:
+  - Všechny služby běží jako kontejnery v Kubernetes.
+
+- **Grafana, Loki, Tempo, Azure Managed Prometheus** - Monitoring:
+  - Služby posílají logy (Loki), trasování (Tempo) a metriky (Azure Managed Prometheus), Grafana je zobrazuje.
+  - Z Loki modul pid navíc čte logy požadavků URL Proxy.
+
+### Vývoj a nasazení
+
+- **Docker** - Kontejnerizace:
+  - Každá služba sestavuje image ve vícestupňovém buildu nad Node.js Alpine image.
+
+- **npm** - Distribuce modulu:
+  - Modul pid se do služeb instaluje jako npm balíček `@golemio/pid` v přesné verzi.
+
+- **Golemio CLI** - Vývojářské nástroje:
+  - Import testovacích dat do databáze, testy OpenAPI dokumentace proti běžícímu API a sloučení AsyncAPI dokumentace modulů.
+
+## Architektura
+
+[![Kontextový diagram PID Polohy](./architecture/diagrams/context.svg)](./architecture/diagrams/context.svg)
+
+Kontextový diagram ukazuje zdrojové systémy (dopravci a telematika, DPP, MPVnet, ROPID FTPS, VYMI, Tabulátor a další), platformu Golemio a odběratele dat (odjezdové a přestupní tabule, Mapa PID, aplikace PID Lítačka, Google Maps, Jízdní řády Seznam.cz (dříve PubTran), Škoda Citymove nebo Catch (GTFS-RT)). Logy odjezdových tabulí se také posílají na Dohledové centrum ROPID (DCIP). Polohy vozidel přicházejí přes MPVnet (HTTP), z dispečinků DPP přímo (TCP, Golemio je přeposílá do MPVnetu) a data metra přes proxy MPVnetu (TCP), statická data a data VYMI si Golemio stahuje a VYMI a Tabulátor navíc změny aktivně posílají. [Architektura PID Poloh] obsahuje legendu a podrobnější diagramy [příjmu a zpracování dat](./architecture/index.md#2-příjem-a-zpracování-dat) a [poskytování dat](./architecture/index.md#3-poskytování-dat) a popis [běhového prostředí a monitoringu](./architecture/index.md#běhové-prostředí-a-monitoring).
+
+## Vývoj
+
+Modul je určen pro služby datové platformy Golemio. Použití, lokální vývoj a další informace popisuje [README modulu core](https://gitlab.com/operator-ict/golemio/code/modules/core/-/blob/development/README.md).
+
+Požadavky pro lokální spuštění testů:
+- Node.js a npm.
+- PostgreSQL s rozšířením PostGIS, Valkey (nebo Redis) a RabbitMQ.
+- Soubor `.env` vytvořený podle `.env.template` s připojeními k těmto službám.
+
+Sestavení, kontrola kódu a testy modulu:
+
+```bash
+npm run build
+npm run lint
+# import testovacích dat do databáze a obnova předpočítaných tabulek, poté testy
+npm test
+# ověření docs/openapi-output.yaml proti běžícímu API (prepare-db zároveň sestaví modul)
+npm run prepare-db && npm run apidocs-test-output:only
+```
+
+## Kontakty
+
+Problémy a dotazy hlaste přes [Issues][PID Polohy issues] nebo emailem na [golemio@operatorict.cz](mailto:golemio@operatorict.cz).