docs/QUICKSTART_DEMO.md

Quickstart Demo — 5 Dakikada Hasarİ / 5-Minute Hasarİ Demo

Bu rehber tek bir hedef için yazıldı: yeni bir geliştiricinin ya da değerlendiricinin 5 dakika içinde çalışan bir Hasarİ demo'su görmesi. Eğitim, üretim deploy veya derin mimari için README ve diğer dokümanlara bak.

This guide has a single goal: get a new developer or evaluator from zero to a working Hasarİ demo in 5 minutes. For training, production deployment, or deep architecture, see the README and other guides.

---

İçindekiler / Table of contents

• Türkçe
  • Önkoşullar
  • Adımlar
  • Beklenen çıktı
  • Sorun giderme
• English
  • Prerequisites
  • Steps
  • Expected output
  • Troubleshooting

---

Türkçe

Önkoşullar

Aşağıdakileri önceden kurmuş olmalısın. Toplam disk ~3 GB, RAM ≥ 8 GB öneriyoruz.

Araç	Sürüm	Doğrulama
Docker Desktop	≥ 24.0 (Compose v2 dahili)	docker --version ve docker compose version
Node.js	20 LTS ya da üzeri	node --version
pnpm	9.0+	corepack enable && corepack prepare pnpm@9.12.0 --activate sonra pnpm --version
Git	herhangi yeni sürüm	git --version

GPU gerekmez. Bu demo backend'i CPU üzerinde çalıştırır (ML_DEVICE: cpu). GPU için bkz. DOCKER.md.

Model ağırlıkları: services/ml/runs/bundles/ altında en az bir snapshot olmalı. Repo bunu içermiyorsa, bkz. Sorun giderme — model weights.

Adımlar

1. Repo'yu al ve bağımlılıkları kur (~90 sn)

git clone https://github.com/your-org/arac-hasar-v2.git
cd arac-hasar-v2
pnpm install

2. Backend stack'i ayağa kaldır (~60 sn, ilk açılışta image build için biraz daha)

# Repo kökünden — Postgres + Redis + MinIO + FastAPI + Celery worker
docker compose up -d

Sağlık kontrolü:

docker compose ps                # tüm servisler "running"/"healthy" olmalı
curl http://localhost:8000/health
# {"status":"ok","ml_loaded":true,"version":"0.1.0", ...}

3. Web uygulamasını başlat (~5 sn) — ayrı terminal

pnpm dev:web

Çıktıda ▲ Next.js 15.x - Local: http://localhost:3000 görmelisin.

4. Tarayıcıdan demoyu aç

1. http://localhost:3000 — landing sayfası açılır.
2. Üst menüden Yeni inceleme → /inspect sayfasına git.
3. Sürükle-bırak alanına bir araç fotoğrafı bırak (JPG/PNG/WebP, < 12 MB). Elinde yoksa CarDD örneklerinden veya açık kaynak unsplash.com/s/photos/car-damage görsellerinden indir.
4. Mod: "Hızlı (sync)" seç (tek fotoğraf için).
5. İncelemeyi başlat → 5–15 saniyede sonuç ekranı açılır.

Beklenen çıktı

/results/{id} ekranında üç sekme görmelisin: Genel, Parçalar, Hasarlar. JSON şeması böyle olur:

+--------------------------------------------------------------+
|  Inspection #8c1f...                       toplam: 5.500 ₺   |
+--------------------------------------------------------------+
|  Genel  |  Parçalar  |  Hasarlar  |  Görselleştirme           |
+--------------------------------------------------------------+
|                                                              |
|  Hasarlı parça:   1   |   Hasarsız parça:   3                |
|  Toplam hasar:    2                                          |
|  Genel şiddet:    Orta                                       |
|  Öneri:           Tamir + boya gerekli                       |
|                                                              |
|  +----------------------------------------------------+      |
|  | ön_tampon                                  Orta    |      |
|  |  - Göçük (orta)         2.500 – 5.500 ₺            |      |
|  |  - Çizik (hafif)          400 – 1.200 ₺            |      |
|  +----------------------------------------------------+      |
|  | kaput                                     Temiz    |      |
|  +----------------------------------------------------+      |
|                                                              |
+--------------------------------------------------------------+

