Вступ та огляд платформи

Ласкаво просимо до офіційної документації інженерної екосистеми SmartFeed Studio!

SmartFeed Studio — це масштабована корпоративна платформа для парсингу, збагачення, валідації та синхронізації великих товарних каталогів (XML/CSV) з локальною шифрованою базою даних SQLite (SQLCipher), хмарним сховищем S3/Cloudflare R2 та високонадійним бекендом NestJS 11 CQRS.

---

🏛 Архітектурний ландшафт

Екосистема SmartFeed Studio побудована як єдиний монорепозиторій під керуванням Turborepo та складається з наступних ключових підсистем:

1. Десктопний клієнт (apps/desktop):

   • Технології: Tauri v2, React 18, Tailwind CSS, shadcn/ui.
   • База даних: Вбудована SQLite з повнодисковим шифруванням SQLCipher та безпечним зберіганням ключів у Keychain операційної системи.
   • Офлайн-першість: Можливість повноцінно працювати з каталогами, правилами націнок та постачальниками навіть без доступу до мережі.

2. Бекенд API (services/backend-api):

   • Технології: NestJS 11 CQRS, Prisma ORM, PostgreSQL 16, Redis 7, BullMQ.
   • Патерни: Відокремлення CommandBus та QueryBus (1 хендлер на файл), транзакційний Outbox, ідемпотентність черг задач, строгі валідації DTO.

3. Веб-портал адміністратора (apps/admin-portal):

   • Технології: Next.js 14 App Router, React Server Components.
   • Призначення: Керування користувачами, комерційними ліцензіями, квотами зберігання, аналітикою та тарифами.

4. Портал документації (apps/docs):

   • Технології: Astro Starlight, двомовність (UA / EN), вбудований повнотекстовий пошук Pagefind.

---

🧭 Навігація по розділах документації

• 🎯 Візія та місія продукту — цілі платформи, вирішення бізнес-болей селерів та дорожня карта.
• 🏛 Високорівнева архітектура системи — топологія монорепозиторію, зв’язки між сервісами та протоколи обміну.
• 📊 Технологічний стек — повний перелік інструментів та бібліотек за архітектурними шарами.
• 🔄 Принципи NestJS CQRS — опис шин Command, Query, EventBus та робота з чергами BullMQ.
• 📋 Моделі бази даних Prisma — структура таблиць PostgreSQL, FK-індекси та каскадні видалення.
• 🦀 Десктопна архітектура Tauri v2 — захист IPC, керування SQLCipher та нативні Rust-команди.
• 🧪 Стратегія тестування та QA — TDD підхід, покриття E2E тестами (Jest & Playwright), політика ізоляції тестових даних.

---

⚡ Швидкий старт для розробника

Для розгортання повного локального оточення розробника:

# 1. Запуск інфраструктурних сервісів (Postgres, Redis, MinIO, Mailpit)
pnpm docker:up

# 2. Генерація клієнта Prisma та міграції
pnpm prisma:generate
pnpm prisma:migrate

# 3. Запуск усіх сервісів у dev-режимі
pnpm dev

# 4. Запуск локального порталу документації
pnpm dev:docs

Сервер документації працює за адресою http://localhost:4321.