tillerhand 3.42.1 → 3.47.0

package/kit/templates/web-saas/docs/architecture/stack.md

@@ -1,169 +1,169 @@
-# Stack: Web Uygulaması / SaaS
+# Stack: Web App / SaaS
 
-> Bu dosya her oturumda AI'ya yüklenir. Projede farklı bir seçim yaptıysan burayı güncelle
-> ve nedenini `docs/decisions/log.md`'ye yaz.
+> This file is loaded into the AI every session. If you made a different choice in the project, update it here
+> and write the reason in `docs/decisions/log.md`.
 
-## Karar noktaları
+## Decision points
 
-`/start` bu kararları sırayla sorar (`docs/workflow/decision-protocol.md`). Her kararda bu projeye en uygun 2-4 seçeneği sun; **önerilen** etiketi varsayılandır, ama PRD'ye göre başka seçenek daha uygunsa onu öner ve nedenini söyle. Fiyat, ücretsiz katman ve kısıt gibi değişebilen iddiaların yanında `(kaynak: <adres>, YYYY-AA-GG)` notu varsa ve 90 günden yeniyse yeniden araştırılmaz.
+`/start` asks these decisions in order (`docs/workflow/decision-protocol.md`). For each decision, offer the 2-4 options that best fit this project. The **recommended** label is the default, but if another option fits the PRD better, recommend that one and say why. If a claim that can change (price, free tier, limit) carries a `(kaynak: <adres>, YYYY-AA-GG)` note newer than 90 days, do not research it again.
 
-| # | Karar | Seçenekler (ne zaman daha iyi) |
+| # | Decision | Options (when each is better) |
 |---|---|---|
