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`.