docs/ANALYTICS_AUDIT.md

Analytics & Observability Audit — apps/web

Tarih: 2026-05-16 Kapsam: Sadece web app (apps/web/). READ-ONLY audit, kod degisikligi yapilmadi. Hedef: Hangi event'lar takip ediliyor, hangileri eksik — vendor-neutral oneriler.

---

1. Mevcut Durum — Ne Var Ne Yok

1.1 Frontend analytics / product analytics

Katman	Durum	Kanit
GA4 (gtag.js)	YOK	apps/web/package.json icinde gtag, @next/third-parties yok; app/layout.tsx icinde <Script> veya gtag cagrisi yok.
Plausible	YOK	Dependency yok, layout'ta script tag'i yok.
PostHog	YOK	posthog-js / posthog-node dependency yok.
Mixpanel / Amplitude / Segment	YOK	Hicbir SDK referansi yok.
Google Tag Manager	YOK	GTM container snippet yok (<noscript> iframe, dataLayer push yok).
dataLayer array	YOK	Hicbir yerde init edilmiyor; event push edilmiyor.

Sonuc: Sifirdan baslayan temiz bir sayfa. Hicbir kullanici davranis verisi toplanmiyor.

1.2 Frontend error tracking / observability

Katman	Durum	Kanit
Sentry (web)	YOK	@sentry/nextjs veya @sentry/react dependency yok; sentry.client.config.ts yok.
Datadog RUM	YOK	@datadog/browser-rum yok.
LogRocket / FullStory	YOK	Dependency yok.
Web Vitals reporting	YOK	reportWebVitals veya next/web-vitals exporter kullanilmiyor.
Browser console error capture	YOK	Global window.onerror / unhandledrejection handler yok.

docs/OBSERVABILITY_SETUP.md dosyasi backend + React Native icin Sentry plani onermis, ancak web app icin Sentry plani belirtilmemis. Backend Prometheus + Grafana plani var; bunlar SRE tarafi, urun analytics'i degil.

1.3 X-Request-ID propagation (backend <-> frontend)

Backend tarafi dogru kurulmus:

• services/backend/middleware.py:99 — RequestIDMiddleware header'i kabul ediyor; yoksa UUID minting yapiyor.
• services/backend/middleware.py:123 — request.state.request_id set ediliyor.
• services/backend/middleware.py:178 — Yapisal access log request_id field'i ile yaziliyor.
• services/backend/middleware.py:265-266 — CORS allow_headers: ["X-Request-ID"] ve expose_headers: ["X-Request-ID"] her ikisi de var. Tarayicidan gonderim ve okuma teknik olarak mumkun.
• services/backend/main.py:374, 403 — Hata response'larinda request_id log'a yaziliyor.

Frontend tarafi eksik:

• apps/web/lib/api.ts icindeki axios request interceptor (line 75-81) X-Request-ID set etmiyor.
• Response interceptor (line 83-103) X-Request-ID okumuyor, log'a yazmiyor, hata mesaji ile birlikte yuzeye cikartmiyor.
• classifyApiError() (line 443+) request_id'yi ApiErrorInfo icine almiyor; kullaniciya hata gosterildiginde request_id gozukmuyor.

Sonuc: Kullanici "X" hatasini gordugunde, support'a yazip "Y zamani Z yaptim" disinda bilgi veremiyor. Backend log'larini grep'lemek icin kullanici ID'si + timestamp ile yaklasik eslesme yapmak gerekiyor — kirilgan. Bu P0 bos.

1.4 Cookie consent / KVKK uyum

Katman	Durum
Cookie consent banner	YOK
Consent Mode v2	YOK (zaten Google tag yok)
NEXT_LOCALE cookie	VAR (middleware.ts), strictly functional, KVKK kapsaminda "essential" — banner gerekmez.
Auth cookie (access_token)	VAR, essential.

Su an tracking olmadigi icin KVKK acidan temiz — ancak analytics ekleyince banner zorunlu olur. Hazirlikli olunmali.

---

2. Page View Tracking — Next.js 15 App Router Tuzaklari

2.1 Otomatik mi manuel mi?

Next.js 15 App Router'da otomatik page view yok. Pages Router'da router.events vardi; App Router'da bu API yok. Manuel olarak yapilir:

• usePathname() + useSearchParams() degistiginde event push edilir.
• Genellikle bir <AnalyticsListener /> client component'i app/layout.tsx'e mount edilir.

2.2 Locale prefix problemi — bu projede YOK ama

Bu proje next-intl'i path prefix'siz mod ile kullaniyor:

• apps/web/i18n.ts — locale NEXT_LOCALE cookie veya Accept-Language header'dan cozulur, URL'de /tr/ veya /en/ prefix YOK.
• Yani /inspect URL'i hem TR hem EN icin ayni; locale ayri bir dimension olarak event'a eklenmeli (custom property: locale: 'tr' | 'en').

Avantaj: Cift sayim problemi yok. Dezavantaj: Locale bilgisi event'a manuel eklenmedikce funnel analizinde gorulemez. Oneri: tum event'lara locale property'si push edilsin.

