API Referansı

Kaza Rehberi backend’i Cloudflare Workers üzerinde çalışan, Hono tabanlı, tek bir createApp(deps) fabrikasından üretilen saf bir HTTP uygulamasıdır. Bu bölüm, portal/mobil/web istemcilerinin tükettiği HTTP sözleşmesini anlatır.

Mimari

• Çalışma zamanı: Cloudflare Workers (V8 isolate), wrangler ile deploy edilir.
• HTTP çatısı: Hono — hafif, Workers’a özgü, Express benzeri routing.
• Şema/doğrulama: iş uçlarının çoğu @hono/zod-openapi (OpenAPIHono) ile yazılır. Her uç bir zod şeması tanımlar; bu şema hem çalışma zamanında girdi/çıktıyı doğrular hem de OpenAPI belgesini üretir — yani kod ile doküman birbirinden asla sapmaz.
• Veritabanı: PostgreSQL, Drizzle ORM ile erişilir.
• Fabrika deseni: createApp(deps: AppDeps) runtime’dan tamamen bağımsızdır — deps içine DB bağlantısı, hata raportörü gibi bağımlılıklar enjekte edilir. Bu sayede aynı uygulama hem Workers’ta hem de Node üzerinde (yerel geliştirme, test) çalıştırılabilir.

app.ts
 ├─ /health                 (sürümsüz — Workers sağlık kontrolü)
 └─ /v1                     (OpenAPIHono — tüm iş uçları)
     ├─ /v1/doc             (OpenAPI 3.1 JSON — makine-okur)
     ├─ /v1/docs            (Swagger UI — tarayıcıda gezilebilir)
     └─ /v1/<kaynak>/...    (auth, hesaplamalar, araçlar, tazminat-dosyaları, ...)

Not

İş uçlarının tamamı /v1 öneki altındadır. /health ise sürümsüzdür — yük dengeleyici ve izleme araçları API sürümünden bağımsız olarak buraya istek atar.

Base URL

Ortam	Base URL
Prod	https://api.kazarehberi.com.tr

Örnek: tam bir hesaplama uç adresi şu şekilde kurulur:

https://api.kazarehberi.com.tr/v1/hesaplamalar/kazanc-kaybi

Sonraki adımlar

• Kimlik Doğrulama — Bearer JWT, public/girişli uçlar, mobil X-App-Key.
• Hata Formatı — tüm hataların ortak gövde biçimi.
• Sürümleme ve Belgeler — /v1/doc, /v1/docs, parametre versiyonu.
• Uç Katalogu — uç gruplarına genel bakış.
• İzinler — admin RBAC-lite matrisi.