Технические решения фронтенда¶

Уровень: L1 (overview) | ← Назад к оглавлению

Архитектурная диаграмма¶

C4Context
    title Технические модули фронтенда Plechiki

    Person(user, "Пользователь", "Мобильное PWA")

    System_Boundary(frontend, "React SPA") {
        Container(ui, "UI Components", "React 18", "Страницы, формы, карточки")
        Container(hooks, "Custom Hooks", "React Hooks", "useWeather, useDebounce, useVirtualPagination")
        Container(api, "API Layer", "Axios", "Единый HTTP-клиент с auto-refresh")
        Container(offline, "Offline Layer", "Dexie/IndexedDB", "Локальное хранилище данных")
        Container(sync, "Sync Engine", "Operation Queue", "Очередь операций с retry")
        Container(emb, "Embeddings", "Web Worker", "Векторный поиск по схожести")
        Container(pwa, "PWA/SW", "Workbox", "Кеширование, офлайн, обновления")
    }

    System_Ext(backend, "Backend API", "Kotlin/Spring")
    System_Ext(minio, "MinIO", "Object Storage")
    System_Ext(ml, "ML Service", "Embedding generation")

    Rel(user, ui, "Взаимодействует")
    Rel(ui, hooks, "Использует")
    Rel(hooks, offline, "Читает данные")
    Rel(hooks, emb, "Similarity search")
    Rel(offline, sync, "Очередь операций")
    Rel(sync, api, "HTTP запросы")
    Rel(api, backend, "REST API")
    Rel(pwa, minio, "Кеширует медиа")
    Rel(backend, ml, "Embeddings")

Диаграмма

Таблица технических решений¶

Решение	Проблема	Технология	Подробнее
API Layer	Единый HTTP-клиент с авторизацией и auto-refresh	Axios + interceptors	→ api-layer/
Offline-First	Работа без интернета, мгновенный отклик UI	Dexie.js (IndexedDB)	→ offline/
Sync Engine	Надёжная синхронизация офлайн-изменений	Operation Queue + Retry	→ sync-engine/
PWA	Установка на устройство, кеширование ресурсов	Workbox + vite-plugin-pwa	→ pwa/
Embeddings	Поиск похожих вещей/образов <5ms	Web Worker + Cosine Similarity	→ embeddings/
Custom Hooks	Переиспользуемая логика (погода, пагинация)	React Hooks	→ hooks/

Ключевые метрики¶

Метрика	Значение	Комментарий
Offline storage	IndexedDB (без лимита 5MB)	Blob-данные в отдельной таблице
Sync latency	<1s (при наличии сети)	Мгновенный оптимистичный UI
Embedding search	<5ms	Вычисление в Web Worker, не блокирует UI
SW cache strategies	5 правил	CacheFirst для медиа, StaleWhileRevalidate для API
Image precache	Batch по 10	requestIdleCallback для фонового кеширования
Retry policy	Exponential backoff 1s→60s	Max 5 попыток, jitter ±20%
Media compression	896×896 / quality 0.8	Перед загрузкой на сервер

Потоки данных¶

flowchart LR
    subgraph UI["UI Layer"]
        Pages --> Hooks
    end

    subgraph Data["Data Layer"]
        Hooks --> LocalDB[(IndexedDB)]
        Hooks --> EmbWorker[Web Worker]
    end

    subgraph Sync["Sync Layer"]
        LocalDB --> OpQueue[Operation Queue]
        OpQueue --> SyncEng[Sync Engine]
    end

    subgraph Network["Network Layer"]
        SyncEng --> API[Axios Client]
        API --> Backend[Backend API]
    end

    subgraph Cache["Cache Layer"]
        SW[Service Worker] --> Media[MinIO Media]
        SW --> RefAPI[Reference API]
    end

Диаграмма

Навигация¶

→ API Layer — HTTP-клиент, модули, auto-refresh
→ Offline — IndexedDB, репозитории, сервисы, хуки
→ Sync Engine — очередь операций, retry, цикл синхронизации
→ PWA — Service Worker, кеширование, обновления
→ Embeddings — векторный поиск, Web Worker, UI
→ Hooks — кастомные хуки и утилиты