kleekTo
CRM для агентств недвижимости. Рынок — Грузия.
Продукт состоит из веб-приложения и расширения Chrome. Агент открывает объявление на ss.ge или myhome.ge, сам раскрывает телефон собственника, звонит — и одним действием фиксирует результат разговора. Объект попадает в базу только после согласия собственника.
Интерфейс работает на трёх языках: грузинском, английском и русском.
Что нужно на машине
| Инструмент | Версия | Зачем |
|---|
| Node.js | 22 или новее | Используется встроенный process.loadEnvFile |
| pnpm | 11 или новее | Монорепозиторий на workspaces |
| Docker | любой свежий | Локальный PostgreSQL |
Проверить: node -v && pnpm -v && docker -v
Запуск с нуля
git clone <адрес репозитория>
cd kleekTo
pnpm install
cp .env.example .env # значения по умолчанию рабочие, править не нужно
pnpm db:up # поднять PostgreSQL в Docker
pnpm db:generate # сгенерировать клиент Prisma
pnpm db:migrate # применить миграции
pnpm db:seed # тестовые данные: две компании
pnpm dev # http://localhost:3000
Готово. Открой http://localhost:3000/api/v1/health — там должно быть:
{ "status": "ok", "database": "up", "version": "0.1.0", "databaseLatencyMs": 6 }
Если "status": "degraded" и код 503 — приложение живо, но не видит базу. Проверь pnpm db:up.
Команды
pnpm dev # веб-приложение в режиме разработки
pnpm build # сборка всех пакетов
pnpm typecheck # типы
pnpm lint # линтер и проверка форматирования
pnpm format # применить форматирование
pnpm test # тесты, база не нужна
pnpm test:integration # тесты на живой базе
pnpm db:up # поднять PostgreSQL
pnpm db:down # остановить
pnpm db:generate # клиент Prisma
pnpm db:migrate # применить миграции (разработка)
pnpm db:seed # тестовые данные: две компании, роли, статусы воронки
pnpm db:studio # просмотр базы в браузере
Перед коммитом должны быть зелёными все четыре: typecheck, lint, test, build. То же самое проверяет CI на каждый push.
Структура
apps/
web/ Next.js: интерфейс CRM и API по пути /api/v1/*
extension/ Chrome MV3
packages/
contracts/ Схемы запросов и ответов. Общие для веба и расширения
core/ Доменная логика: сценарии, права, аутентификация. О HTTP не знает
i18n/ Словари ka · en · ru и форматтеры
db/ Prisma: схема, миграции, клиент
scripts/
with-env.mjs Подаёт корневой .env инструментам, которые ищут его в другом месте
docs/ Спецификация, архитектура, решения, дизайн
Пакет adapters появится в фазе 5 вместе с адаптерами площадок. Пустых каталогов «на будущее» в репозитории нет намеренно.
Зависимости идут только вниз, циклы запрещены:
apps/web → contracts, core, db, i18n
apps/extension → contracts, i18n
packages/core → contracts, db
packages/db → (ничего)
packages/contracts, packages/i18n → (ничего)
Направление проверяется линтером: попытка импортировать логику площадки в ядро уронит CI, а не останется на усмотрение ревью.
Расширение Chrome
Собирается вместе со всем остальным (pnpm build) в apps/extension/dist.
Установка для разработки:
chrome://extensions → включить «Режим разработчика»;- «Загрузить распакованное» → выбрать
apps/extension/dist;
- открыть объявление на ss.ge или myhome.ge, раскрыть телефон на странице,
позвонить — и только потом вызвать расширение правым кликом или кнопкой.
Порядок здесь не формальность. Расширение читает DOM, который агент раскрыл
своими действиями: пока номер не раскрыт, импорт заблокирован и запрос к API
не уходит вообще (правило 11).
Адрес сервера подставляется на сборке и по умолчанию http://localhost:3000:
KLEEKTO_API_URL=https://app.example KLEEKTO_APP_URL=https://app.example pnpm --filter @kleekto/extension build
host_permissions в манифесте сборка приводит к этому же адресу — иначе
расширение стучалось бы туда, куда ему не разрешено, и получало сетевую ошибку
без внятной причины.
Окружение
Все переменные описаны в .env.example — каждая с объяснением, зачем она нужна. Файл .env в репозиторий не попадает никогда.
NODE_ENV в .env отсутствует намеренно: его выставляет сам инструмент. Значение в файле окружения сломало бы next start.
Окружение одно и лежит в корне, но Next ищет .env рядом с приложением, а Prisma — рядом с собой. Их примиряет scripts/with-env.mjs; поэтому команды запускаются через pnpm, а не напрямую.
Документы
| Файл | Что там |
|---|
CLAUDE.md | Правила проекта. Читается в начале каждой сессии |
docs/MASTER_PROMPT.md | Мастер-промпт: правила, фазы, гейты |
docs/spec/MASTER_PRODUCT_SPECIFICATION.md | Исходная спецификация. Не редактируется |
docs/architecture/ | Архитектура, модель данных, права, контракты API, дедупликация |
docs/decisions/ | ADR — по файлу на решение |
docs/design/DESIGN.md | Дизайн-система, экраны, состояния |
docs/progress.md | Журнал работы |
docs/analysis/ | Требования, противоречия, открытые вопросы, риски |
docs/AUDIT.md | Аудит перед запуском: что проверено, чем, и что осталось |
docs/DEPLOYMENT.md | Развёртывание на боевом окружении и установка расширения |
docs/launch-checklist.md | Чек-лист готовности к первому агентству |
Начинать чтение стоит с docs/architecture/system.md, затем erd.md.
Состояние
Фаза 8 из 10 — MVP собран. Полный путь агента работает от объявления
до объекта и обратно: расширение читает страницу, агент звонит и одним
пунктом меню фиксирует исход, объект появляется в CRM, движется по воронке
и виден в сводке.
Есть: домен и изоляция арендаторов, три роли с проверкой прав на сервере,
объекты и объявления, дедупликация четырёх уровней, миграция базы агентства,
адаптеры чтения ss.ge и myhome.ge, расширение Chrome, веб-интерфейс CRM,
дашборд по ролям, ограничение частоты входа, заголовки безопасности и CSP.
Перед первым агентством прочитайте docs/launch-checklist.md. Три пункта
блокируют пилот, и два из них кодом не закрываются.
Нет: заполнения форм размещения (ждёт фикстур формы), ленты выгодных
объявлений и общего индекса (фазы 9–10).
