Архитектура фронтенд-приложения «Плечики»¶

Уровень: L1 (обзор) | Вверх: ../README.md

Фронтенд-часть системы «Плечики» представляет собой одностраничное прогрессивное веб-приложение (PWA) для цифровизации гардероба. Приложение реализовано по принципу mobile-first с offline-first архитектурой и поддержкой клиентских ML-эмбеддингов для поиска похожих вещей.

Ключевые цифры¶

Метрика	Значение
Страниц (routes)	16
Компонентов (ui + common + layout)	26
Модулей верхнего уровня	12
Строк кода (TS/TSX/CSS)	~12 450
Zustand-сторов	2
API-модулей	8
Offline-модулей	17
Embedding-модулей	7

Слои приложения¶

graph TB
    subgraph UI["Слой представления"]
        Pages["Pages (16 экранов)"]
        Layout["Layout (AppLayout, BottomNav, PageHeader)"]
        Common["Common (ItemCard, OutfitCard, ...)"]
        UIComp["UI (MediaCard, FilterChip, BottomSheet, ...)"]
    end

    subgraph Logic["Слой бизнес-логики"]
        Hooks["Hooks (useDebounce, useWeather, useVirtualPagination, useServiceWorker)"]
        Stores["Stores (authStore, outfitBuilderStore)"]
        Embeddings["Embeddings (similarityService, vectorMath, Web Worker)"]
    end

    subgraph Data["Слой данных"]
        API["API (axios client, 8 модулей)"]
        TanStack["TanStack Query (queryClient, кэширование)"]
        Offline["Offline (Dexie DB, repositories, syncEngine)"]
    end

    Pages --> Layout
    Pages --> Common
    Pages --> UIComp
    Pages --> Hooks
    Pages --> Stores
    Common --> UIComp
    Hooks --> API
    Hooks --> Stores
    Hooks --> Offline
    Stores --> Offline
    Embeddings --> Offline
    API --> TanStack
    Offline --> TanStack

Диаграмма

Обзор разделов¶

Раздел	Суть	Ссылка
Технологический стек	React 18 + TypeScript 5 + Vite 5 + Ant Design 5, обоснование выбора	tech-stack/
Структура проекта	12 модулей, layer-based организация с элементами feature-based	project-structure/
Управление состоянием	Zustand (клиентское) + TanStack Query (серверное) + useState (локальное)	state-management/
Дизайн-система	CSS Modules + CSS Custom Properties + кастомизированная тема Ant Design	design-system/
Архитектура компонентов	4-уровневая иерархия: pages → layout → common → ui	components/

Принцип mobile-first¶

Приложение спроектировано как мобильное PWA с базовым разрешением iPhone 14 (390 × 844 px). Все компоненты, отступы и типографика оптимизированы под мобильный экран. Используются safe-area-inset для корректного отображения на устройствах с вырезами. Максимальная ширина контента ограничена 768px для планшетов.

Принцип offline-first¶

Данные хранятся локально в IndexedDB (Dexie.js) и синхронизируются с сервером через очередь операций (syncEngine). Пользователь может просматривать гардероб, создавать образы и редактировать вещи без подключения к интернету. При восстановлении связи накопленные изменения автоматически синхронизируются.

Клиентские ML-эмбеддинги¶

Векторные представления вещей и образов хранятся в IndexedDB и используются для поиска похожих элементов. Тяжёлые вычисления (косинусное сходство) вынесены в Web Worker для предотвращения блокировки основного потока.