Spaces:

erdoganpeker
/

hasari-api

Sleeping

App Files Files Community

hasari-api / README.md

erdoganpeker

deploy(hf): add repo-root Dockerfile + README front-matter for HF Spaces

852422c 17 days ago

preview code

raw

history blame contribute delete

18 kB

metadata

title: Hasari API
emoji: 🚗
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: AI-powered vehicle damage detection (FastAPI + YOLO11)

Hasarİ — Araç Hasar Tespiti v2

AI-powered, part-centric vehicle damage detection and cost estimation — web + desktop + mobile + backend + ML, all in one monorepo.

What it is

Hasarİ is a multi-platform application that detects damage on a car from a photograph, identifies which body part is affected, estimates the severity, and produces a Turkish-Lira repair cost range — in under 8 seconds. It targets minor everyday damage (bumper scratches, small dents, headlight cracks) where the cost of an in-person appraiser is disproportionate to the repair itself.

The system runs three YOLO models in parallel and merges their output with intelligent IoU matching, so every detected damage is anchored to a specific part. Clean (undamaged) parts are reported too, so the user sees the full vehicle view, not just a list of defects.

Features

Three platforms, one codebase: Next.js 15 web, Tauri 2 desktop (Win/macOS/Linux), React Native + Expo mobile (iOS/Android)
Three ML models running in parallel: damage segmentation (YOLO11m-seg, 6 classes), parts segmentation (YOLO11s-seg, 21 classes), severity classification (YOLO11n-cls, 3 classes)
Part-centric output: every damage is matched to a body part via IoU; every clean part is reported too
Turkish-Lira cost engine: ranges calibrated to local OEM/aftermarket parts and labor rates
Sync + async inspection modes: sync for ≤5 photos with inline results; async with Celery + Redis for batches up to 20 with WebSocket progress
JWT auth + legacy API-key fallback: full register/login/refresh flow, role-based admin
Bilingual UI: Turkish (primary) and English across all three apps via next-intl (web) and i18next (mobile/desktop)
Production-grade backend: FastAPI + Postgres + Redis + S3/MinIO + Alembic migrations + Prometheus metrics
Internationalized cost & damage labels: damage types and 21 part names available in TR/EN

Tech stack

Layer	Stack
Web	Next.js 15 (App Router), React 18, Tailwind CSS, next-intl
Desktop	Tauri 2, Vite, React 18, Tailwind, i18next
Mobile	React Native + Expo, i18next, expo-secure-store
Backend	FastAPI, Celery, SQLAlchemy, Pydantic v2, Alembic
Datastore	Postgres 16, Redis 7, MinIO (S3-compatible)
ML	PyTorch 2.4 (CUDA 12.8), Ultralytics YOLO11 (m-seg, s-seg, n-cls)
Observability	Prometheus, Grafana, Sentry (planned)
Deploy	Docker Compose (dev), Render.com (pilot)

Quick start

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

# 2. Start backend (Postgres + Redis + MinIO + FastAPI + Celery) — from repo root
docker compose up -d                                         # detached: api on :8000, MinIO on :9000/:9001

# 3. Web (separate terminal, from repo root)
pnpm dev:web                                                 # http://localhost:3000

Then visit http://localhost:3000. Swagger lives at http://localhost:8000/docs. See Hızlı başlangıç below for desktop, mobile, ML, and data setup. New to the project? Follow the 5-minute demo guide → docs/QUICKSTART_DEMO.md.

