Generative Design + Site Finder

Две продуктовые линии в одной воронке: Site Finder (AI-подбор инвестиционных земельных участков) + Generative Design (автоматическая генерация концепций застройки) для девелоперов РФ.

North Star

К концу месяца 3: 3 платящих пилота (≥30 тыс. ₽/мес каждый) + заявка в реестр российского ПО → право на Раунд А (20–25 млн ₽).

Acceptance criteria разбиты на 3 блока (функционально / бизнесово / технически). Правило перехода: 3/3 → Раунд А; 2/3 → продление Фазы 0 на 1–2 мес.; 1/3 или меньше → стоп проекта.

---

Структура репозитория

gendesign/
├── backend/                           # Python 3.12 / FastAPI / PostGIS
│   ├── pyproject.toml                 # uv-проект, ruff/mypy/pytest конфиги
│   ├── Dockerfile                     # с системными deps под Geo + WeasyPrint
│   ├── .env.example
│   ├── app/
│   │   ├── main.py                    # FastAPI + Sentry + /health
│   │   ├── core/                      # config (Pydantic Settings), db (SQLAlchemy)
│   │   ├── api/v1/                    # concepts.py, parcels.py
│   │   ├── schemas/                   # Pydantic-контракты для openapi-typescript
│   │   ├── services/
│   │   │   ├── generative/            # Stage 1: geometry, teap, financial
│   │   │   ├── site_finder/           # Stage 2: parser, scorer, filters
│   │   │   └── exporters/             # Stage 1c: pdf, excel, dxf
│   │   ├── models/parcel.py           # GeoAlchemy2 + PostGIS
│   │   └── workers/celery_app.py      # Stage 2a: daily PKK sync
│   └── tests/
├── frontend/                          # Next.js 15 / React 19 / TypeScript / Leaflet
│   ├── package.json                   # включая `npm run codegen` → openapi-typescript
│   ├── Dockerfile                     # multi-stage, output: standalone
│   └── src/app/
│       ├── page.tsx                   # / — главная
│       ├── concept/page.tsx           # /concept — Generative Design
│       └── site-finder/page.tsx       # /site-finder — Site Finder
├── memory/
│   └── memory-gendesign.jsonl         # хард-линк на C:\mcp\.aim — общий граф памяти
├── docs/                              # стратегические документы (бизнес-план, цели MVP)
├── docker-compose.yml                 # dev: Postgres + Redis + backend + frontend
├── docker-compose.prod.yml            # prod: образы из реестра + Caddy reverse-proxy
├── Caddyfile                          # авто-TLS Let's Encrypt
├── Makefile                           # make up / down / test / codegen / migrate
└── .github/workflows/
    ├── ci.yml                         # ruff + mypy(core) + pytest + frontend build
    └── deploy.yml                     # build → push в реестр → ssh deploy на VM

---

Технический стек (v2.2)

Backend: Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2, Alembic, Celery + Redis, httpx Geo: Shapely 2.0, GeoPandas, Pyproj (WGS84 ↔ МСК-66 для Свердловской обл.) ML: scikit-learn (XGBoost — отложен на Фазу 1, в Discovery эвристики) БД: PostgreSQL 16 + PostGIS 3.4, Redis 7 Frontend: Next.js 15, React 19, TypeScript 5, Tailwind 4, TanStack Query, Leaflet (Mapbox в Stage 2b) Экспорт: WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel) Dev: uv, ruff, mypy (strict только на core), pytest

---

Команда и порядок работы

2 фуллстек-разработчика, оба part-time 20 ч/нед — итого ~40 person-hours/нед, эффективных с координацией ~33.

Ритм:

• 1 синк/нед (30 мин, понедельник)
• daily-async в Telegram
• PR review обязательный
• Trunk-based: feature ветки ≤ 3 дней
• Codegen TS-типов из Pydantic (npm run codegen) — без этого 2 фуллстека плодят расхождения в API-контракте

Порядок: строго последовательный — Generative полностью, потом Site Finder.

---

Этапы MVP (12 недель)

Stage 0 — Скелет (нед. 1)

Монорепо backend+frontend, Docker с PostGIS+Redis, FastAPI hello, Next.js hello, openapi-typescript codegen, GitHub Actions CI, ruff + mypy(core) + pytest. Без JWT (single-tenant + X-Demo-User до Раунда А).

Stage 1 — Generative MVP (нед. 2–7)

• 1a (нед. 2–3): геометрия + API-контракт. Shapely-сервис (отступы, сетка), Pydantic-схемы, POST /api/v1/concepts с заглушкой. Фронт: страница /concept, Leaflet, импорт GeoJSON, форма параметров, 3 варианта в табах.
• 1b (нед. 4–5): алгоритм размещения. Жадное заполнение, 3 стратегии (max площадь / max инсоляция / balanced), STRtree для коллизий. Цель ≤10 сек, fallback 15 сек.
• 1c (нед. 6–7): ТЭП + финмодель + экспорты. WeasyPrint PDF, ezdxf, openpyxl. UI кнопок скачивания.

Acceptance Stage 1 (конец нед. 7): полигон → 3 варианта → ТЭП + финмодель → PDF/Excel/DXF. Это уже продаваемый артефакт — можно показывать на встречах с месяца 2.

Stage 2 — Site Finder MVP (нед. 8–12)

• 2a (нед. 8–9): data pipeline. Парсер ПКК Rosreestr (httpx async, retries), модель Parcel с GeoAlchemy2, ≥1000 участков Екатеринбурга. Overpass API для POI, ДОМ.РФ/ЦИАН для цен м², кеш в Redis.
• 2b (нед. 10–11): скоринг + API + UI. 3 критерия (расстояние до центра, плотность POI в 1 км, цена района), POST /api/v1/parcels/search. Карта с градацией по рейтингу, фильтры, карточка.
• 2c (нед. 12): интеграция + полировка. Кнопка «Обсчитать концепцию», демо-наполнение 50 участков, бэкапы БД, подача в реестр ПО.

