Funkce platformy

Sběr zajišťují samostatní poskytovatelé (providers) — nezávislé, bezstavové moduly za jednotným rozhraním. Každý deklaruje svůj kód, kategorii, právní základ dotazování a druhy subjektů, které umí zpracovat. Registr poskytovatelů řídí katalog zdrojů v API (GET /v1/sources).

Aktuálně integrovaných dvanáct zdrojů: osm českých registrů (ARES, ISIR, obchodní rejstřík justice.cz, centrální evidence exekucí, katastr nemovitostí, registr smluv, registr dotací a vnitrostátní sankční seznam ČR), plus tři mezinárodní: VIES (ověření DPH v EU), GLEIF (globální LEI registr) a sankční seznam OFAC SDN (USA), vedle konsolidovaného sankčního seznamu EU. Podrobný přehled toho, co každý zdroj přináší, je níže. Pro testy existuje deterministický offline MockProvider — testy nikdy nevolají skutečnou síť.

Každý zdroj má vlastní ochranné mechanismy sdílené knihovnou poskytovatelů: token-bucket rate limiting v Redisu, circuit breaker se stavy closed/open/half-open, retry s exponenciálním backoffem a TTL cache výsledků. Výpadek nebo zpomalení jednoho registru tak nezablokuje zbytek šetření.

Poskytovatelé mezi sebou záměrně nekomunikují — každý je testovatelný a nasaditelný samostatně a přidání nového zdroje nevyžaduje zásah do jádra platformy.

Každý subjekt se převádí na kanonický klíč, který deduplikuje tentýž subjekt nalezený nezávisle různými zdroji: firmy podle IČO (company:CZ:<ico8>), osoby podle normalizovaného jména a data narození, domény po převodu na eTLD+1, IP adresy v kanonickém tvaru a e-maily po lowercasingu. Normalizační funkce jsou idempotentní a pokryté property-based testy.

Odpovědi zdrojů se normalizují do jednotné obálky důkazu: kód zdroje, čas pořízení, hash obsahu, normalizovaná data, důvěryhodnost, právní základ a viditelnost (veřejný / omezený / interní). Veřejná a interní podoba dat jsou oddělené typy — interní pole nikdy neprojdou do API odpovědi.

Entity nalezené během šetření (firmy, osoby) a jejich typované vztahy — vlastnictví, jednatelství, podíly — se ukládají do PostgreSQL a promítají do vestavěné grafové databáze Kuzu. Graf je odvozená projekce: kdykoli přestavitelný z relační databáze, nikdy druhá autorita nad týmiž fakty.

Grafové API vystavuje sousedy entity, ohraničený dotaz (hloubka, typy vztahů, minimální důvěryhodnost), hledání cest mezi entitami, výpočet centrality a detekci cyklů — tedy vlastnických smyček typických pro schránkové struktury, které prosté procházení rejstříku přehlédne.

Veřejné API záměrně nenabízí surové Cypher dotazy. Jediným dotazovacím povrchem je ohraničené DSL — hloubka a rozsah průchodu jsou limitované a filtr tenantu je aplikován na každý uzel i hranu, takže průchod napříč tenanty je vyloučen konstrukcí, ne konvencí.

Interaktivní vizuální explorer grafu pro analytiky je Plánováno — dnes je graf dostupný přes REST API a zobrazení v aplikaci.

Z každého dokončeného šetření lze vygenerovat zprávu ve formátech JSON, HTML a Markdown. Zpráva obsahuje shrnutí subjektu, zjištění podle závažnosti, ledger důkazů s hashi (normalizovaná data i surové záznamy zdrojů) a vložený ověřovací manifest. Zpráva se ukládá jako neměnný artefakt s vlastním SHA-256 otiskem — příjemce může pomocí manifestu i offline ověřit, že se artefakt ani hashe důkazů po vygenerování nezměnily.

Do zprávy vstupují pouze veřejné datové obálky — surová data od poskytovatelů a interní pracovní poznámky do výstupu nikdy neprosáknou. Export do PDF je Plánováno.

Dlouhé sběry nikdy neblokují HTTP požadavek. Založení šetření vrátí odpověď okamžitě a samotný běh — sběr od poskytovatelů, kontrolu integrity a syntézu projekcí — provede ARQ worker nad Redisem. Šetření prochází stavovým automatem (queued → collecting → validating → synthesizing → completed/failed/cancelled) a jeho stav lze kdykoli dotázat přes API — buď jedním požadavkem, nebo průběžně přes SSE stream (GET /v1/investigations/{id}/events); běžící šetření lze i ručně zrušit, což worker zohlední na nejbližší kontrolní bod mezi jednotlivými zdroji.

Jediným zdrojem pravdy je PostgreSQL se schématem spravovaným migracemi (Alembic); TimescaleDB rozšíření nese časové řady událostí sběru a historie zjištění. Meilisearch a Kuzu jsou odvozené projekce. Strukturované JSON logování s korelačními ID prochází celou pipeline. Lokální vývojové prostředí definuje docker-compose.