Architecture

                          ┌──────────────────────┐
                          │   FastAPI Backend    │
                          │  + Celery + Redis    │
                          │  + Postgres + MinIO  │
                          └──────────┬───────────┘
                                     │ /api/v1/*  (REST + WebSocket)
        ┌────────────────┬───────────┴─────────────┬───────────────┐
        │                │                         │               │
   ┌────┴─────┐     ┌────┴─────┐             ┌─────┴─────┐    ┌────┴────┐
   │ Next.js  │     │ Tauri 2  │             │ React     │    │  ML     │
   │  Web     │     │ Desktop  │             │ Native    │    │ Pipeline│
   │ (3000)   │     │ (native) │             │ Mobile    │    │ YOLO11  │
   └──────────┘     └──────────┘             └───────────┘    └─────────┘
        └────────── packages/ui (shared React) ───┘
        └────────── packages/types (shared TS contract) ─┘

Inference flow (single image):

upload → S3 → ┬─ damage YOLO11m-seg ──┐
              ├─ parts  YOLO11s-seg ──┼─→ IoU match → severity classifier (per damage crop)
              └─ severity yolo11n-cls─┘                       │
                                                              ▼
                                                  Part-centric output → cost engine → JSON

Repository layout

arac-hasar-v2/
├── apps/
│   ├── web/                  # Next.js 15 — public web app
│   │   ├── app/              # App Router pages
│   │   ├── components/       # Header, Footer, PartList, ResultsTabs
│   │   └── messages/         # tr.json, en.json (next-intl)
│   ├── desktop/              # Tauri 2 + Vite — Windows/macOS/Linux
│   │   ├── src/
│   │   │   └── locales/      # tr.json, en.json (i18next)
│   │   └── src-tauri/        # Rust shell
│   └── mobile/               # React Native + Expo — iOS/Android
│       ├── screens/
│       └── locales/          # tr.json, en.json (i18next)
├── packages/
│   ├── ui/                   # Shared React components + Tailwind preset
│   └── types/                # Backend ↔ frontend TS contract
├── services/
│   ├── backend/              # FastAPI + Celery + Postgres + S3/MinIO
│   │   ├── main.py           # routes
│   │   ├── auth.py           # JWT register/login/refresh/me
│   │   ├── ml_service.py     # in-process model wrapper
│   │   ├── worker.py         # Celery tasks
│   │   ├── ws.py             # WebSocket progress channel
│   │   └── migrations/       # Alembic
│   └── ml/                   # YOLO11 training, pipeline, severity, cost engine
│       ├── pipeline.py
│       ├── train_all.py      # orchestrator
│       ├── cost_engine.py
│       └── runs/             # training artifacts (DO NOT TOUCH while training)
├── scripts/                  # Dataset download + verification
├── tools/                    # Model export (TFLite/CoreML/ONNX), regression
├── observability/            # Prometheus + Grafana configs
├── docs/                     # Operational guides (see below)
└── render.yaml               # Render.com deploy spec

Documentation

Document	Audience	What's inside
docs/QUICKSTART_DEMO.md	First-time evaluators	5-minute "see the demo working" walkthrough (TR + EN) with troubleshooting
docs/API_GUIDE.md	Backend integrators	Every REST endpoint with curl examples, request/response schemas, error codes
docs/AUTH_FLOW.md	Frontend developers	JWT register/login/refresh sequence diagrams, token TTLs, per-platform storage
docs/DEPLOY_GUIDE.md	DevOps / operators	Render.com walkthrough, env vars, smoke tests, rollback
docs/USER_GUIDE_TR.md	End users (Turkish)	Adım adım inceleme rehberi — web/mobil/desktop
docs/MODEL_GUIDE.md	ML engineers	Model performance, retraining commands, known failure modes
ARCHITECTURE.md	Engineers	Pipeline internals, IoU matching, part-centric reorganization
DATA.md	ML / data engineers	Datasets, licenses, training order
services/backend/README.md	Backend devs	Endpoint list, auth, env vars
docs/PILOT_ONBOARDING.md	Pilot customers	First-week setup checklist
docs/LAUNCH_CHECKLIST.md	Engineering / PM	Pre-launch sign-off gates
docs/SECURITY.md	Security / compliance	Threat model, KVKK/GDPR notes

ML model performance

Model	Architecture	Classes	Dataset	Epochs	Key metric	Inference (RTX 5050 8GB)
Damage segmentation	YOLO11m-seg	6	CarDD (academic, ~4k images)	120	mAP50_M = 0.683, mAP50-95_M = 0.509	~45 ms/image
Parts segmentation	YOLO11s-seg	21	Combined parts (Roboflow + CarPartsDB)	50	mAP50_M ≈ 0.72	~30 ms/image
Severity classifier	YOLO11n-cls	3 (hafif/orta/agir)	Roboflow Severity	30	val_acc = 0.742	~12 ms/crop

All three models run in parallel per image; end-to-end (model + IoU match + severity per damage + cost) is well under 8 seconds for typical 4-photo inspections. See docs/MODEL_GUIDE.md for full performance breakdown, known limitations, and retraining instructions.

Hızlı başlangıç (Türkçe)

Önkoşullar

Node.js 20+ ve pnpm 9+ (corepack enable && corepack prepare pnpm@9.12.0 --activate)
Python 3.11 (ML için)
Docker + Docker Compose (backend stack için)
Rust 1.77+ (sadece desktop için, rustup ile)
NVIDIA GPU + CUDA 12.8+ (eğitim için, opsiyonel)

1-2. Bağımlılıklar + backend

pnpm install
# Repo kökünden — backend stack (FastAPI + Celery + Postgres + Redis + MinIO):
docker compose up -d
# Swagger:       http://localhost:8000/docs
# MinIO console: http://localhost:9001  (minioadmin/minioadmin)
# Postgres:      localhost:5432   Redis: localhost:6379

Alternatif: services\backend\docker-compose.yml ML-bundled (GPU) varyantını içerir. Sıradan dev için repo kökündeki compose yeterlidir.

3. Web (paralel terminal)

pnpm dev:web                                                 # http://localhost:3000

4. Desktop (paralel terminal)

pnpm --filter @arac-hasar/desktop tauri:dev

5. Mobile (Expo)

pnpm --filter @arac-hasar/mobile start
# Expo Go ile QR tara, veya iOS/Android emülatör

6. ML ortamı (eğitim için)

cd services\ml
powershell -ExecutionPolicy Bypass -File setup.ps1
# Linux/macOS/WSL: bash setup.sh

7. Veri

python scripts\download_pretrained.py --all
python scripts\download_data.py --cardd-hf
$env:ROBOFLOW_API_KEY = "..."
python scripts\download_data.py --roboflow-severity
python scripts\verify_data.py

Komut referansı

Komut	İşlevi
`pnpm dev:web`	Next.js dev server (3000)
`pnpm --filter @arac-hasar/desktop tauri:dev`	Tauri pencere + Vite HMR
`pnpm dev:mobile`	Expo Metro bundler
`pnpm backend:docker`	Tüm backend stack
`pnpm backend:dev`	Sadece FastAPI (uvicorn reload, host 0.0.0.0:8000 — venv'yi önceden aktive et)
`pnpm data:download`	Veri indirme orchestrator
`pnpm build`	Tüm uygulamaları derle
`pnpm typecheck`	Tüm workspace'te TS kontrolü

API contract (summary)

Backend endpoints (full reference: docs/API_GUIDE.md):

Method	Path	Description
`POST`	`/auth/register`	Create user, returns access + refresh tokens
`POST`	`/auth/login`	Email + password → tokens
`POST`	`/auth/refresh`	Refresh → new access token
`GET`	`/auth/me`	Current user
`GET`	`/health`	Health check (ml_loaded, status)
`GET`	`/api/v1/version`	Version + build info
`POST`	`/api/v1/inspect?mode=sync\|async`	Multi-image inspection
`POST`	`/api/v1/inspect/sync`	Single-image fast path
`GET`	`/api/v1/inspect/{id}`	Status + result
`GET`	`/api/v1/inspect/{id}/visualization/{annotated\|parts\|damages}`	Presigned PNG redirect
`GET`	`/api/v1/inspect`	Paginated history
`DELETE`	`/api/v1/inspect/{id}`	Delete (owner only)
`WS`	`/api/v1/inspect/{id}/stream`	Async progress push

Output format (part-centric)

{
  "inspection_id": "uuid",
  "parts": [
    {
      "name": "front_bumper",
      "name_tr": "Ön Tampon",
      "status": "moderate_damage",
      "damage_count": 2,
      "damages": [
        { "type": "dent", "type_tr": "Göçük", "severity": {"level": "orta"}, "cost": {"min_tl": 2500, "max_tl": 5500} },
        { "type": "scratch", "type_tr": "Çizik", "severity": {"level": "hafif"}, "cost": {"min_tl": 400, "max_tl": 1200} }
      ],
      "part_cost_min_tl": 2900,
      "part_cost_max_tl": 6700
    },
    { "name": "hood", "name_tr": "Kaput", "status": "clean", "damage_count": 0, "damages": [] }
  ],
  "summary": {
    "damaged_parts_count": 3,
    "clean_parts_count": 4,
    "total_cost_range_tl": [6800, 14500],
    "repair_recommendation": "tamir_boya",
    "repair_recommendation_tr": "Tamir + boya gerekli"
  }
}

Full schema lives in packages/types/src/inspection.ts.

Yol haritası

v0.1 (MVP — tamamlandı, pilot-production):

Monorepo iskeleti (pnpm workspace), paylaşılan packages/ui + packages/types
Backend FastAPI: JWT auth (register/login/refresh/me), /api/v1/inspect sync+async, WebSocket progress (/api/v1/inspect/{id}/stream), Postgres + Alembic migrations, Redis, S3/MinIO storage, Prometheus /metrics
ML pipeline: YOLO11m-seg (damage, 6 cls) + YOLO11s-seg (parts, 21 cls) + YOLO11n-cls (severity, 3 cls) paralel, IoU-eşleştirme, cost_table.yaml tabanlı TL maliyet motoru
Web (Next.js 15 App Router), Desktop (Tauri 2 + Vite), Mobile (RN + Expo)
TR/EN i18n her platformda (next-intl web, i18next desktop/mobile)
Docker Compose dev stack (repo kökü), Render.com pilot deploy spec (render.yaml)
Web auth cookie-based migration (hâlen localStorage — LAUNCH_CHECKLIST blok-eden madde)
httpOnly cookie + CSRF double-submit

v0.2 (4-6 hafta):

Mobile on-device kalite kontrol (TFLite YOLO11n) — tools/ altında export iskelet hazır
Maliyet motoru ML regresyonu (lookup tablo yerine, ~500 etiketli pilot örnekten sonra)
Refresh token revocation list (Redis-backed jti blocklist)
Türkçe araç markası fine-tune (Egea, Symbol, vb.)
Sentry release tag + Grafana production panelleri canlı (config zaten observability/)

v1.0 (3-6 ay):

VIN/plaka OCR + KVKK otomatik anonimleştirme (yüklemede yüz/plaka blur)
Fraud detection (deepfake/foto manipülasyon, EXIF tutarlılık)
B2B partner dashboard (sigorta acentesi, oto-ekspertiz)
TR yedek parça API'leri ile fiyat motorunun beslenmesi
Multi-region failover + KMS-managed JWT signing

License + disclaimer

This codebase is MIT licensed. Dataset licenses differ: CarDD is academic non-commercial — commercial use requires separate permission. See scripts/DATA_README.md.

KVKK / GDPR: License plates and VIN may be visible in raw uploads. Production use requires automated blurring / anonymization (v0.2 backlog item).

Contact

Maintainer: weblineet@gmail.com
Issues: GitHub issues

Known hardcoded strings — follow-up cleanup

While building locale files, the following hardcoded strings were spotted in source code that should eventually be moved to i18n keys. They are already covered by translation keys in apps/web/messages/{tr,en}.json (under home.*, nav.*, footer.*), but the components still inline literals:

Web (apps/web/):

app/page.tsx — hero copy, VALUE_PROPS array (driver-friendly, small-damage, local-pricing), FEATURES stats, preview card labels ("Ön tampon", "2 hasar", "3.500 – 5.200 ₺", "~2 iş günü tamir + boya yeterli"), CTA section. Use home.* keys.
components/Header.tsx — NAV array ("Yeni inceleme", "Geçmiş"), Hasarİ brand, "MVP", "Demo'yu dene", aria-label="Hasarİ ana sayfa". Use nav.* keys.
components/Footer.tsx — copyright string, "v0.1 MVP", "Türkiye için tasarlandı". Use footer.* keys.
app/inspect/page.tsx, app/history/page.tsx, app/results/[id]/page.tsx — currently call useTranslations, may have residual inline strings worth auditing.

Mobile (apps/mobile/screens/*) and Desktop (apps/desktop/src/**) — components were not exhaustively scanned in this pass; recommend grepping for raw Turkish strings (e.g. rg "[ğüşöçıİĞÜŞÖÇ]" apps/mobile/screens apps/desktop/src) before pilot launch and replacing with t('...') calls referencing the keys already shipped in the locale files.

Brand decision: locale files keep Hasarİ as the brand in both TR and EN per the existing source code. If a separate English brand is desired (e.g. "DamageAI"), update only common.appName in en.json files — the rest of the strings reference the namespace, not the literal.