-| 1 | Framework | **Next.js** (önerilen: SEO + panel + API tek projede, AI'nın en iyi bildiği ekosistem) · Astro (içerik/açılış sayfası ağırlıklı, en hızlı sayfa) · SvelteKit (daha az kod, hızlı; ekosistem küçük) · React + Vite SPA (sadece giriş arkasında uygulama, SEO gereksiz, en basit barındırma) |
-| 2 | Dil | **TypeScript** (önerilen: AI hatalarını derleme anında yakalar) · JavaScript (sadece çok küçük prototip) |
-| 3 | Veritabanı + kimlik | **Supabase** (önerilen: Postgres + Auth + Storage + RLS tek yerde; ücretsiz katman 2 aktif proje, proje başı 500 MB veritabanı, 1 hafta hareketsiz kalan proje duraklatılır (kaynak: https://supabase.com/pricing, 2026-10-26)) · Neon + Better Auth (daha fazla kontrol, sağlayıcı bağımlılığı az) · Firebase (gerçek zamanlı, NoSQL, mobil ile ortak backend) · Clerk + Postgres (hazır, şık kimlik arayüzü; ilk 50.000 aylık geri dönen kullanıcı ücretsiz, sonrası kullanıcı başı ücret (kaynak: https://clerk.com/billing, 2026-10-26)) |
-| 4 | Veri erişimi | **Supabase client + RLS** (Supabase seçildiyse) · Drizzle ORM (tip güvenli SQL, sağlayıcıdan bağımsız) · Prisma (olgun, şema odaklı; daha ağır) |
-| 5 | UI bileşenleri | **shadcn/ui + Tailwind** (önerilen: kod projede, tamamen özelleştirilebilir, tasarım skill'leriyle uyumlu) · Tailwind + kendi bileşenleri (tam özgün tasarım) · Mantine (hazır zengin bileşenler, panel ağırlıklı) |
-| 6 | Ödeme | Yok (ilk sürümde ücretsiz) · **iyzico** (TR kartları, taksit, TL) · Stripe (yurt dışı müşteri; TR şirketiyle kısıtlı olabilir: Türkiye desteklenen ülke listesinde görünmüyor (kaynak: https://stripe.com/global, 2026-10-26)) · Paddle / Lemon Squeezy (merchant of record: vergi ve fatura onlarda; yurt dışına abonelik satışı) |
-| 7 | Barındırma | **Vercel** (önerilen Next.js için: sıfır ayar, önizleme ortamları; ücretsiz Hobby planı yalnız kişisel, ticari olmayan kullanım içindir, ödeme alan ya da reklam gösteren ürün Pro ister (kaynak: https://vercel.com/docs/limits/fair-use-guidelines, 2026-10-26)) · Cloudflare (ucuz ve hızlı; ücretsiz Workers günde 100.000 istek ve istek başına 10 ms CPU ile sınırlı (kaynak: https://developers.cloudflare.com/workers/platform/limits/, 2026-10-26)) · Netlify · Kendi sunucun + Coolify (sabit maliyet, bakım sende) |
-| 8 | E-posta | **Resend** (önerilen: geliştirici dostu, React e-posta şablonları; ücretsiz planda ayda 3.000, günde 100 e-posta (kaynak: https://resend.com/pricing, 2026-10-26)) · Postmark (teslim oranı çok yüksek) · Amazon SES (en ucuz, kurulumu zor) |
-| 9 | Analitik | **Plausible** (çerezsiz, KVKK dostu; ücretsiz plan yok, aylık 9 dolardan başlar, 30 gün deneme (kaynak: https://plausible.io/docs/billing, 2026-10-26)) · PostHog (ürün analitiği, huniler, özellik bayrakları) · Umami (kendin barındır, ücretsiz) · Yok |
-| 10 | Hata takibi | **Sentry** (önerilen) · Highlight / Better Stack |
-| 11 | Dil desteği | **Sadece Türkçe** (önerilen MVP için) · Türkçe + İngilizce (next-intl; baştan kurmak sonradan eklemekten ucuzdur) |
-| 12 | Test | **Vitest + Playwright** (önerilen) · Sadece Playwright (az mantık, çok arayüz) |
+| 1 | Framework | **Next.js** (recommended: SEO + dashboard + API in one project, the ecosystem the AI knows best) · Astro (content/landing-page heavy, fastest pages) · SvelteKit (less code, fast; smaller ecosystem) · React + Vite SPA (app only behind login, no SEO need, simplest hosting) |
+| 2 | Language | **TypeScript** (recommended: catches AI mistakes at compile time) · JavaScript (only for a very small prototype) |
+| 3 | Database + identity | **Supabase** (recommended: Postgres + Auth + Storage + RLS in one place; free tier has 2 active projects, 500 MB database per project, a project idle for 1 week is paused (kaynak: https://supabase.com/pricing, 2026-10-26)) · Neon + Better Auth (more control, less provider lock-in) · Firebase (realtime, NoSQL, shared backend with mobile) · Clerk + Postgres (ready-made, polished identity UI; first 50,000 monthly returning users free, then per-user fee (kaynak: https://clerk.com/billing, 2026-10-26)) |
+| 4 | Data access | **Supabase client + RLS** (if Supabase is chosen) · Drizzle ORM (type-safe SQL, provider-independent) · Prisma (mature, schema-driven; heavier) |
+| 5 | UI components | **shadcn/ui + Tailwind** (recommended: code lives in the project, fully customizable, works with the design skills) · Tailwind + own components (fully original design) · Mantine (rich ready-made components, dashboard heavy) |
+| 6 | Payment | None (free in the first release) · **iyzico** (Turkish cards, installments, TRY) · Stripe (customers abroad; may be restricted for a Turkish company: Turkey does not appear in the supported-country list (kaynak: https://stripe.com/global, 2026-10-26)) · Paddle / Lemon Squeezy (merchant of record: they handle tax and invoicing; subscriptions sold abroad) |
+| 7 | Hosting | **Vercel** (recommended for Next.js: zero config, preview environments; the free Hobby plan is for personal, non-commercial use only, a product that takes payments or shows ads needs Pro (kaynak: https://vercel.com/docs/limits/fair-use-guidelines, 2026-10-26)) · Cloudflare (cheap and fast; free Workers are limited to 100,000 requests per day and 10 ms CPU per request (kaynak: https://developers.cloudflare.com/workers/platform/limits/, 2026-10-26)) · Netlify · Your own server + Coolify (fixed cost, maintenance is yours) |
+| 8 | Email | **Resend** (recommended: developer friendly, React email templates; free plan gives 3,000 emails per month, 100 per day (kaynak: https://resend.com/pricing, 2026-10-26)) · Postmark (very high deliverability) · Amazon SES (cheapest, hard to set up) |
+| 9 | Analytics | **Plausible** (cookieless, KVKK friendly; no free plan, starts at 9 dollars per month, 30-day trial (kaynak: https://plausible.io/docs/billing, 2026-10-26)) · PostHog (product analytics, funnels, feature flags) · Umami (self-host, free) · None |
+| 10 | Error tracking | **Sentry** (recommended) · Highlight / Better Stack |
+| 11 | Language support | **Turkish only** (recommended for the MVP) · Turkish + English (next-intl; setting it up from the start is cheaper than adding it later) |
+| 12 | Test | **Vitest + Playwright** (recommended) · Playwright only (little logic, mostly UI) |
 
 ## Seçilen teknolojiler
 
-> `/start` Adım 4'te karar noktalarına göre doldurulur. Aşağıdaki tablo **önerilen** yığındır ve onaylanana kadar öneri sayılır.
-> Seçim farklıysa bu dosyanın komut, klasör, kural, doğrulama ve kontrol bölümleri seçime göre yeniden yazılır.
+> `/start` fills this in at Step 4 from the decision points. The table below is the **recommended** stack and counts as a proposal until approved.
+> If the choice differs, rewrite the commands, folder, rules, verification and checks sections of this file to match the choice.
 
-| Katman | Seçim | Not |
+| Layer | Choice | Note |
 |---|---|---|
 | Framework | Next.js (App Router) + TypeScript (strict) | |
-| UI | Tailwind CSS + shadcn/ui | Yeni bileşen yazmadan önce shadcn'de var mı bak |
-| DB + Auth + Depolama | Supabase (Postgres) | Alternatif: Neon + Auth.js |
-| ORM / sorgu | Supabase client veya Drizzle | Projede hangisi varsa sadece o |
-| Doğrulama | Zod | Hem form hem sunucu |
-| Ödeme | Stripe / iyzico / Paddle | TR şirketiyle Stripe sınırlı olabilir, kontrol et |
-| E-posta | Resend | Alan adı doğrulaması şart |
+| UI | Tailwind CSS + shadcn/ui | Before writing a new component, check whether shadcn has it |
+| DB + Auth + Storage | Supabase (Postgres) | Alternative: Neon + Auth.js |
+| ORM / query | Supabase client or Drizzle | Use only the one the project already has |
+| Validation | Zod | For both forms and the server |
+| Payment | Stripe / iyzico / Paddle | Stripe may be restricted for a Turkish company, check |
+| Email | Resend | Domain verification is required |
 | Hosting | Vercel | |
-| Hata takibi | Sentry | |
-| Analitik | Plausible / PostHog | Çerez onayına dikkat |
-| Test | Vitest (birim), Playwright (e2e) | |
+| Error tracking | Sentry | |
+| Analytics | Plausible / PostHog | Watch cookie consent |
+| Test | Vitest (unit), Playwright (e2e) | |
 
-## Komutlar
+## Komutlar (commands)
 
 ```bash
-npm run dev            # geliştirme
-npm run build          # prod derleme (deploy öncesi mutlaka)
+npm run dev            # development
+npm run build          # production build (always before deploy)
 npm run lint
-npx tsc --noEmit       # tip kontrolü
+npx tsc --noEmit       # type check
 npm run test           # vitest
 npx playwright test    # e2e
-npx supabase migration new [ad]   # yeni migration
+npx supabase migration new [ad]   # new migration
 ```
 
-## Klasör yapısı
+## Folder structure
 
-Özellik bazlı yapı ve kurallar: `docs/architecture/structure.md`. Harita: `.claude/structure.json` (dışına yazım sorulur, CI denetler).
+Feature-based structure and rules: `docs/architecture/structure.md`. Map: `.claude/structure.json` (writing outside it is asked about, CI checks it).
 ```
 src/
-├── app/                        # SADECE rotalar: page, layout, loading, error, route handler. İş mantığı yok.
-│   ├── (marketing)/            # açılış, fiyat, blog
-│   ├── (auth)/                 # giriş, kayıt, şifre sıfırlama
-│   ├── (app)/                  # giriş gerektiren uygulama
-│   └── api/                    # webhook ve dış API uçları
+├── app/                        # ONLY routes: page, layout, loading, error, route handler. No business logic.
+│   ├── (marketing)/            # landing, pricing, blog
+│   ├── (auth)/                 # sign in, sign up, password reset
+│   ├── (app)/                  # the app that needs login
+│   └── api/                    # webhook and external API endpoints
 ├── features/
-│   └── <özellik>/              # örn. invoice/
-│       ├── components/         # sadece bu özelliğin bileşenleri
-│       ├── hooks/              # istemci hook'ları
-│       ├── server/             # server actions, sorgular, servisler (sunucuda çalışır)
-│       ├── lib/                # özelliğe özel yardımcılar
-│       ├── __tests__/          # birim ve entegrasyon testleri
-│       ├── schemas.ts          # Zod şemaları
+│   └── <feature>/              # e.g. invoice/
+│       ├── components/         # components of this feature only
+│       ├── hooks/              # client hooks
+│       ├── server/             # server actions, queries, services (run on the server)
+│       ├── lib/                # feature-specific helpers
+│       ├── __tests__/          # unit and integration tests
+│       ├── schemas.ts          # Zod schemas
 │       ├── types.ts
-│       └── index.ts            # özelliğin dışa açtığı tek kapı
+│       └── index.ts            # the only gate the feature exposes
 ├── components/
-│   └── ui/                     # shadcn/ui ve paylaşılan sunum bileşenleri
-├── hooks/                      # birden fazla özelliğin kullandığı hook'lar
-├── lib/                        # altyapı istemcileri: supabase/, stripe/, email/, sentry
-├── config/                     # ortam değişkeni doğrulama (env.ts), sabitler
-├── styles/                     # global stiller, tasarım belirteçleri (DESIGN.md'den)
-├── types/                      # global tipler
+│   └── ui/                     # shadcn/ui and shared presentational components
+├── hooks/                      # hooks used by more than one feature
+├── lib/                        # infrastructure clients: supabase/, stripe/, email/, sentry
+├── config/                     # environment variable validation (env.ts), constants
+├── styles/                     # global styles, design tokens (from DESIGN.md)
+├── types/                      # global types
 └── middleware.ts
-public/                         # statik dosyalar
+public/                         # static files
 tests/
-├── e2e/                        # Playwright kabul testleri (Ö-01.1 ...)
-└── live/                       # canlı izleme testleri (veri silmeyen)
-supabase/migrations/            # veritabanı değişiklikleri SADECE burada
+├── e2e/                        # Playwright acceptance tests (Ö-01.1 ...)
+└── live/                       # live monitoring tests (that delete no data)
+supabase/migrations/            # database changes ONLY here
 ```
 
-## Kodlama kuralları
+## Coding rules
 
-- Varsayılan **Server Component**. `"use client"` sadece etkileşim gerekiyorsa ve en alttaki bileşende.
-- Veri yazma: Server Action veya route handler. Her birinde: Zod doğrulama → oturum kontrolü → yetki kontrolü → işlem.
-- `NEXT_PUBLIC_` ön ekli değişkenler tarayıcıya gider. Sır asla `NEXT_PUBLIC_` olmaz.
-- Supabase gizli anahtarı (`SUPABASE_SECRET_KEY`, `sb_secret_…`; eski adı `service_role`) sadece sunucuda ve sadece gerçekten gerekiyorsa (RLS'i atlar).
-- DB şema değişikliği sadece migration dosyasıyla (`npx supabase migration new [ad]`). Panelden veya MCP'den elle DDL yok; `supabase-dev` MCP'si dev'de veri denemek içindir.
-- Her yeni tabloda RLS açık, politikası yazılı ve tablo `tests/security/rls.mjs` → `TABLES` listesinde (CI'daki `rls` işi kayıtsız tabloda kırmızı olur).
-- Her sayfada `loading.tsx` / boş durum / `error.tsx` düşün.
-- Görseller `next/image`, linkler `next/link`.
-- Metinler Türkçe; tarih/para `Intl` ile `tr-TR`.
-- UI işinden önce `DESIGN.md` ve `docs/design/design-guide.md`'yi oku; belirteçlerin ve kuralların dışına çıkma. Yeni tasarım kararı gerekiyorsa `/design`.
+- Default to **Server Component**. `"use client"` only when interaction is needed, and in the lowest component.
+- Writing data: Server Action or route handler. In each: Zod validation → session check → permission check → operation.
+- Variables with the `NEXT_PUBLIC_` prefix go to the browser. A secret is never `NEXT_PUBLIC_`.
+- The Supabase secret key (`SUPABASE_SECRET_KEY`, `sb_secret_…`; old name `service_role`) only on the server and only when really needed (it bypasses RLS).
+- DB schema changes only through a migration file (`npx supabase migration new [ad]`). No manual DDL from the dashboard or MCP; the `supabase-dev` MCP is for trying data in dev.
+- Every new table has RLS on, a written policy, and an entry in the `tests/security/rls.mjs` → `TABLES` list (the `rls` job in CI turns red on an unregistered table).
+- On every page, think about `loading.tsx` / empty state / `error.tsx`.
+- Images with `next/image`, links with `next/link`.
+- Texts are in Turkish; format date/money with `Intl` and `tr-TR`.
+- Before UI work, read `DESIGN.md` and `docs/design/design-guide.md`; do not go outside the tokens and rules. If a new design decision is needed, use `/design`.
 
-## Doğrulama (görev bitmeden kanıt)
+## Verification (evidence before a task is done)
 
-- Arayüz: `node .claude/hooks/preview.mjs <görev kodu>` masaüstü (1440) ve mobil (390) ekran görüntüsünü alır (`AGENTS.md` → `geliştirme:` ve `önizleme:` satırları). Senaryoları denemek için `npm run dev` açıkken Playwright CLI (`npx -y @playwright/cli@0.1.22 open http://localhost:3000`, sonra `snapshot`, `console`, `screenshot`) veya Claude'un tarayıcısı ile sayfayı aç, ana senaryoyu ve bir hata senaryosunu dene.
-- Kabul kriterlerini tarayıcıda kanıtlamak: `/qa` (kriter başına Playwright testi, rapor `docs/quality/qa/`).
-- Yetki: ikinci bir test kullanıcısıyla birinci kullanıcının kaydına erişmeyi dene; erişememeli.
-- Konsolda hata/uyarı yok.
+- UI: `node .claude/hooks/preview.mjs <task id>` takes a desktop (1440) and mobile (390) screenshot (the `geliştirme:` and `önizleme:` lines in `AGENTS.md`). To try scenarios, with `npm run dev` running, open the page with the Playwright CLI (`npx -y @playwright/cli@0.1.22 open http://localhost:3000`, then `snapshot`, `console`, `screenshot`) or with Claude's browser, and try the main scenario and one error scenario.
+- Proving acceptance criteria in the browser: `/qa` (one Playwright test per criterion, report in `docs/quality/qa/`).
+- Authorization: with a second test user, try to reach the first user's record; it must fail.
+- No errors/warnings in the console.
 
-## Otomatik kontroller
+## Automatic checks
 
-| Katman | Ne yapar | Kurulum |
+| Layer | What it does | Setup |
 |---|---|---|
-| Claude hook'ları | Sır yazımını engeller; düzenlenen dosyayı Prettier ile biçimlendirir | Hazır (`.claude/settings.json`). Prettier projede kurulu olmalı |
-| Pre-commit | lint-staged (ESLint + Prettier) + sır taraması | `npm i -D husky lint-staged prettier` → `npm pkg set scripts.prepare="husky"` → `npx husky` |
-| CI (+ Semgrep, kopya kod, karmaşıklık bütçesi) | Lint, tip, test, build, açık taraması, gitleaks, değişen dosyalarda karmaşıklık bütçesi (fonksiyon karmaşıklığı 15, fonksiyon 80, dosya 400 satır; `node .claude/hooks/budget.mjs --check`) | `.github/workflows/ci.yml` hazır. GitHub > Settings > Variables'a `NEXT_PUBLIC_*` değerlerini ekle |
-| Dependabot | Haftalık küçük güncellemeler tek PR'da | `.github/dependabot.yml` hazır |
-| MCP | Supabase (salt-okunur), Sentry, Context7 · gerektiğinde: Playwright, Chrome DevTools, Supabase dev (`docs/workflow/mcp-catalog.md`) | `.mcp.json`: `DEV_REF`'i doldur (salt-okunur, **geliştirme** projesi; prod ref'i AI ortamına yazılmaz). Yazma yetkili Supabase MCP sadece **geliştirme** projesine (`supabase-dev`) |
+| Claude hooks | Block writing secrets; format the edited file with Prettier | Ready (`.claude/settings.json`). Prettier must be installed in the project |
+| Pre-commit | lint-staged (ESLint + Prettier) + secret scan | `npm i -D husky lint-staged prettier` → `npm pkg set scripts.prepare="husky"` → `npx husky` |
+| CI (+ Semgrep, duplicate code, complexity budget) | Lint, types, test, build, vulnerability scan, gitleaks, complexity budget on changed files (function complexity 15, function 80, file 400 lines; `node .claude/hooks/budget.mjs --check`) | `.github/workflows/ci.yml` is ready. Add the `NEXT_PUBLIC_*` values to GitHub > Settings > Variables |
+| Dependabot | Weekly small updates in a single PR | `.github/dependabot.yml` is ready |
+| MCP | Supabase (read-only), Sentry, Context7 · when needed: Playwright, Chrome DevTools, Supabase dev (`docs/workflow/mcp-catalog.md`) | `.mcp.json`: fill in `DEV_REF` (read-only, the **development** project; the prod ref is not written into the AI environment). The write-enabled Supabase MCP only for the **development** project (`supabase-dev`) |
 
-## Kabul testleri ve özellik bayrakları
+## Acceptance tests and feature flags
 
-**Kabul testleri** (`docs/quality/test-plan.md` §1a): Test adı kriter kimliğini taşır (`test('Ö-01.1 ...')`). Pano JUnit raporunu okur:
+**Acceptance tests** (`docs/quality/test-plan.md` §1a): The test name carries the criterion id (`test('Ö-01.1 ...')`). The dashboard reads the JUnit report:
 
 ```bash
 PLAYWRIGHT_JUNIT_OUTPUT_NAME=test-results/junit.xml npx playwright test --reporter=list,junit
 npx vitest run --reporter=default --reporter=junit --outputFile.junit=test-results/junit-unit.xml
 ```
 
-**Özellik bayrakları** (`docs/operations/feature-flags.md`): Acil kapatma deploy gerektirmemeli. Bu yüzden ortam değişkeni değil, çalışma anında okunan bir kaynak kullanılır:
-- PostHog seçildiyse PostHog feature flags; değilse
-- Supabase'de `feature_flags` tablosu (`ad`, `acik`, `yuzde`) + sunucuda 60 sn önbellek. Okuma tek bir yardımcıdan yapılır: `lib/bayrak.ts` → `bayrakAcik('ad', kullanici)`.
-- Bayrak kontrolü sunucuda yapılır; istemci sadece sonucu görür.
+**Feature flags** (`docs/operations/feature-flags.md`): Emergency shutdown must not need a deploy. So use a source read at runtime, not an environment variable:
+- PostHog feature flags if PostHog is chosen; otherwise
+- A `feature_flags` table in Supabase (`ad`, `acik`, `yuzde`) + a 60 s cache on the server. Reading goes through one helper: `lib/bayrak.ts` → `bayrakAcik('ad', kullanici)`.
+- The flag check runs on the server; the client only sees the result.
 
-## Sık yapılan AI hataları (bunlara dikkat)
+## Common AI mistakes (watch for these)
 
-- Koda, teste veya ayara bu makineye özel mutlak yol yazmak (`C:\Users\<ad>\…`, `/home/<ad>/…`, proje klasörünün tam yolu): başka makinede çalışmaz. Yolu `import.meta.url` / `__dirname`, `path.join(process.cwd(), …)` veya `os.tmpdir()` ile türet. Deterministik kapı bunu yakalar.
-- Client component içinde Supabase admin istemcisi veya sır kullanmak.
-- Sayfayı middleware ile koruyup server action'ı korumasız bırakmak.
-- RLS'i "çalışmıyor" diye kapatmak.
-- Eski Pages Router kalıplarını (`getServerSideProps`) App Router'a karıştırmak.
-- Webhook'ta imza doğrulamamak; webhook'u iki kez gelince iki kez işlemek (idempotency).
+- Writing an absolute path specific to this machine into code, a test or a setting (`C:\Users\<ad>\…`, `/home/<ad>/…`, the full path of the project folder): it does not work on another machine. Derive the path with `import.meta.url` / `__dirname`, `path.join(process.cwd(), …)` or `os.tmpdir()`. The deterministic gate catches this.
+- Using the Supabase admin client or a secret inside a client component.
+- Protecting the page with middleware but leaving the server action unprotected.
+- Turning RLS off because it "does not work".
+- Mixing old Pages Router patterns (`getServerSideProps`) into the App Router.
+- Not verifying the signature on a webhook; processing a webhook twice when it arrives twice (idempotency).
 
-## Güvenlik (ek)
+## Security (extra)
 
-- [ ] Tüm tablolarda RLS açık ve her tablo saldırgan testinde: `tests/security/rls.mjs` (CI `rls` işi yeşil). Yerelde: `npx -y supabase@2.120.0 start`, sonra dosyanın başındaki komutlar.
-- [ ] Başka kullanıcı ve anonim, kullanıcının satırını okuyamıyor, değiştiremiyor, silemiyor (aynı test).
-- [ ] Güvenlik başlıkları (CSP, X-Frame-Options vb.) `next.config` veya middleware'de.
-- [ ] Auth uçlarında rate limit (Supabase ayarları + gerekiyorsa Upstash).
+- [ ] RLS is on in all tables and every table is in the adversarial test: `tests/security/rls.mjs` (CI `rls` job green). Locally: `npx -y supabase@2.120.0 start`, then the commands at the top of the file.
+- [ ] Another user and an anonymous user cannot read, change or delete the user's row (same test).
+- [ ] Security headers (CSP, X-Frame-Options etc.) in `next.config` or middleware.
+- [ ] Rate limit on auth endpoints (Supabase settings + Upstash if needed).
 
-## Canlıya alma (ek)
+## Go live (extra)
 
-- [ ] Vercel prod ortam değişkenleri girildi (Preview ve Production ayrı)
-- [ ] Supabase prod projesi ayrı; Auth → URL Configuration'da prod alan adı ve redirect URL'leri
-- [ ] Supabase e-posta şablonları Türkçe ve özel SMTP (varsayılan SMTP'nin limiti çok düşük)
-- [ ] Ödeme: canlı anahtarlar, canlı webhook uç noktası ve imza sırrı
-- [ ] SEO: `metadata` (title, description), Open Graph görseli, `sitemap.ts`, `robots.ts`, favicon
-- [ ] Lighthouse (mobil): Performans ≥ 90, Erişilebilirlik ≥ 90, SEO ≥ 90
+- [ ] Vercel prod environment variables entered (Preview and Production separate)
+- [ ] Supabase prod project is separate; prod domain and redirect URLs in Auth → URL Configuration
+- [ ] Supabase email templates in Turkish and a custom SMTP (the default SMTP limit is very low)
+- [ ] Payment: live keys, live webhook endpoint and signing secret
+- [ ] SEO: `metadata` (title, description), Open Graph image, `sitemap.ts`, `robots.ts`, favicon
+- [ ] Lighthouse (mobile): Performance ≥ 90, Accessibility ≥ 90, SEO ≥ 90
 - [ ] Core Web Vitals: LCP < 2.5s, CLS < 0.1, INP < 200ms
-- [ ] `not-found.tsx` ve `error.tsx` özelleştirildi
-- [ ] Alan adı + `www` yönlendirme + SSL (Vercel otomatik)
-- [ ] Sentry kaynak haritaları (source map) yükleniyor
+- [ ] `not-found.tsx` and `error.tsx` customized
+- [ ] Domain + `www` redirect + SSL (Vercel automatic)
+- [ ] Sentry source maps are uploaded
 
-## Bakım (ek)
+## Maintenance (extra)
 
-- Haftalık: Vercel kullanım (bandwidth, function süresi), Supabase kullanım (DB boyutu, MAU).
-- Aylık: `npm outdated`, `npm audit`, Lighthouse tekrar.
-- Çeyreklik: Next.js / Supabase majör sürüm notları; Supabase yedekleri (ücretsiz katmanda PITR yok, kendi yedeğini al: `supabase db dump`).
-- Ücretsiz Supabase projesi hareketsiz kalınca duraklatılabilir; canlı projede ücretli plana geç veya bunu izle.
+- Weekly: Vercel usage (bandwidth, function duration), Supabase usage (DB size, MAU).
+- Monthly: `npm outdated`, `npm audit`, rerun Lighthouse.
+- Quarterly: Next.js / Supabase major version notes; Supabase backups (no PITR on the free tier, take your own backup: `supabase db dump`).
+- A free Supabase project can be paused when idle; on a live project move to a paid plan or watch this.

package/kit/templates/web-saas/docs/architecture/structure.md

@@ -1,71 +1,71 @@
-# Proje yapısı: Web / SaaS (Next.js App Router)
+# Project structure: Web / SaaS (Next.js App Router)
 
-> Bu dosya `.claude/structure.json` haritasının insan için açıklamasıdır; ikisi birlikte güncellenir.
-> Yapıya uyum zorunludur: yazım anında hook, her PR'da CI, kurul Mimarı ve `/findings-tech` denetler.
+> This file is the human explanation of the `.claude/structure.json` map; the two are updated together.
+> Following the structure is mandatory: the hook checks at write time, CI on every PR, the board Architect and `/findings-tech` review it.
 
-## Kod
+## Code
 
 ```
 src/
-├── app/                        # SADECE rotalar: page, layout, loading, error, route handler. İş mantığı yok.
-│   ├── (marketing)/            # açılış, fiyat, blog
-│   ├── (auth)/                 # giriş, kayıt, şifre sıfırlama
-│   ├── (app)/                  # giriş gerektiren uygulama
-│   └── api/                    # webhook ve dış API uçları
+├── app/                        # ONLY routes: page, layout, loading, error, route handler. No business logic.
+│   ├── (marketing)/            # landing, pricing, blog
+│   ├── (auth)/                 # sign in, sign up, password reset
+│   ├── (app)/                  # the app that needs login
+│   └── api/                    # webhook and external API endpoints
 ├── features/
-│   └── <özellik>/              # örn. invoice/
-│       ├── components/         # sadece bu özelliğin bileşenleri
-│       ├── hooks/              # istemci hook'ları
-│       ├── server/             # server actions, sorgular, servisler (sunucuda çalışır)
-│       ├── lib/                # özelliğe özel yardımcılar
-│       ├── __tests__/          # birim ve entegrasyon testleri
-│       ├── schemas.ts          # Zod şemaları
+│   └── <feature>/              # e.g. invoice/
+│       ├── components/         # components of this feature only
+│       ├── hooks/              # client hooks
+│       ├── server/             # server actions, queries, services (run on the server)
+│       ├── lib/                # feature-specific helpers
+│       ├── __tests__/          # unit and integration tests
+│       ├── schemas.ts          # Zod schemas
 │       ├── types.ts
-│       └── index.ts            # özelliğin dışa açtığı tek kapı
+│       └── index.ts            # the only gate the feature exposes
 ├── components/
-│   └── ui/                     # shadcn/ui ve paylaşılan sunum bileşenleri
-├── hooks/                      # birden fazla özelliğin kullandığı hook'lar
-├── lib/                        # altyapı istemcileri: supabase/, stripe/, email/, sentry
-├── config/                     # ortam değişkeni doğrulama (env.ts), sabitler
-├── styles/                     # global stiller, tasarım belirteçleri (DESIGN.md'den)
-├── types/                      # global tipler
+│   └── ui/                     # shadcn/ui and shared presentational components
+├── hooks/                      # hooks used by more than one feature
+├── lib/                        # infrastructure clients: supabase/, stripe/, email/, sentry
+├── config/                     # environment variable validation (env.ts), constants
+├── styles/                     # global styles, design tokens (from DESIGN.md)
+├── types/                      # global types
 └── middleware.ts
-public/                         # statik dosyalar
+public/                         # static files
 tests/
-├── e2e/                        # Playwright kabul testleri (Ö-01.1 ...)
-└── live/                       # canlı izleme testleri (veri silmeyen)
-supabase/migrations/            # veritabanı değişiklikleri SADECE burada
+├── e2e/                        # Playwright acceptance tests (Ö-01.1 ...)
+└── live/                       # live monitoring tests (that delete no data)
+supabase/migrations/            # database changes ONLY here
 ```
 
-## Her projede ortak
+## Common to every project
 
 ```
 .
-├── .claude/               # Claude Code: komutlar, ajanlar, hook'lar, kurul, bulgular, structure.json
-├── .github/               # CI, Dependabot, bulut ajanları
+├── .claude/               # Claude Code: commands, agents, hooks, board, findings, structure.json
+├── .github/               # CI, Dependabot, cloud agents
 ├── docs/
 │   ├── product/           # prd, roadmap, glossary, launch, feedback, unit-economics
-│   ├── architecture/      # overview, stack, structure (bu dosya)
-│   ├── design/            # design-guide (arayüz varsa)
-│   ├── decisions/         # log.md (karar günlüğü) + adr-NNNN-*.md (ayrıntılı kararlar)
+│   ├── architecture/      # overview, stack, structure (this file)
+│   ├── design/            # design-guide (if there is a UI)
+│   ├── decisions/         # log.md (decision log) + adr-NNNN-*.md (detailed decisions)
 │   ├── quality/           # test-plan, metrics, retros
 │   ├── security/          # checklist
 │   ├── legal/             # privacy-kvkk
 │   ├── operations/        # release-checklist, maintenance, accounts, feature-flags
 │   ├── workflow/          # progress, decision-protocol, skills, board, usage-limits, cost-log
-│   ├── findings/          # /findings-* raporları (tür/tarih.md, latest.md)
-│   └── archive/           # artık geçerli olmayan ama saklanan dokümanlar
-├── sandbox/               # deneme, keşif kodu, geçici script (git'e girmez)
+│   ├── findings/          # /findings-* reports (type/date.md, latest.md)
+│   └── archive/           # documents that are no longer valid but are kept
+├── sandbox/               # trials, exploration code, temporary scripts (not committed to git)
 ├── AGENTS.md  CLAUDE.md  README.md  CHANGELOG.md
 └── .env.example
 ```
 
-## Kurallar
+## Rules
 
-1. **Yeni dosya, haritadaki yerine.** `.claude/structure.json` haritası dışına yazım sorulur; dağınıklık kalıpları (`*.bak`, `*-old.*`, `* copy*`, `temp/`, `deneme*`) engellenir. CI her PR'da tüm depoyu denetler.
-2. **Özellik bazlı.** Bir özelliğe ait her şey (bileşen, mantık, test) `features/<özellik>/` altında durur. Bir kod iki özellik tarafından kullanılmaya başlarsa paylaşılan katmana (`components/`, `lib/`, `shared/`) taşınır.
-3. **Özellikler birbirinin içine girmez.** `features/a` başka bir özelliğin iç dosyalarını içe aktarmaz; sadece o özelliğin `index` dosyasından dışa açtıklarını kullanır.
-4. **Adlandırma:** Klasörler ve dosyalar `kebab-case`. React bileşen dosyaları `PascalCase.tsx` olabilir; Python modülleri `snake_case.py`. Özellik klasör adı tekil ve İngilizce (`invoice`, `customer`).
-5. **Geçici ve alakasız işler** `sandbox/` altına. İşe yarayan bir şey çıkarsa doğru yere taşınır; `sandbox/` düzenli temizlenir.
-6. **Eski dokümanlar** silinmez, `docs/archive/` altına taşınır ve başına neden arşivlendiği yazılır.
-7. **Haritayı değiştirmek** (yeni üst klasör, yeni katman) bir `teknik` karardır: kullanıcıya sorulur, `docs/decisions/` altına kaydedilir, sonra `.claude/structure.json` ve bu dosya güncellenir.
+1. **A new file goes to its place in the map.** Writing outside the `.claude/structure.json` map is asked about; clutter patterns (`*.bak`, `*-old.*`, `* copy*`, `temp/`, `deneme*`) are blocked. CI checks the whole repo on every PR.
+2. **By feature.** Everything that belongs to a feature (component, logic, test) stays under `features/<feature>/`. When a piece of code starts to be used by two features, it moves to the shared layer (`components/`, `lib/`, `shared/`).
+3. **Features do not reach into each other.** `features/a` does not import the internal files of another feature; it uses only what that feature exposes from its `index` file.
+4. **Naming:** Folders and files use `kebab-case`. React component files may use `PascalCase.tsx`; Python modules use `snake_case.py`. A feature folder name is singular and English (`invoice`, `customer`).
+5. **Temporary and unrelated work** goes under `sandbox/`. If something useful comes out, it moves to the right place; `sandbox/` is cleaned regularly.
+6. **Old documents** are not deleted; they move under `docs/archive/` with a line at the top saying why they were archived.
+7. **Changing the map** (a new top-level folder, a new layer) is a `teknik` decision: ask the user, record it under `docs/decisions/`, then update `.claude/structure.json` and this file.

package/kit/templates/web-saas/docs/design/design-guide.md

@@ -1,55 +1,55 @@
-# Tasarım
+# Design
 
-> Arayüzün tek kaynağı üç dosyadır:
-> - `PRODUCT.md`: ürün bağlamı (kim, ne için). Impeccable `init` ile, PRD'den beslenerek yazılır.
-> - `DESIGN.md`: görsel dünya ve tasarım belirteçleri (renk, yazı, boşluk, köşe, gölge, hareket). Impeccable yazar; bileşenler sadece bu belirteçleri kullanır.
-> - Bu dosya: seçilen yön, tasarım karar günlüğü ve her ekranda geçerli kalıcı kurallar.
+> The interface has three sources of truth:
+> - `PRODUCT.md`: product context (who, for what). Written with Impeccable `init`, fed from the PRD.
+> - `DESIGN.md`: visual world and design tokens (color, type, spacing, corners, shadow, motion). Impeccable writes it; components use only these tokens.
+> - This file: the chosen direction, the design decision log and the lasting rules that apply on every screen.
 >
-> Kararlar `/design` ile **görsel önizlemelerle** alınır (`docs/workflow/decision-protocol.md` §5). Yeni bir renk, boyut veya bileşen
-> gerekiyorsa önce karar olarak sorulur, sonra DESIGN.md'ye eklenir. Kodda ham renk veya rastgele boyut yazılmaz.
+> Decisions are made with `/design` using **visual previews** (`docs/workflow/decision-protocol.md` §5). If a new color, size or component
+> is needed, it is asked as a decision first, then added to DESIGN.md. No raw colors or arbitrary sizes in code.
 
-## 1. Seçilen yön
+## 1. Seçilen yön (Chosen direction)
 
-| Alan | Seçim | Skill | Önizleme | Tarih |
+| Area | Choice | Skill | Preview | Date |
 |---|---|---|---|---|
-| Stil yönü | [örn. Premium / Apple tarzı] | [örn. taste-skill:high-end-visual-design] | `.previews/01-stil/b.html` | |
-| Renk paleti | | ui-ux-pro-max | | |
-| Yazı tipi çifti | | ui-ux-pro-max | | |
-| Köşe / gölge / hareket | | | | |
-| Koyu tema | | | | |
-| Hitap (sen/siz) | | | | |
+| Style direction | [e.g. Premium / Apple style] | [e.g. taste-skill:high-end-visual-design] | `.previews/01-stil/b.html` | |
+| Color palette | | ui-ux-pro-max | | |
+| Font pair | | ui-ux-pro-max | | |
+| Corners / shadow / motion | | | | |
+| Dark theme | | | | |
+| Form of address (informal/formal) | | | | |
 
-## 2. Tasarım karar günlüğü
+## 2. Design decision log
 
-| # | Tarih | Ekran/kapsam | Soru | Seçilen | Önizleme |
+| # | Date | Screen/scope | Question | Chosen | Preview |
 |---|---|---|---|---|---|
 
-## 3. Bileşenler
+## 3. Components
 
-- Önce `components/ui/` (shadcn) içinde var mı bak; varsa onu kullan, kopyalayıp değiştirme.
-- Buton varyantları: `default` (sayfada en fazla 1 ana eylem), `secondary`, `outline`, `ghost`, `destructive`.
-- Form: etiket her zaman görünür (sadece placeholder değil), hata mesajı alanın altında, gönderirken buton devre dışı + yükleniyor.
-- Tablo/liste: boş durum bileşeni + yükleniyor iskeleti (skeleton) zorunlu.
-- İkonlar: [lucide-react], tek set.
+- First check whether it exists in `components/ui/` (shadcn); if it does, use it, do not copy and change it.
+- Button variants: `default` (at most 1 main action per page), `secondary`, `outline`, `ghost`, `destructive`.
+- Form: the label is always visible (not only a placeholder), the error message sits under the field, the button is disabled + loading while submitting.
+- Table/list: an empty-state component + a loading skeleton are required.
+- Icons: [lucide-react], a single set.
 
-## 4. Durumlar (her ekranda)
+## 4. States (on every screen)
 
-| Durum | Nasıl görünür |
+| State | How it looks |
 |---|---|
-| Yükleniyor | İskelet; 300 ms'den kısa yüklemelerde hiçbir şey |
-| Boş | Ne olacağını anlatan bir cümle + ilk adım butonu |
-| Hata | Ne oldu + ne yapabilir (tekrar dene / destek); teknik detay yok |
-| Başarılı işlem | Kısa bildirim (toast), 3-4 sn |
+| Loading | Skeleton; nothing for loads shorter than 300 ms |
+| Empty | One sentence saying what will be here + a first-step button |
+| Error | What happened + what the user can do (retry / support); no technical detail |
+| Successful action | Short notification (toast), 3-4 s |
 
-## 5. Erişilebilirlik
+## 5. Accessibility
 
-- Metin kontrastı en az 4.5:1 (büyük metin 3:1); iki temada da.
-- Klavye ile her şeye ulaşılır, odak halkası görünür.
-- Görsellerde `alt`, ikon butonlarda `aria-label`.
-- Mobil genişlikte (375 px) yatay kaydırma yok, dokunma alanı en az 44 px.
+- Text contrast at least 4.5:1 (large text 3:1); in both themes.
+- Everything is reachable by keyboard, the focus ring is visible.
+- `alt` on images, `aria-label` on icon buttons.
+- No horizontal scroll at mobile width (375 px), touch target at least 44 px.
 
-## 6. Metin dili
+## 6. Copy language
 
-- Hitap: [sen/siz] (`docs/product/glossary.md` ile aynı).
-- Butonlar fiil: "Kaydet", "Fatura oluştur"; "Tamam", "Gönder" gibi belirsiz değil.
-- Hata mesajı suçlamaz ve çözümü söyler: "E-posta adresi geçerli değil. Örnek: ad@alan.com".
+- Form of address: [informal/formal] (same as `docs/product/glossary.md`).
+- Buttons are verbs: "Save", "Create invoice"; not vague ones like "OK", "Submit".
+- An error message does not blame the user and says the fix: "The email address is not valid. Example: name@domain.com".

package/kit/templates/web-saas/tests/live/smoke.spec.ts

@@ -6,14 +6,14 @@ import { test, expect } from '@playwright/test';
 const BASE = process.env.BASE_URL ?? 'http://localhost:3000';
 const MAX_MS = Number(process.env.LIVE_MAX_MS ?? 3000);
 
-test('canlı: ana sayfa açılıyor, yanıt süresi sınırda, konsolda hata yok', async ({ page }) => {
+test('live: home page opens, response time within the limit, no console errors',async ({ page }) => {
   const errors: string[] = [];
   page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
   page.on('pageerror', (e) => errors.push(e.message));
   const start = Date.now();
   const response = await page.goto(BASE, { waitUntil: 'domcontentloaded' });
   const ms = Date.now() - start;
-  expect(response?.ok(), `durum kodu ${response?.status()}`).toBe(true);
-  expect(ms, `ana sayfa ${ms} ms (sınır ${MAX_MS} ms)`).toBeLessThan(MAX_MS);
-  expect(errors, `konsol hatası: ${errors[0] ?? ''}`).toEqual([]);
+  expect(response?.ok(), `status code ${response?.status()}`).toBe(true);
+  expect(ms, `home page ${ms} ms (limit ${MAX_MS} ms)`).toBeLessThan(MAX_MS);
+  expect(errors, `console error: ${errors[0] ?? ''}`).toEqual([]);
 });