Technologická dokumentace

Architektura, technologie a procesy stojící za platformou Revize Plus.

Revize Plus je marketplace propojující české zákazníky — domácnosti, SVJ, bytová družstva, živnostníky a firmy — s certifikovanými revizními techniky pro povinné bezpečnostní revize. Platforma řeší zákonem vyžadovanou periodickou kontrolu elektřiny, plynu, komínů, fotovoltaických systémů a dalších technických zařízení.

Software je navržen s důrazem na dlouhodobou udržovatelnost. Kombinuje osvědčené architektonické vzory (Domain-Driven Design, Hexagonální architektura, CQRS) s moderním technologickým stackem postaveným na zavedených enterprise nástrojích.

API-first přístup

Backend je postavený jako čisté REST API se standardizovanou OpenAPI dokumentací (generovanou automaticky přes API Platform). Veškerá funkcionalita systému je dostupná přes API endpointy — současné webové rozhraní (Next.js) je pouze jedním z možných klientů, nikoli jediným přístupovým bodem.

Nativní mobilní aplikace

iOS / Android

Případnou nativní aplikaci pro iPhone nebo Android lze postavit přímo nad stávajícím API bez nutnosti zásahu do backendu. Všechna data a operace jsou již dostupné.

Integrace třetích stran

B2B / partneři

Externí systémy (CRM, účetnictví, partnerské portály, registry techniků) lze napojit přes dokumentované endpointy. Autentizace probíhá přes standardní JWT tokeny.

Standardizovaná dokumentace

OpenAPI / Swagger

API je dokumentováno podle OpenAPI specifikace a dostupné na /api/docs. Klienti mohou automaticky generovat typový kód v libovolném jazyce.

Architektura

Backend je rozdělen do tří jasně oddělených vrstev. Toto rozdělení vychází z principů Domain-Driven Design a Hexagonální architektury (známé také jako Ports and Adapters). Pro orchestraci use-case scénářů je použit vzor CQRS (oddělení čtení a zápisu). Hlavní přínos tohoto přístupu je nezávislost doménové logiky na konkrétním frameworku, snadná testovatelnost a možnost vyměnit části systému (např. databázi nebo API vrstvu) bez přepisu obchodní logiky.

Doménová vrstva

Domain

Entity, value objekty, repository rozhraní a doménové události. Čisté PHP bez závislosti na frameworku — jádro obchodní logiky platformy.

Aplikační vrstva

Application

Příkazy (Commands), dotazy (Queries) a jejich handlery. Orchestruje use-case scénáře a koordinuje doménové operace.

Infrastrukturní vrstva

Infrastructure

Konkrétní implementace — Doctrine repositáře, API Platform resources, integrace s externími službami. Adaptéry napojené na porty z doménové vrstvy.

Tok požadavku

HTTP požadavek → API Platform → Command nebo Query Bus → Handler → doménová logika → Repository → databáze. Každá vrstva má jasně definovanou odpovědnost a komunikuje přes rozhraní, ne přes konkrétní implementaci.

Technologický stack

Stack je postaven výhradně na zavedených, dlouhodobě udržovaných open-source technologiích s aktivní komunitou a jasnou cestou aktualizací.

Backend

Technologie	Verze	Účel
PHP	8.4	Programovací jazyk pro backend
Symfony	7.4	Aplikační framework
API Platform	4.2	REST API framework s OpenAPI dokumentací
Doctrine ORM	3.3	Mapování objektů na databázi
Symfony Messenger	—	Command/Query bus pro CQRS architekturu
Lexik JWT Bundle	—	Stateless autentizace přes JWT tokeny

Frontend

Technologie	Verze	Účel
Next.js	15	React framework s App Routerem
React	19	UI knihovna
TypeScript	—	Typová bezpečnost a IDE podpora
TanStack Query	v5	Správa stavu dat ze serveru
Zustand	—	Klientský state management
React Hook Form + Zod	—	Formuláře a validace
Tailwind CSS	4	Stylování s utility-first přístupem
shadcn/ui	—	Knihovna přístupných UI komponent

Databáze a infrastruktura

Technologie	Verze	Účel
MariaDB	10.11	Relační databáze
Docker Compose	—	Lokální vývoj a kontejnerizace
Nginx	—	Web server a reverse proxy
Mailpit	—	Vývojový SMTP server

Bezpečnost

JWT autentizace — stateless API postavené na podepsaných tokenech přes lexik/jwt-authentication-bundle. Žádné session cookies, žádný server-side state.
Role-based přístup — oddělené uživatelské role pro Zákazníka, Technika a Admina. Každý endpoint kontroluje konkrétní oprávnění.
Validace na hranicích systému — všechna vstupní data jsou validována v API resources a Command DTO. Doménové entity nikdy nepřijmou neplatný stav.
Veřejné endpointy explicitně označené — /api/auth a /api/docs jsou přístupné bez autentizace, vše ostatní vyžaduje platný JWT token.
Identifikátory jako UUID v7 — místo inkrementálních ID, což eliminuje předvídatelnost a snižuje riziko enumeračních útoků.

Kvalita kódu

Kvalita je vynucována automaticky — žádný kód se nedostane do produkce bez splnění stanovených standardů.

Statická analýza

Backend: PHPStan na úrovni max — nejpřísnější dostupná úroveň, odhalí typové chyby ještě před spuštěním. Frontend: TypeScript strict mode.

Standardy formátování

Backend: PSR-12 vynucený přes PHP_CodeSniffer. Frontend: ESLint + Prettier.

Automatizované testy

Backend: PHPUnit — unit, integrační i aplikační testy. Frontend: Vitest. End-to-end: Playwright — automatické ověření klíčových uživatelských scénářů přes skutečný prohlížeč.

Continuous Integration

Každý commit prochází automatickým pipeline — lint, statická analýza, testy. Žádný kód se nesmí dostat do hlavní větve bez úspěšného průchodu.

Vývojový proces

Docker Compose — celé vývojové prostředí (backend, frontend, databáze, mail server) běží v izolovaných kontejnerech. Nový vývojář má systém spuštěný do několika minut.
Doctrine migrace — všechny změny databázového schématu jsou verzované a deterministické. Nasazení do produkce nikdy neobsahuje ruční SQL.
Git workflow s code review — všechny změny prochází přes pull requesty s povinným reviewem před sloučením do hlavní větve.
Automatizované nasazení — CI/CD pipeline po úspěšném testování automaticky nasazuje do produkčního prostředí. Žádné ruční kroky, žádný prostor pro chybu lidským faktorem.
Doctrine XML mappingy — mapování entit na databázi je definováno v XML souborech, oddělené od doménových entit. Tím zůstává doménová vrstva nezávislá na ORM.