Visualization sekmesi: 3 maskeli PNG — annotated (damage + part overlay), parts (sadece parça maskeleri), damages (sadece hasar maskeleri). Backend bunları MinIO'da saklar ve presigned URL ile sunar.

API'den aynı sonucu komut satırından da alabilirsin:

$env:BASE = "http://localhost:8000"
# Önce hesap oluştur
$tokens = (curl -X POST "$env:BASE/auth/register" `
    -H "Content-Type: application/json" `
    -d '{"email":"demo@local.dev","password":"DemoPass1234"}' | ConvertFrom-Json)
$env:ACCESS_TOKEN = $tokens.access_token

# Sonra sync inceleme
curl -X POST "$env:BASE/api/v1/inspect/sync" `
    -H "Authorization: Bearer $env:ACCESS_TOKEN" `
    -F "file=@path\to\damage.jpg"

Sorun giderme

Belirti	Sebep	Çözüm
bind: address already in use :::5432	Yerel Postgres çalışıyor	docker compose down veya yerel Postgres servisini durdur (Stop-Service postgresql-x64-16)
bind: address already in use :::3000	Başka bir Next.js / Grafana 3000'i tutuyor	pnpm dev:web -- --port 3100 ile farklı port; ya da çakışan süreci kapat
bind: address already in use :::8000	Başka FastAPI / uvicorn süreci	docker compose down sonra Get-Process | Where-Object {$_.ProcessName -eq "python"} ile kontrol
Backend 200 ama /inspect sonsuz yükleniyor	Celery worker düşmüş ya da Redis bağlanmamış	docker compose logs worker redis
"ml_loaded": false 5 dakikadan uzun sürer	Model ağırlıkları eksik	services/ml/runs/bundles/ altına bir snapshot koy ya da MODEL_SNAPSHOT_DIR env'i ile yolu göster (bkz. docker-compose.yml yorumları)
MinIO console açıldı ama inspections bucket yok	minio-init container'ı erken kapanmış	docker compose up minio-init ile tekrar koştur; idempotent'tir
Web Failed to fetch http://localhost:8000	Backend henüz hazır değil	30-60 sn bekle, sonra curl http://localhost:8000/health
Tarayıcı Network Error / CORS	CORS_ORIGINS env'inde http://localhost:3000 yok	services/backend/.env'i kontrol; default değer 3000'i içerir

Daha fazlası: DEPLOY_GUIDE.md — Troubleshooting ve DOCKER.md.

---

English

Prerequisites

You must have these installed beforehand. Plan for ~3 GB disk, RAM ≥ 8 GB.

Tool	Version	Verify
Docker Desktop	≥ 24.0 (bundled Compose v2)	docker --version and docker compose version
Node.js	20 LTS or later	node --version
pnpm	9.0+	corepack enable && corepack prepare pnpm@9.12.0 --activate then pnpm --version
Git	any recent	git --version

No GPU required. This demo runs the backend on CPU (ML_DEVICE: cpu). For GPU, see DOCKER.md.

Model weights: at least one snapshot must exist under services/ml/runs/bundles/. If the repo does not ship one, see Troubleshooting — model weights.

Steps

1. Clone and install (~90 s)

git clone https://github.com/your-org/arac-hasar-v2.git
cd arac-hasar-v2
pnpm install

2. Bring up the backend stack (~60 s; longer on first image build)

# From the repo root — Postgres + Redis + MinIO + FastAPI + Celery worker
docker compose up -d

Health check:

docker compose ps                # all services must be running/healthy
curl http://localhost:8000/health
# {"status":"ok","ml_loaded":true,"version":"0.1.0", ...}

