Обзор системы Plechiki¶

Назначение¶

Plechiki — веб-приложение для цифровизации гардероба. Пользователь фотографирует вещи, система автоматически классифицирует их (категория, цвет, сезон) с помощью ML, позволяет составлять образы, делиться ими и получать рекомендации.

Архитектура системы¶

Система построена по микросервисной архитектуре. Все сервисы контейнеризированы и развёрнуты в Kubernetes-кластере.

graph TD
    User["👤 Пользователь"]

    subgraph Platform["Plechiki Platform"]
        Frontend["🌐 Frontend<br/><i>React 18 · TypeScript · Vite</i>"]
        Backend["⚙️ Backend API<br/><i>Kotlin · Spring Boot 3</i>"]
        Postgres[("🗄️ PostgreSQL 15")]
        MinIO["📦 MinIO<br/><i>S3-хранилище</i>"]
        ML["🤖 ML Service<br/><i>Python · FastAPI · PyTorch</i>"]
    end

    User -- "HTTPS" --> Frontend
    Frontend -- "REST/JSON" --> Backend
    Frontend -. "HTTPS GET<br/>изображения" .-> MinIO
    Backend -- "JDBC" --> Postgres
    Backend -- "S3 API" --> MinIO
    Backend -- "HTTP/JSON" --> ML

    style Frontend fill:#1890ff,color:#fff,stroke:#1890ff
    style Backend fill:#52c41a,color:#fff,stroke:#52c41a
    style Postgres fill:#faad14,color:#fff,stroke:#faad14
    style MinIO fill:#722ed1,color:#fff,stroke:#722ed1
    style ML fill:#eb2f96,color:#fff,stroke:#eb2f96
    style User fill:#f5f5f5,stroke:#333
    style Platform fill:#f9f9f9,stroke:#d9d9d9

Диаграмма

Сервисы и их роли¶

Сервис	Технологии	Роль
Frontend	React 18, TypeScript, Vite, Ant Design, Zustand	PWA-приложение: интерфейс гардероба, создание образов, лента рекомендаций, шеринг. Mobile-first (390×844). Offline-first с локальными эмбеддингами
Backend API	Kotlin 1.9, Spring Boot 3.2, JPA, Spring Security	REST API: управление пользователями, вещами, образами. Авторизация через JWT. Проксирование ML-запросов. Генерация фида и шеринг-ссылок
PostgreSQL	PostgreSQL 15 Alpine	Хранение всех структурированных данных: пользователи, вещи, образы, справочники, ссылки шеринга, эмбеддинги
MinIO	MinIO (S3-совместимый)	Объектное хранилище для медиафайлов: фотографии вещей, аватары, обложки образов. Публичный доступ для чтения
ML Service	Python 3.11, FastAPI, PyTorch, scikit-learn	Классификация вещей по фото (категория, цвет, сезон), генерация эмбеддингов (ResNet50 → 1024d), оценка совместимости образов, рекомендации

Технологический стек¶

Слой	Технология	Версия	Назначение
Frontend	React	18	UI-библиотека
Frontend	TypeScript	5.x	Типизация
Frontend	Vite	5.x	Сборщик
Frontend	Ant Design	5.x	UI-компоненты
Frontend	Zustand	4.x	State management
Frontend	TanStack Query	5.x	Server state
Backend	Kotlin	1.9.24	Язык
Backend	Spring Boot	3.2.5	Фреймворк
Backend	Spring Security	—	Авторизация (JWT)
Backend	Liquibase	—	Миграции БД
Backend	JJWT	0.12.5	JWT-токены
ML	Python	3.11	Язык
ML	FastAPI	0.115	REST-фреймворк
ML	PyTorch	2.0+	Deep learning
ML	scikit-learn	1.3+	ML-модели
Database	PostgreSQL	15	РСУБД
Storage	MinIO	latest	S3-хранилище
Infra	k3s	1.32	Kubernetes
Infra	Traefik	—	Ingress + TLS
Infra	GitHub Actions	—	CI/CD
Infra	Harbor	—	Container registry

Домены и точки доступа¶

Домен	Сервис	Протокол
`plechiki.ru.dmitriy.space`	Frontend (React SPA)	HTTPS (TLS, Let's Encrypt)
`api.plechiki.ru.dmitriy.space`	Backend API	HTTPS, REST/JSON
`minio.plechiki.ru.dmitriy.space`	MinIO Console	HTTPS
`minio-api.plechiki.ru.dmitriy.space`	MinIO S3 API	HTTPS, S3 protocol

Протоколы взаимодействия¶

Frontend ↔ Backend: REST API через HTTPS. Авторизация — JWT Bearer-токен в заголовке Authorization. Access-токен + Refresh-токен.
Backend ↔ PostgreSQL: JDBC через TCP (порт 5432). Spring Data JPA для ORM.
Backend ↔ MinIO: S3 API через HTTPS. Загрузка/удаление объектов. MinIO Java SDK.
Backend ↔ ML: HTTP/JSON внутри кластера (http://ml:8000). Multipart для отправки изображений, JSON для предсказаний.
Frontend ↔ MinIO: Прямой HTTPS GET для загрузки изображений (публичные URL).

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

Добавление вещи¶

Пользователь → [фото] → Frontend → Backend (POST /media) → MinIO (сохранение)
                                   → Backend → ML Service (POST /attributes) → predictions
                                   → Backend (POST /items, сохранение в PostgreSQL)
                                   → Frontend (отображение с предсказаниями)

Генерация фида¶

Frontend (GET /feed) → Backend → PostgreSQL (публичные образы)
                               → ML Service (scoring, ranking)
                               → Backend → Frontend (лента образов)

Шеринг образа¶

Frontend (POST /outfits/{id}/share) → Backend → генерация токена → PostgreSQL
                                    → ShareLink URL → Frontend → получатель
Получатель → GET /share/{token} → Backend → outfit + view_count++
           → POST /share/{token} → Backend → копия образа + claim_count++