Архітектура

Прийнята архітектура · 1 жовтня 2026, варіант 2

Agentfy містить harness; API Store Deputy надає єдиний MCP; модуль OpenCart — захищений REST/JSON API. Store Deputy перевіряє підключення, контекст працівника/покупця, права, погодження й аудит, не створюючи другого harness. Connect → вхід/реєстрація → безпечне підключення → автоматичне створення агента в Agentfy з MCP Store Deputy → повернення в модуль. В app: команди, агенти, акаунт, білінг і чат із кожним агентом.

Це замінює попереднє рішення того самого дня про MCP безпосередньо в модулі. Код і прототипи нижче ще не реалізують нову інтеграцію. Сесії покупців і справжній кошик OpenCart мають окрему перевірену прив'язку; cookie залишається в магазині. Див. рішення про єдиний MCP: межі, етапи та подальша робота над контрактом.

Стан · 1 жовтня 2026. Код мають три частини з п'яти — API, застосунок і перша чернетка сайту, — і працюють вони лише на машині розробника. Сайт документації опубліковано. Адмін-панель не створено. Жодного справжнього магазину не підключено: усе, що описано як зроблене, перевірялося лише на двох локальних тестових магазинах.

Store Deputy складається з п'яти частин в одному репозиторії — API, застосунок, адмін-панель, сайт і документація — та невеликого модуля, який встановлюється в магазин. Ці п'ять частин засновник назвав 1 жовтня 2026 року. Код дотримується CleanSlice — архітектурного стандарту, який проєкт використовує для застосунків на NestJS і Nuxt. CleanSlice охоплює API, застосунок і адмін-панель; маркетинговий сайт, сайт документації та код на PHP він не описує, і на відповідних сторінках про це сказано.

Частини

Частина	Для чого	Хто користується	На чому	Стан
API	Знає людей, команди, ролі та підключені магазини. Єдина частина, яка звертається до магазину	Застосунок; згодом — адмін-панель і агенти	NestJS, Prisma, PostgreSQL	Основу зроблено; працює локально
Застосунок	Тут людина входить і підтверджує підключення магазину	Власники магазинів та їхні команди	Nuxt, Vue 3, Pinia, Tailwind	Вхід, реєстрацію та підключення зроблено; працює локально
Адмін-панель	Панель для тих, хто керує самим Store Deputy	Оператори платформи	Nuxt, якщо будувати так, як описує CleanSlice	Не створено; обсяг не визначено
Сайт	Маркетинговий сайт: те, що власник магазину читає, перш ніж вирішити спробувати продукт	Покупці	Nuxt, Vue 3, Tailwind	Зроблено першу чернетку: одна сторінка; працює локально
Документація	Внутрішня: дослідження, рішення, специфікації та прототипи дизайну	Команда й агенти, що працюють над продуктом	VitePress	Опубліковано
Модуль магазину	Встановлюється в OpenCart. Виконує підписані запити API і дає власникові кнопки Connect, Pause і Disconnect	Власник магазину; API	PHP 7.3+, OpenCart 3.0.3.5+	Підключення зроблено; запускалося лише на локальних тестових магазинах

Модуль магазину описано в REST 1.0, тут він не повторюється.

Як частини спілкуються

покупець ───▶ сайт              маркетингова сторінка
власник ────▶ застосунок ───┐   вхід, реєстрація, підключення
оператор ───▶ адмін-панель ─┤   не створено
                            ▼
                           API ─────── PostgreSQL
                            │
                            │  Bridge Protocol v1: підписані запити
                            ▼
                  модуль у магазині (OpenCart 3)

• Браузерні частини спілкуються лише з API. Клієнт API в застосунку генерується з опису маршрутів, який дає сам API, а не пишеться вручну.
• До магазину звертається лише API — за REST 1.0. Застосунок ніколи не викликає магазин.
• Підключення магазину проходить через три частини. Власник натискає Connect у модулі магазину й потрапляє в застосунок з одноразовим кодом. Застосунок просить API підключити магазин. API надсилає модулю підписаний запит, і власник повертається на сторінку модуля, з якої почав.

Чого CleanSlice вимагає від коду

CleanSlice поєднує дві ідеї. Код згруповано за функціями, а всередині кожної функції розділено за відповідальністю.

