sparkguardian-frontend/README.md

Sparkguardian

Клиентское веб-приложение для просмотра записанных сессий, HLS-потоков и телеметрии (клавиатура, мышь и др.), работающее поверх REST API Sparkguardian.

A single-page web client for reviewing recorded sessions, HLS streams, and telemetry (keyboard, mouse, and more), built on top of the Sparkguardian REST API.

---

О проекте

Приложение предназначено для операторов и разработчиков, которым нужно открыть список сессий, перейти к деталям конкретной записи и синхронно смотреть видео с разбором событий на временной шкале. Бэкенд отвечает за хранение чанков, плейлистов и событий; фронтенд подставляет базовый URL API, подгружает данные и отображает их в интерфейсе на базе Taiga UI.

Основные возможности

• Список сессий с пагинацией и созданием новой сессии по названию.
• Карточка сессии с вкладками: сводная информация, просмотр записи и телеметрии, интерактивный режим с визуализацией клавиатуры и курсора поверх видео.
• HLS-воспроизведение через hls.js, выбор потока (например, экран или веб-камера), если бэкенд отдаёт несколько stream_type.
• Телеметрия: загрузка разобранных событий с фильтрацией по типу и времени, привязка к окну записи (started_at / ended_at).
• Уведомления об ошибках HTTP с понятными сообщениями для пользователя.

Технологии

Область	Выбор
Фреймворк	Angular 21, TypeScript
UI	Taiga UI, анимации через @angular/animations
HTTP	HttpClient, интерсептор базового URL API
Тесты	Vitest через @angular/build:unit-test, jsdom
Линт	ESLint (angular-eslint)
Видео	hls.js

Стили опираются на дизайн-токены (CSS-переменные); для компонентов по возможности используются примитивы Taiga UI.

Как устроен код

• Маршруты: главная страница — список сессий (/); детали — /sessions/:id. Остальные пути перенаправляются на список.
• Слой API: SessionsApiService ходит на эндпоинты вида /sessions, /sessions/:id/events и т.д.; префикс API задаётся через API_BASE_URL (см. ниже). Относительные URL плейлистов HLS разрешаются к origin через API_ORIGIN.
• Окружение: src/environments/environment.ts генерируется скриптом npm run env:sync из переменных в .env (значения по умолчанию совпадают с .env.example). Production-сборка подменяет файл на environment.prod.ts.
• Прокси в разработке: ng serve использует proxy.conf.cjs: запросы к /api/** уходят на хост из SG_DEV_PROXY_TARGET в .env (по умолчанию указан в примере).

Подробная схема REST описана в docs/doc_v1.json (OpenAPI).

Требования

• Node.js версии, совместимой с Angular 21 (см. рекомендации в документации Angular CLI).
• npm (в проекте зафиксирован packageManager в package.json).

Локальная настройка

1. Скопируйте .env.example в .env и при необходимости измените переменные (SG_API_BASE_PATH, SG_API_FALLBACK_ORIGIN, SG_INTERACTIVE_PREROLL_MS, для dev — SG_DEV_PROXY_TARGET).
2. Установите зависимости: npm install или make install.
3. Сгенерируйте environment.ts: npm run env:sync или make env-sync (перед start и build это выполняется автоматически через npm-скрипты prestart / prebuild).

Запуск и сборка

Задача	Команда
Dev-сервер с прокси	npm start или make start
Production-сборка	npm run build или make build
Сборка development	make build-dev
Unit-тесты	npm test (в режиме разработки без CI обычно удобен интерактивный режим)
Линт	npm run lint
Очистка артефактов	make clean

После npm start приложение доступно по адресу, который выводит Angular CLI (по умолчанию http://localhost:4200/).

CI

В репозитории описан workflow Gitea Actions: .gitea/workflows/ci.yml — линт, тесты с --watch=false, production build. На сервере должны быть включены Actions и настроен runner.

Структура каталогов (кратко)

• src/app/core — API, HTTP, модели, уведомления, разбор телеметрии клавиатуры/мыши, подсветка SVG.
• src/app/features/sessions — список сессий, детальная страница и вкладки, плеер HLS, выбор потока, детали события.
• src/environments — конфигурация окружения.
• public — статические ассеты (иконки, SVG для визуализации и т.д.).
• scripts — вспомогательные скрипты (sync-env.cjs).

---

About the project

The app is aimed at operators and developers who need a session list, a focused session view, and a way to watch video while inspecting timed telemetry. The backend owns chunks, playlists, and events; the frontend configures the API base URL, loads data, and presents it through Taiga UI.

Features

• Session list with pagination and creating a session with a title.
• Session detail with tabs: summary, combined playback and telemetry, and an interactive view with keyboard and cursor overlays on top of the video.
• HLS playback via hls.js, with stream selection when multiple stream_type entries exist.
• Telemetry: parsed events with type and time filters, aligned with the recording window (started_at / ended_at).
• HTTP error notifications with user-facing messages.

Tech stack

Area	Choice
Framework	Angular 21, TypeScript
UI	Taiga UI, @angular/animations for motion
HTTP	HttpClient, API base URL interceptor
Tests	Vitest via @angular/build:unit-test, jsdom
Lint	ESLint (angular-eslint)
Video	hls.js

Styling relies on CSS variables (design tokens); Taiga UI components are preferred where they fit.

Architecture

• Routes: home is the session list (/); details live at /sessions/:id. Unknown paths redirect to the list.
• API layer: SessionsApiService calls /sessions, /sessions/:id/events, etc. The API prefix comes from API_BASE_URL. Relative HLS playlist URLs are resolved with API_ORIGIN.
• Environment: src/environments/environment.ts is generated by npm run env:sync from .env (defaults match .env.example). Production builds use environment.prod.ts.
• Dev proxy: ng serve loads proxy.conf.cjs: /api/** is forwarded to SG_DEV_PROXY_TARGET from .env.

The REST contract is summarized in docs/doc_v1.json (OpenAPI).

Prerequisites

• A Node.js version compatible with Angular 21 (see Angular CLI docs).
• npm (see packageManager in package.json).

Local setup

1. Copy .env.example to .env and adjust variables (SG_API_BASE_PATH, SG_API_FALLBACK_ORIGIN, SG_INTERACTIVE_PREROLL_MS, and for local dev SG_DEV_PROXY_TARGET).
2. Install dependencies: npm install or make install.
3. Generate environment.ts: npm run env:sync or make env-sync (also runs automatically before start / build via npm prestart / prebuild).

Running and building

Task	Command
Dev server with proxy	npm start or make start
Production build	npm run build or make build
Development build	make build-dev
Unit tests	npm test
Lint	npm run lint
Clean artifacts	make clean

After npm start, open the URL printed by the CLI (typically http://localhost:4200/).

CI

Gitea Actions workflow: .gitea/workflows/ci.yml — lint, tests with --watch=false, production build. Actions must be enabled and a runner must be available.

Repository layout

• src/app/core — API client, HTTP, models, notifications, keyboard/mouse telemetry parsing and SVG highlighting.
• src/app/features/sessions — session list, detail page and tabs, HLS player, stream selector, telemetry event drill-down.
• src/environments — environment configuration.
• public — static assets (fonts, SVG overlays, favicon).
• scripts — helpers such as sync-env.cjs.