Add local development environment with switchable backend

Set up local dev workflow: SSH tunnel to dev DB, Next.js API proxy
via rewrites, Docker or native backend on port 5000. Update and
restructure project documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -28,7 +28,13 @@ GBSite/
 │   └── Dockerfile      # Multi-stage: dotnet sdk → aspnet runtime
 ├── deploy/
 │   ├── docker-compose.prod.yml
-│   └── docker-compose.dev.yml
+│   ├── docker-compose.dev.yml
+│   └── docker-compose.local.yml  # Local backend (Docker mode)
+├── scripts/
+│   ├── local-tunnel.ps1          # SSH tunnel to dev DB
+│   ├── local-backend-docker.ps1  # Start Docker backend
+│   ├── local-backend-dotnet.ps1  # Start native backend
+│   └── local-frontend.ps1       # Start frontend dev server
 ├── .woodpecker/
 │   └── deploy.yml      # CI/CD pipeline
 └── CLAUDE.md           # This file
@@ -40,8 +46,9 @@ GBSite/
 |-----|-------------|---------|-----|
 | **Prod** | https://new.goodbrick.com.ua | https://new.goodbrick.com.ua/api/* | prod_db |
 | **Dev** | https://dev.goodbrick.com.ua | https://dev.goodbrick.com.ua/api/* | dev_db |
+| **Local** | http://localhost:3000 | http://localhost:5000/api/* | dev_db (via SSH tunnel) |
 
-## Docker Containers
+## Docker Containers (Server)
 
 | Container | Internal Port | Host Port | Network |
 |-----------|--------------|-----------|---------|
@@ -58,7 +65,48 @@ Path-based routing — один домен для фронта и API:
 
 Backend получает запросы с prefix `/api/` (Caddy использует `handle`, не `handle_path`).
 
-## Development
+## Local Development
+
+### Quick Start (3 терминала)
+
+**Terminal 1 — SSH Tunnel (всегда нужен):**
+```powershell
+.\scripts\local-tunnel.ps1
+```
+
+**Terminal 2 — Backend (выбрать один):**
+```powershell
+# Работа с фронтом — бэкенд в Docker:
+.\scripts\local-backend-docker.ps1
+
+# Работа с бэком — dotnet run с hot-reload:
+.\scripts\local-backend-dotnet.ps1
+```
+
+**Terminal 3 — Frontend:**
+```powershell
+.\scripts\local-frontend.ps1
+```
+
+### Как это работает
+
+- **SSH Tunnel:** `localhost:5433` → сервер `31.131.18.254:5432` (dev_db)
+- **Backend:** слушает на `localhost:5000`, подключается к БД через туннель
+- **Frontend:** `npm run dev` на `:3000`, Next.js rewrites проксируют `/api/*` → `localhost:5000`
+- **Переключение режимов:** Ctrl+C в терминале с бэком, запустить другой скрипт. Фронт перезапускать не нужно.
+
+### Конфигурация
+
+- `backend/src/GBSite.Api/appsettings.Local.json` — connection string к dev_db (gitignored)
+- `frontend/.env.local` — `LOCAL_API_URL` и `INTERNAL_API_URL` для локального проксирования
+- `deploy/docker-compose.local.yml` — Docker backend с `host.docker.internal:5433`
+
+### URLs
+- Frontend: http://localhost:3000
+- Backend API: http://localhost:5000/api/health
+- DB: localhost:5433 (через SSH tunnel к dev_db)
+
+## Development (manual)
 
 ### Frontend
 ```bash
@@ -91,7 +139,7 @@ cd backend && dotnet build
 - `src/components/` — React components (create when needed)
 - shadcn/ui components via `npx shadcn@latest add <component>`
 - Server-side calls to backend use `INTERNAL_API_URL` env var
-- Client-side calls use relative paths (`/api/...`) — Caddy proxies them
+- Client-side calls use relative paths (`/api/...`) — Caddy proxies them on server, Next.js rewrites locally
 
 ## Git & CI/CD
 
@@ -118,6 +166,7 @@ Host=postgres;Port=5432;Database={db};Username={user};Password={pass}
 ```
 
 Configured via env var `ConnectionStrings__Default` in docker-compose files.
+Locally via `appsettings.Local.json` with SSH tunnel (`localhost:5433`).
 
 ## Key Rules
 
@@ -125,3 +174,4 @@ Configured via env var `ConnectionStrings__Default` in docker-compose files.
 - Frontend standalone output (`output: "standalone"` in next.config.ts) — required for Docker
 - Backend listens on port 5000 (`ASPNETCORE_URLS=http://+:5000`)
 - All containers must be in `app-network` (external Docker network)
+- `appsettings.Local.json` is gitignored — local dev overrides only