• Слайс — це одна функція в одній теці. Усе, що потрібно функції, лежить разом. Додати функцію — означає додати теку; зрозуміти функцію — означає прочитати одну теку.
• Три шари всередині слайса. Подання приймає ввід і оформлює вивід: контролери та форми запитів в API, сторінки й компоненти в браузерному застосунку. Домен містить правила та контракти для всього зовнішнього. Дані виконують ці контракти, звертаючись до бази або до іншого сервісу.
• Правила не залежать від інфраструктури. Доменний шар описує, що йому потрібно, у вигляді контракту — шлюзу (gateway). Шар даних його реалізує. Правило на кшталт «підключити магазин може лише власник або адмін» читається й перевіряється без бази даних і мережі.
• Службові слайси та слайси функцій. Службові (setup) несуть спільну інфраструктуру: підключення до бази, формат помилок, тему, клієнт API. Слайси функцій несуть сам продукт.
• Пов'язані слайси лежать у спільній теці-просторі імен. Вхід, команди та членство зібрано в user/. Сама батьківська тека коду не містить.
• Слайси зустрічаються через домен. Слайс може використовувати правила й типи іншого слайса, але не його шар даних.
• Імена. Теки слайсів — в однині (user, store); маршрути — у множині (/teams).
• Фіксований стек. NestJS і Prisma для API; Nuxt, Vue 3, Pinia і Tailwind для браузерних застосунків.
• Чотири фази, що узгоджуються. Загальний план, детальний план, реалізація, огляд — кожна узгоджується до початку наступної; спершу API, потім застосунок.

Коли джерела розходяться, порядок у цьому репозиторії такий: CleanSlice, потім настанова для агентів у репозиторії, потім наявний код.

Де репозиторій відступає від CleanSlice

CleanSlice	Тут	Чому
Схеми баз даних зі слайсів зшиває пакет prisma-import	Їх зшиває невеликий власний скрипт	Записана причина: пакет востаннє публікувався в лютому 2024 року під Prisma 4
Помилки форматує перехоплювач (interceptor)	Їх форматує глобальний фільтр винятків	Перехоплювач не бачить помилку, яку кинула перевірка входу, тож відповідь «не увійшов» прийшла б в іншому форматі
Стандарт NestJS показує контролер, що викликає шлюз; сторінка про шари — контролер, що викликає сервіс	Усюди контролер → сервіс → шлюз	Правила ролей — це бізнес-правила, їхнє місце в сервісі
В еталонному застосунку є службовий слайс упровадження залежностей	У застосунку його немає	Поки не потрібен. Сам CleanSlice лишає його для слайсів, яким потрібні підмінні або офлайн-реалізації
Компоненти інтерфейсу генерує shadcn-vue	П'ять компонентів написано вручну в тому самому стилі	Рішення від 29 вересня 2026 року. Повернутися до shadcn-vue, коли знадобляться діалоги, меню чи таблиці
У кожній теці компонентів є Provider.vue	У теці спільної шапки сторінки його немає	Помічено 1 жовтня 2026 року; як рішення не записано

Локальні адреси

Усе нижче — машина розробника. Публічної адреси продукт не має.

Частина	Порт	Примітка
Застосунок	4140
Адмін-панель	4141	Зарезервовано; нічого не запущено
API	4142	Інтерактивний опис маршрутів — за адресою /api
Тестові магазини	4143, 4144	OpenCart 3.0.3.5 і 3.0.5.1
База даних API	4145	PostgreSQL у Docker
Документація	4146	Попередній перегляд продакшн-збірки — на 4147
Локальний дашборд	4152	Посилання, стан сервісів і логи для розробника; не частина продукту
Сайт	4148

Що читати далі

• API — які слайси є і як один запит проходить крізь шари.
• Застосунок — що людина може зробити сьогодні і як застосунок влаштовано.
• Адмін-панель — що зарезервовано і що треба вирішити до початку роботи.
• Сайт — маркетинговий сайт: що на ньому, як його влаштовано і що вирішити далі.
• Документація — як влаштовано цей сайт і чому CleanSlice на нього не поширюється.
• План реалізації — цільовий дизайн роботи з каталогом, схвалень і завдань; нічого з цього ще не зроблено.