Что урезано из v2.2 из-за part-time × 2

• XGBoost-скоринг → Фаза 1 (с реальными данными от пилотов)
• JWT-auth с refresh → перед Раундом А
• mypy --strict — только на core (generative/*, site_finder/scorer.py)
• Время генерации ≤ 15 сек как fallback (а не 10 сек)

---

Quick start (локально)

Требования: Docker Desktop, Node.js 20+, uv (для backend dev вне Docker).

# 1. Скопировать env-файлы
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# 2. Запустить всё
docker compose up -d --build
# или: make up

# 3. Проверить
curl http://localhost:8000/health
# → {"status":"ok","environment":"dev"}

# Frontend → http://localhost:3000
# Swagger docs → http://localhost:8000/docs

Полезное:

make logs                # tail логов всех сервисов
make backend-shell       # bash внутри backend контейнера
make migrate             # alembic upgrade head
make test                # pytest
make lint                # ruff check
make typecheck           # mypy на core
make codegen             # обновить TS-типы из OpenAPI

---

Хостинг (production)

Discovery MVP (мес. 1–3): минимальный режим

1× VPS на Selectel / Timeweb / Beget (2 vCPU / 4 GB / 60 GB SSD), всё в Docker Compose:

Компонент	Сервис
App	backend + frontend (образы из GHCR)
БД	Postgres 16 + PostGIS 3.4 (в том же compose)
Кэш/очереди	Redis 7
TLS	Caddy с Let's Encrypt автоматически
Бэкапы	cron pg_dump → Yandex Object Storage (free tier 1 GB)

Стоимость: ~1300–2000 ₽/мес (VPS) + ~17 ₽/мес (домен .ru) = ~1500–2000 ₽/мес.

⚠️ Критично: настроить ежесуточный pg_dump в первую неделю. Без бэкапа = смерть проекта при первом сбое VM.

Триггеры миграции на Yandex Cloud

Переезжаем на YC Managed PostgreSQL + Compute + Container Registry, когда:

• Подписан 3-й платящий пилот (~ конец мес. 3)
• Закрылся Раунд А
• Идёт переговор с госзаказчиком (нужен реестр ПО + солидная инфра)
• БД > 10 GB или появилось > 50 RPS

Стоимость production на YC: ~10–15 тыс ₽/мес.

GitHub Actions deploy

Workflow .github/workflows/deploy.yml собирает образы и через SSH деплоит на VM:

1. Build backend + frontend Docker образов
2. Push в реестр (GHCR для Discovery, YCR после миграции)
3. SSH на VM → docker compose pull && up -d

Secrets (GitHub → Settings → Secrets and variables → Actions):

• DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY, DEPLOY_PORT (опц.)
• Для GHCR — GITHUB_TOKEN встроенный, отдельный secret не нужен
• Для YC (после миграции) — YC_SA_JSON_CREDENTIALS, YC_REGISTRY_ID

---

Память проекта (knowledge graph)

Все решения, факты, риски, KPI, протоколы валидации хранятся только в графе памяти, не в .md-документах. Это решает проблему расхождения версий между документами.

Как устроено:

• MCP-сервер mcp-knowledge-graph пишет в C:\mcp\.aim\memory-gendesign.jsonl
• Этот файл — хард-линк на <repo>/memory/memory-gendesign.jsonl
• Изменения попадают в git автоматически
• Синхронизация между коллегами — через git pull / git push

Правило проекта (Feedback_MemoryFirst):

• Все факты и решения сохраняем в граф (context: "gendesign")
• .md / .docx / .pdf Claude не создаёт сам — только по явному запросу
• Источник правды = граф, документы = производные срезы

Рабочий цикл:

git pull                                      # перед началом работы
# ... сессия с Claude ...
git add memory/memory-gendesign.jsonl
git commit -m "Memory: <что добавили>"
git push

Конфликты в .jsonl обычно простые (файл построчный): git pull --rebase, оставить обе стороны, git rebase --continue.

Подключение коллеги

Краткая инструкция для нового участника команды (полная версия — у владельца репо):

1. Установить Claude Desktop, Node.js 20+, Git
2. Клонировать репо в C:\Users\<имя>\source\repos\gendesign
3. mkdir C:\mcp\.aim
4. Создать хард-линк:

   New-Item -ItemType HardLink `
     -Path C:\mcp\.aim\memory-gendesign.jsonl `
     -Value $PWD\memory\memory-gendesign.jsonl
   

5. Добавить в %APPDATA%\Claude\claude_desktop_config.json:

   "knowledge-graph": {
     "command": "npx",
     "args": ["-y", "mcp-knowledge-graph", "--memory-path", "C:\\mcp\\.aim"]
   }
   

6. Перезапустить Claude Desktop полностью (через трей)
7. Проверить: «Покажи память контекста gendesign»

---

Документы стратегии

В docs/:

• MVP_Goals_Python.md — цели Discovery MVP, Python-стек (v2.2, апрель 2026)
• Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md — бизнес-план

⚠️ Эти документы — снимок состояния на момент написания. Свежее состояние стратегии — в графе памяти. При расхождении доверяем графу.

---

Полезные ссылки

• Репо: https://github.com/lekss361/-gendesign
• Целевой регион Discovery: Свердловская обл. (Екатеринбург, ПЗЗ, МСК-66)
• Конкуренты: rTIM (только концепт-стадия, нет site-selection), TestFit (нет РФ-данных)