3. Start the web app (~5 s) — separate terminal

pnpm dev:web

You should see ▲ Next.js 15.x - Local: http://localhost:3000.

4. Open the demo in a browser

1. Visit http://localhost:3000 — the landing page loads.
2. From the top menu, click Yeni inceleme to reach /inspect.
3. Drag-drop a vehicle photo (JPG/PNG/WebP, < 12 MB). No sample? Pull one from unsplash.com/s/photos/car-damage or the public CarDD samples.
4. Mode: select "Hızlı (sync)" for a single photo.
5. Click İncelemeyi başlat — results render in 5–15 s.

Expected output

The /results/{id} view shows three tabs: Genel (Overview), Parçalar (Parts), Hasarlar (Damages):

+--------------------------------------------------------------+
|  Inspection #8c1f...                       total: 5,500 TL   |
+--------------------------------------------------------------+
|  Overview | Parts | Damages | Visualization                  |
+--------------------------------------------------------------+
|                                                              |
|  Damaged parts:  1   |   Clean parts:  3                     |
|  Total damages:  2                                           |
|  Overall:        Moderate                                    |
|  Recommendation: Repair + paint                              |
|                                                              |
|  +----------------------------------------------------+      |
|  | front_bumper                            moderate   |      |
|  |  - dent (moderate)      2,500 – 5,500 TL           |      |
|  |  - scratch (light)        400 – 1,200 TL           |      |
|  +----------------------------------------------------+      |
|  | hood                                       clean   |      |
|  +----------------------------------------------------+      |
|                                                              |
+--------------------------------------------------------------+

Visualization tab: 3 mask PNGs — annotated (damage + part overlay), parts (part masks only), damages (damage masks only). The backend persists them in MinIO and serves them via presigned URLs.

You can reach the same result from the shell:

export BASE=http://localhost:8000

# Create an account
TOKENS=$(curl -s -X POST "$BASE/auth/register" \
    -H "Content-Type: application/json" \
    -d '{"email":"demo@local.dev","password":"DemoPass1234"}')
ACCESS_TOKEN=$(echo "$TOKENS" | jq -r .access_token)

# Run a sync inspection
curl -X POST "$BASE/api/v1/inspect/sync" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -F "file=@path/to/damage.jpg"

Troubleshooting

Symptom	Cause	Fix
bind: address already in use :::5432	Local Postgres running	docker compose down, or stop the local service (brew services stop postgresql@16 / sudo systemctl stop postgresql)
bind: address already in use :::3000	Another Next.js / Grafana on 3000	pnpm dev:web -- --port 3100, or kill the conflicting process
bind: address already in use :::8000	Another uvicorn / FastAPI process	docker compose down, then lsof -i :8000 (macOS/Linux) or Get-NetTCPConnection -LocalPort 8000 (Windows)
Backend returns 200 but /inspect hangs forever	Celery worker crashed or Redis unreachable	docker compose logs worker redis
"ml_loaded": false for > 5 min	Model weights missing	Drop a snapshot into services/ml/runs/bundles/, or set MODEL_SNAPSHOT_DIR (see docker-compose.yml comments)
MinIO console up but inspections bucket missing	minio-init container exited too early	docker compose up minio-init (idempotent)
Web shows Failed to fetch http://localhost:8000	Backend still warming up	Wait 30–60 s, retry curl http://localhost:8000/health
Browser Network Error / CORS	CORS_ORIGINS env missing http://localhost:3000	Check services/backend/.env; the default includes port 3000

More: DEPLOY_GUIDE.md — Troubleshooting and DOCKER.md.

---

Next steps / Sonraki adımlar

• Run the desktop / mobile apps — see README.md → Hızlı başlangıç.
• Explore the REST API — docs/API_GUIDE.md.
• Understand the ML pipeline — docs/MODEL_GUIDE.md.
• Deploy to Render.com — docs/DEPLOY_GUIDE.md.