2.3 SPA navigation problemi

router.push('/results/${id}') ile gecisler full page reload yapmaz. Otomatik gtag/posthog config'i bunu yakalamayabilir. Manuel page_view event'i pathname degisiminde firlatilmali.

---

3. Funnel & Kritik Event'lar

3.1 Soft funnel adimlari (URL bazli)

/  (Anasayfa)
  -> /inspect          (Foto secimi / upload form)
    -> /results/[id]   (Sonuc bekleme + render)
      -> /inspect      (Tekrar — "yeni inceleme" CTA)

Auth funnel:

/  -> /login | /register  -> /dashboard  -> /inspect  -> /results

3.2 Eksik event listesi — P0 / P1 / P2

P0 (lansman oncesi mutlaka)

Event	Trigger	Properties	Neden P0
page_view	Pathname degisimi	path, locale, referrer, is_authenticated	Funnel temeli; bunsuz hicbir analiz yapilamaz.
inspection_started	apps/web/app/inspect/page.tsx — handleSubmit() icinde, createInspection() cagrilmadan once	file_count, mode (sync/async), total_bytes, locale	Funnel'in kalbi; conversion'in basladigini soyleyen tek sinyal.
inspection_completed	apps/web/lib/use-inspection-polling.ts — polling status === 'completed' doner donmez	inspection_id, duration_ms (started_at'a gore), damage_count, parts_affected, cost_estimated_total_tl (numeric), locale	Asil business event; cost_estimated_total_tl ARR proxy'si.
inspection_failed	Polling status === 'failed' veya handleSubmit catch	error_kind (classifyApiError cikti), status_code, request_id, phase (upload/processing)	Drop-off teshisi.
auth_register	auth-context.tsx — register() success	method: 'email', locale	Acquisition.
auth_login	auth-context.tsx — login() success	method: 'email', locale	Retention.
auth_logout	auth-context.tsx — logout() cagrisinda	(none)	Session uzunlugu.
api_error	axios response interceptor (reject path)	endpoint, status, error_kind, request_id	Frontend hata oranlarini Sentry disinda da olcmek icin.

P1 (lansman + ilk hafta)

Event	Trigger	Properties
language_changed	LanguageSwitcher.tsx — setLocale() icinde	from, to
upload_dropzone_files_added	apps/web/app/inspect/page.tsx onFiles()	file_count_added, total_size_bytes, mime_types[]
upload_dropzone_file_removed	removeFile() cagrisi	remaining_count
upload_mode_changed	ModeOption tikla	from, to
results_tab_switched	ResultsTabs.tsx tab tikla	tab, inspection_id
damage_highlighted	PartList veya badge tikla	part_id, damage_id
inspection_history_viewed	/history mount	page, page_size, result_count
inspection_deleted	inspections.delete() success	inspection_id

P2 (optimizasyon fazinda)

Event	Trigger	Properties
web_vital_lcp / _cls / _inp	reportWebVitals	value, path
cta_clicked	Anasayfa hero/CTA butonlari	cta_name, position
error_boundary_caught	React error boundary	component, error_message
inspection_polling_timeout	use-inspection-polling.ts — timedOut true	inspection_id, attempts
api_key_created / revoked	apiKeys.create/revoke	key_id

3.3 Drop-off noktalari (event'lar dogru kurulursa)

Su funnel PostHog/GA4'te kurulabilir:

1. page_view path=/inspect ->
2. upload_dropzone_files_added ->
3. inspection_started ->
4. inspection_completed

Her adim arasi drop-off oraninin (%) ayri kovalarda izlenmesi gerekir. Ozellikle 2 -> 3 arasi (dosya secilmis ama submit edilmemis) yuksek olursa form UX problemi var demektir.

---

4. A/B Test Altyapisi

Vendor	Durum	Tavsiye
GrowthBook	YOK	Self-hosted, KVKK uyumu kolay — gerektiginde tercih.
LaunchDarkly	YOK	Pahali, MVP icin overkill.
Vercel Edge Config / Feature Flags	YOK	Eger Vercel'e deploy edilirse en dusuk surtunmeli secim.
PostHog Feature Flags	YOK	PostHog secilirse dahili, ekstra entegrasyona gerek yok.

Su an oneri: KURMA. A/B testi sadece istatistiksel anlamli trafikte (haftalik 1K+ kullanici/varyant) ise yarar. MVP'de copy ve buton degisiklikleri elle yapilir; analytics event'lar zaten yeterli ipucu verir. Trafik 10K MAU'ya ulastiginda yeniden degerlendirilir.

---

5. Vendor-Neutral SDK Onerileri (KURMA, sadece karsilastir)

Asagidaki tablo karar verme aracidir; secimi proje sahibi yapacak.

Ihtiyac	Aday A	Aday B	KVKK
Product analytics (event + funnel)	PostHog Cloud EU (Frankfurt)	Self-host PostHog (Docker, 2-3 GB RAM)	EU region zorunlu; A daha hizli kurulur, B daha temiz veri ikametgahi.
Tag manager	GTM (web) — tek script, sonradan tag eklenir	dogrudan SDK init (manager yok)	GTM consent mode v2 destegi var; banner ile entegre olabilir.
Frontend error tracking	Sentry SaaS EU (Frankfurt)	GlitchTip self-hosted (Sentry-compatible OSS)	A hizli; B veri ikamet kontrolu.
Cookie banner	CookieYes / Cookiebot	Custom UI (3-4 saatlik is)	TR icinde tutarsa custom daha gungormus; KVKK + GDPR ortak ise SaaS.
Web vitals	Next.js reportWebVitals -> PostHog/Sentry	Vercel Analytics	Native, ekstra SDK gerekmez.

Onerilen minimum stack (KVKK uyumlu):

1. GTM container layout'a tek script olarak gomulur (consent gated).
2. PostHog (EU) GTM uzerinden cookie consent sonrasi yuklenir; tum kritik event'lar posthog.capture() ile.
3. Sentry browser SDK layout'a Sentry.init() ile gomulur — error tracking consent gerektirmez (legitimate interest, PII redact'li), DSN'i .env'den.
4. Custom cookie banner (necessary / analytics / marketing 3 kategori) — Turkce/Ingilizce, mevcut next-intl messages dosyalarina eklenir.

Tek vendor cozumu istenirse: PostHog (analytics + error tracking + session replay + feature flags hepsi tek paket). Tradeoff: session replay'in performans maliyeti ve KVKK acisindan ek ozen.

---

6. Backend <-> Frontend Log Korelasyonu — Eylem Plani

Backend hazir, frontend eksik. Onerilen (kod ekleme degil, plan):

1. apps/web/lib/api.ts request interceptor'da her cagri oncesi crypto.randomUUID() ile bir X-Request-ID uretilip header'a eklenir. Backend zaten kabul ediyor (middleware.py:122).
2. Response interceptor'da response.headers['x-request-id'] okunup response.config veya context'e yazilir.
3. Reject path'inde error.response.headers['x-request-id'] ApiErrorInfo.requestId field'ina eklenir.
4. classifyApiError doneren tip'e requestId?: string eklenir.
5. Hata UI'larinda (ornegin apps/web/app/results/[id]/page.tsx'deki ErrorBanner, inspect/page.tsx'deki alert) request_id kucuk monospace yazi olarak gosterilir: Hata kodu: a1b2c3d4 — support'a iletilebilir.
6. api_error event'inde request_id property olarak gonderilir; bu sayede analytics dashboard'da hata bir tikla backend log'unda aranabilir.

Korelasyon zinciri (hedef)

Kullanici hata gorur (UI'da request_id: a1b2c3d4)
   |
   v
api_error event PostHog/Sentry'ye gider (request_id: a1b2c3d4)
   |
   v
SRE PostHog'da event'i bulur, request_id kopyalar
   |
   v
Backend log aggregator'da (Loki/CloudWatch) request_id="a1b2c3d4" ile filtre
   |
   v
Tam request trace + stack trace

Bu zincir kurulmadan, production'da gelen "calismadi" sikayetlerinin %70'i teshis edilemeyecek.

---

7. Ozet Karar Listesi (P0 / P1 / P2)

P0 — Lansman blocker (kurulmadan canli alinmamali)

• Cookie consent banner (3 kategori: necessary / analytics / marketing) + KVKK/GDPR metni.
• GTM container layout'a gomulu (henuz tag yok, infra hazir).
• PostHog (veya secilen analytics) consent-gated yuklenir.
• Frontend X-Request-ID set + read + UI'da goster.
• Event'lar: page_view, inspection_started, inspection_completed, inspection_failed, auth_register, auth_login, auth_logout, api_error.
• Sentry browser SDK (PII scrubbing on).

P1 — Lansman + ilk hafta

• language_changed, upload UX event'lari, results tab/highlight event'lari.
• Funnel dashboard'i (anasayfa -> inspect -> results) PostHog/GA4'te kurulu.
• Crash-free user rate alert (Sentry).

P2 — Optimizasyon fazinda

• Web vitals (LCP/CLS/INP) raporlama.
• Feature flag altyapisi (10K MAU sonrasi).
• Session replay (eger PostHog secildiyse, KVKK degerlendirmesi sonrasi).

---

8. Bulgu Ozeti

• Web app'te hicbir analytics SDK yok — temiz sayfa, blank slate.
• Frontend error tracking yok — production'a cikilirsa hatalar gormezden gelinir.
• Backend X-Request-ID propagation hazir, frontend kullanmiyor — en hizli ROI'li tek dokunus burada.
• Path-prefixless i18n sayesinde locale cift sayim problemi yok; ama locale event property olarak gonderilmeli.
• App Router otomatik page_view yok — manuel kurulum gerekir.
• A/B test altyapisi gerek yok (henuz).
• KVKK su an temiz, ama analytics girince banner zorunlu olur — hazirlikli baslanmali.