Обзор системы Plechiki¶
Назначение¶
Plechiki — веб-приложение для цифровизации гардероба. Пользователь фотографирует вещи, система автоматически классифицирует их (категория, цвет, сезон) с помощью ML, позволяет составлять образы, делиться ими и получать рекомендации.
Архитектура системы¶
Система построена по микросервисной архитектуре. Все сервисы контейнеризированы и развёрнуты в Kubernetes-кластере.
C4Container
title Plechiki — Container Diagram
Person(user, "Пользователь", "Владелец гардероба")
System_Boundary(plechiki, "Plechiki Platform") {
Container(frontend, "Frontend", "React 18, TypeScript, Vite", "PWA: гардероб, образы, лента, шеринг")
Container(backend, "Backend API", "Kotlin, Spring Boot 3", "REST API: CRUD, авторизация, интеграция с ML")
ContainerDb(postgres, "PostgreSQL 15", "Реляционная БД", "Пользователи, вещи, образы, справочники")
Container(minio, "MinIO", "S3-совместимое хранилище", "Фотографии вещей, аватары, обложки")
Container(ml, "ML Service", "Python, FastAPI, PyTorch", "Классификация, эмбеддинги, рекомендации")
}
Rel(user, frontend, "HTTPS", "plechiki.ru.dmitriy.space")
Rel(frontend, backend, "REST/JSON", "api.plechiki.ru.dmitriy.space")
Rel(backend, postgres, "JDBC", "PostgreSQL protocol")
Rel(backend, minio, "S3 API", "minio-api.plechiki.ru.dmitriy.space")
Rel(backend, ml, "HTTP/JSON", "http://ml:8000")
Rel(frontend, minio, "HTTPS GET", "Загрузка изображений")
Сервисы и их роли¶
| Сервис | Технологии | Роль |
|---|---|---|
| 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 (лента образов)