# GenDesign

Site Finder (AI-подбор инвест-участков) + Generative Design (концепции застройки) для девелоперов РФ.
Live: `https://gendsgn.ru/` — Свердловская обл. (ЕКБ, ПЗЗ, МСК-66).

## Stack

| Слой | Stack |
|---|---|
| Backend | Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2, Celery + Redis, httpx, Shapely 2 |
| DB | PostgreSQL 16 + PostGIS 3.4 (~50 таблиц, partitioned `rosreestr_deals`, GIST на geom) |
| Frontend | Next.js 15 app router, React 19, TypeScript 5 strict, Tailwind 4, TanStack Query |
| Export | WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel) |
| Tooling | uv, ruff, mypy strict (selective), pytest, pre-commit, prettier |
| Deploy | Beget VPS · GHA → GHCR → SSH → docker-compose · Caddy |
| Knowledge | Obsidian vault `obsidian.gendsgn.ru` (CouchDB LiveSync) |

## Commands

```bash
# Dev (Docker):
docker compose up -d --build
curl http://localhost:8000/health

# Backend without Docker:
cd backend && uv sync && uv run uvicorn app.main:app --reload

# Frontend:
cd frontend && npm install && npm run dev

# Migrations:
make migration NAME=add_foo_column   # Alembic
# или raw SQL: data/sql/NN_topic.sql  # views, partitions, indexes

# Tests:
cd backend && uv run pytest
cd frontend && npm test

# Lint + typecheck:
cd backend && uv run --no-project --with ruff ruff check app/
cd frontend && npx tsc --noEmit && npm run lint

# Regen TS types from OpenAPI:
cd frontend && npm run codegen
```

## Critical rules

1. **Knowledge = Obsidian vault only.** `mcp__obsidian__*` tools. Local mirror: `C:\Users\user\Documents\gendesign-memory`. Deprecated: `memory/memory-gendesign.jsonl` — не читай, не пиши.

2. **Branch + PR mandatory.** Никаких direct push в main. `feat/...` / `fix/...` / `refactor/...` / `docs/...` / `chore/...` → `gh pr create` → PR URL пользователю. После PR create — сразу `ScheduleWakeup` polling. **Полные правила: `.claude/rules/git-pr.md`**.

3. **Agent-first workflow.** Main session orchestrates ONLY — не пишет код inline. Любая задача >1 файл / >50 строк → subagent. Pre-push: spawn `code-reviewer` subagent на staged changes. Post-push review — внешнее окно Claude (НЕ дублировать).

4. **psycopg v3 only.** `import psycopg2` → ModuleNotFoundError. `CAST(:x AS type)` в SQL — никогда `:x::type`. **Полные правила: `.claude/rules/backend.md` + `sql.md`**.

5. **No `--no-verify` / `--force` / `--amend`.** Pre-commit hooks обязательны. Hook падает → fix root cause.

6. **Vault обновляется вместе с кодом** — в той же сессии. Bug → `fixes/`, module → `code/modules/`, decision → `decisions/`, runbook → `runbooks/`.

7. **Тестируй каждый merge** — chrome-devtools MCP или curl ДО/сразу после deploy. Не доверяй "тесты прошли" без verify.

## Subagents (`.claude/agents/`)

| Agent | Scope |
|---|---|
| `tech-analyst` | Нечёткая / cross-domain задача → план |
| `backend-engineer` | `backend/app/**` — FastAPI, Celery, scrapers, services |
| `frontend-engineer` | `frontend/src/**` — Next.js, React, hooks |
| `database-expert` | `data/sql/**.sql`, Alembic, EXPLAIN ANALYZE |
| `devops-engineer` | `docker-compose*.yml`, `Caddyfile`, `.github/workflows/**` |
| `code-reviewer` | Pre-push lint (security, correctness, conventions) |

**Routing:** тривиально (typo, 1-line) → main session. Single-domain clear → worker. Cross-domain / нечётко → `tech-analyst` first. Worker → `code-reviewer` → main commits → push → PR.

## Where to look

- **Path-scoped rules:** `.claude/rules/` (backend, frontend, sql, git-pr, deploy) — auto-loaded при работе с соответствующими файлами
- **Personal preferences:** `~/.claude/CLAUDE.md` (cross-project: no auto-commit, no Co-Authored-By, no @claude)
- **Workflow memory:** `~/.claude/projects/<repo>/memory/MEMORY.md` index
- **Vault MOCs:** `meta/`, `domains/<area>/<area>-MOC.md`, `decisions/`, `fixes/`, `limitations/`, `code/patterns/`
- **DB access:** SSH tunnel `ssh -N gendesign` → `localhost:15432` · Credentials: vault `meta/00_credentials.md`

## Don't

- ❌ `import psycopg2` — только psycopg v3
- ❌ Direct push в main / merge без approval
- ❌ `--no-verify` / `--amend` / `git push --force`
- ❌ `print()` в prod-коде — только `logger.*`
- ❌ `requests` — только `httpx`
- ❌ Knowledge-файлы вне vault (`docs/research/`, `notes/`, `wiki/`)
- ❌ `DROP TABLE` / `TRUNCATE` без явного approval
- ❌ Hardcode credentials в коде / коммитах

---

**Maintenance:** этот файл обновляется когда меняется tech stack, добавляются новые critical rules, или меняется структура rules/. **Цель: ≤150 lines.** Детали → `.claude/rules/` или vault.