csbot-prototype/documentation/03-architektura-a-mapa-kodu.md

03 - Architektura a mapa kodu

Technologie

Vrstva	Technologie
Server	Node.js 20, Express 4, TypeScript, ESM
Web	React 18, Vite 6, TypeScript, Tailwind 4, React Router 6
Auth	JWT (jsonwebtoken), hesla bcrypt
Validace	zod
Docs	swagger-ui-express nad rucne psanou OpenAPI definici

Jeden package.json. Runtime zavislosti jsou v dependencies, nastroje pro build webu v devDependencies - runtime image je pak instaluje pres --omit=dev.

Build

tsc   src/**.ts   ->  dist/*.js
vite  web/        ->  dist/public/

Server obsluhuje dist/public jako statiku. Dockerfile kopiruje do vysledneho image jen dist, takze staci jedna slozka.

Mapa kodu - server

Cesta	K cemu je
src/index.ts	vstupni bod: middleware, mount routeru, statika, SPA, Swagger
src/config.ts	cteni environment variables, normalizace ROOT_PATH
src/openapi.ts	OpenAPI definice vcetne servers s prefixem proxy
src/types.ts	typy uzivatele a JWT payloadu
src/middleware/auth.ts	requireAuth, requireRole
src/events/bus.ts	sbernice udalosti, ze ktere cerpa SSE stream
src/routes/auth.ts	prihlaseni, odhlaseni, kdo jsem
src/routes/dashboard.ts	data portalu, katalog konektoru, CRUD automatizaci
src/routes/stream.ts	SSE stream zmen
src/routes/simulate.ts	vyvolani provoznich udalosti
src/routes/webhook.ts	verejny prijem dat do automatizace
src/routes/contact.ts	poptavkovy formular z webu
src/data/ticketStore.ts	tickety, jejich resitele, log prubehu, prehled vytizeni
src/data/people.ts	resitele ticketu - oddeleni od uzivatelu portalu
src/data/tenants.ts	firmy, ktere portal pouzivaji
src/data/access.ts	kdo co vidi - jedno misto pro cely portal
src/data/widgets.ts	katalog widgetu prehledu
src/data/dashboardLayouts.ts	rozlozeni dashboardu za dvojici uzivatel a firma
src/data/incidentStore.ts	incidenty vcetne zmen a udalosti
src/data/automationStore.ts	automatizace, strom akci, tokeny webhooku
src/data/connectors.ts	katalog konektoru, jejich spousteču a akci
src/data/conditions.ts	typy parametru a operatory podminek
src/data/templates.ts	sablony {{parametr}} v nastaveni kroku
src/data/flowScope.ts	co je videt v kterem miste stromu
src/data/users.ts	demo uzivatele
src/data/mock.ts	souhrn pro prehled a casova rada grafu

Mapa kodu - web

Cesta	K cemu je
web/src/main.tsx	vstupni bod, basename routeru podle prefixu proxy
web/src/App.tsx	routovani, portal se nacita lazy
web/src/index.css	design tokeny a vlastni utility Tailwindu
web/src/config/brand.ts	vsechny firemni udaje na jednom miste
web/src/lib/api.ts	fetch wrapper, sprava tokenu, skladani adres
web/src/lib/eventStream.ts	cteni SSE streamu pres fetch
web/src/lib/useApiQuery.ts	nacitani dat vcetne obnoveni pri udalosti
web/src/lib/flow.ts	ciste funkce nad stromem automatizace
web/src/components/dashboard/	shell portalu, dlazdice, graf, stream, simulace
web/src/components/dashboard/flow/	strom akci, vyber kroku, nastaveni poli akce
web/src/components/dashboard/TicketTrace.tsx	log ticketu jako strom
web/src/components/dashboard/TicketWorkload.tsx	prehled, kdo co ma u sebe
web/src/components/home/	sekce homepage
web/src/pages/	jedna stranka je jeden soubor

Klicova rozhodnuti

Jeden container misto dvou. AppFactory nasazuje jednu aplikaci, proto Express obsluhuje i statiku. Odpada CORS i druha deploy jednotka.

SSE misto WebSocketu. Tok dat je jednosmerny, server ke klientovi. Klient posila zmeny beznym REST volanim. SSE prochazi reverse proxy bez zvlastni konfigurace.

Stream pres fetch, ne pres EventSource. EventSource neumi poslat hlavicku Authorization a token by musel byt v adrese, odkud se dostane do access logu. Cenou je rucni parsovani a rucni znovupripojeni v web/src/lib/eventStream.ts.

Ceske cesty v URL. /sluzby, /o-nas, /prihlaseni, /dashboard/tickety. Kod zustava anglicky.

Data v pameti. Vedome zjednoduseni prototypu. Uloziste jsou oddelena od rout, takze napojeni na databazi znamena prepsat soubory v src/data/, ne endpointy.

Filtr na firmu je povinny argument. listTickets, listPeople i listAutomations vyzaduji tenantIds. Zapomenuty filtr tak neznamena "vse", ale nezkompiluje se. Podrobnosti v 07-firmy-a-prava.md.

Prava se nikdy nedovozuji na klientovi. Server vraci GET /api/dashboard/access s tim, co uzivatel smi. Kdyby si to klient pocital sam, pocitalo by se to na dvou mistech a jednou se to rozejde.

Resitel neni uzivatel. Uzivatel se prihlasuje do portalu, resitel ma u sebe tickety. Technik muze mit tickety a ucet nikdy nemit. Spojka je e-mail, podrobnosti v 06-tickety.md.

Filtrovani ticketu dela server. Klient posila query parametry a dostane hotovy seznam. Kdyby filtroval sam, ukazoval by jina cisla nez prehled vytizeni.

Krok vidi jen to, co je pred nim. Parametry spoustece plus vystupy predchozich kroku. Vetev podminky nepridava nic do sekvence za podminkou, protoze nemusela probehnout. Vypocet je v flowScope.ts, priklady v 06-tickety.md.

Sablony odkazuji jmenem, ne ID. Opak podminek, a je to zamer: {{subject}} uzivatel napise a precte, {{f_42}} ne. Rozbite odkazy po prejmenovani se hlasi jako nedodelek.

Zadna ticha selhani. Kazdy catch loguje a uzivatel se o chybe dozvi.