tillerhand 3.42.1 → 3.47.0

package/kit/templates/backend/docs/architecture/stack.md

@@ -1,156 +1,156 @@
-# Stack: Backend / API / Otomasyon
+# Stack: Backend / API / Automation
 
-> 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 the project makes a different choice, update this file
+> and write the reason to `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 fit this project best. The **recommended** label is the default, but if another option fits the PRD better, recommend that one and say why. A claim that can change (price, free tier, limit) with a `(kaynak: <adres>, YYYY-AA-GG)` note newer than 90 days is not researched again.
 
-| # | Karar | Seçenekler (ne zaman daha iyi) |
+| # | Decision | Options (when each is better) |
 |---|---|---|
-| 1 | Dil ve framework | **Python + FastAPI** (önerilen: AI/veri işleri, hızlı geliştirme, otomatik OpenAPI dokümanı) · Node.js + TypeScript + Hono/Fastify (frontend ile aynı dil, tip paylaşımı) · Go (yüksek performans, tek binary, düşük bellek) · Django (hazır admin paneli, büyük monolit) |
-| 2 | Veritabanı | **PostgreSQL** (önerilen: her şeye yeter, JSON desteği) · SQLite / Turso (tek sunucu, küçük ölçek, sıfır işletme) · MongoDB (şemasız doküman, değişken yapı) |
-| 3 | ORM / sorgu | **SQLAlchemy 2 + Alembic** (Python) · SQLModel (Pydantic ile tek model, daha basit) · Node seçildiyse: Drizzle (önerilen) / Prisma |
-| 4 | Kimlik doğrulama | **Dış sağlayıcının JWT'si** (Supabase Auth / Clerk; kullanıcı yönetimini sen yazmazsın) · API anahtarı (servisler arası, B2B API) · Kendi oturum/JWT'n (tam kontrol; güvenlik yükü sende) |
-| 5 | Arka plan işleri | **Platform cron'u** (önerilen basit zamanlanmış işler için) · ARQ / Celery + Redis (kuyruk, yeniden deneme, yoğun iş) · Temporal / Inngest (çok adımlı, uzun süren iş akışları) · Yok |
-| 6 | API stili | **REST + OpenAPI** (önerilen) · GraphQL (çok farklı istemci, esnek sorgu) · tRPC (sadece TypeScript istemci) |
-| 7 | Barındırma | **Railway** (önerilen: en kolay, Postgres dahil; ücretsiz kalıcı katman yok, Hobby aylık 5 dolar ve 5 dolarlık kullanım içerir (kaynak: https://docs.railway.com/pricing/plans, 2026-10-26)) · Fly.io (kullanıcıya yakın bölge, ölçekleme) · Render · Google Cloud Run (istek başı ödeme, sıfıra ölçeklenir) · VPS + Coolify (sabit maliyet, bakım sende) |
-| 8 | Paket yönetimi | **uv** (önerilen Python için: çok hızlı, kilit dosyası) · Poetry |
-| 9 | Gözlem | **Sentry + yapılandırılmış log** (Better Stack / Axiom) · OpenTelemetry (dağıtık servisler) |
-| 10 | Test | **pytest + httpx** (önerilen) · Node seçildiyse: Vitest + supertest |
+| 1 | Language and framework | **Python + FastAPI** (recommended: AI/data work, fast development, automatic OpenAPI docs) · Node.js + TypeScript + Hono/Fastify (same language as the frontend, shared types) · Go (high performance, single binary, low memory) · Django (ready-made admin panel, large monolith) |
+| 2 | Database | **PostgreSQL** (recommended: fits everything, JSON support) · SQLite / Turso (single server, small scale, zero operations) · MongoDB (schemaless documents, variable structure) |
+| 3 | ORM / queries | **SQLAlchemy 2 + Alembic** (Python) · SQLModel (one model with Pydantic, simpler) · If Node is chosen: Drizzle (recommended) / Prisma |
+| 4 | Authentication | **An external provider's JWT** (Supabase Auth / Clerk; you do not write user management) · API key (service to service, B2B API) · Your own session/JWT (full control; the security burden is yours) |
+| 5 | Background jobs | **Platform cron** (recommended for simple scheduled jobs) · ARQ / Celery + Redis (queue, retries, heavy work) · Temporal / Inngest (multi-step, long-running workflows) · None |
+| 6 | API style | **REST + OpenAPI** (recommended) · GraphQL (many different clients, flexible queries) · tRPC (TypeScript clients only) |
+| 7 | Hosting | **Railway** (recommended: easiest, Postgres included; no free permanent tier, Hobby is 5 dollars a month and includes 5 dollars of usage (kaynak: https://docs.railway.com/pricing/plans, 2026-10-26)) · Fly.io (region close to users, scaling) · Render · Google Cloud Run (pay per request, scales to zero) · VPS + Coolify (fixed cost, maintenance is yours) |
+| 8 | Package management | **uv** (recommended for Python: very fast, lock file) · Poetry |
+| 9 | Observability | **Sentry + structured logs** (Better Stack / Axiom) · OpenTelemetry (distributed services) |
+| 10 | Testing | **pytest + httpx** (recommended) · If Node is chosen: Vitest + supertest |
 
 ## 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.
+> Filled in by `/start` 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 this file's commands, folder, rules, verification and checks sections to match.
 
-| Katman | Seçim | Not |
+| Layer | Choice | Note |
 |---|---|---|
-| Dil | Python 3.12+ | Alternatif: Node.js + TypeScript (Hono/Fastify + Drizzle) |
-| Paket yönetimi | uv | `pip install` değil, `uv add` |
+| Language | Python 3.12+ | Alternative: Node.js + TypeScript (Hono/Fastify + Drizzle) |
+| Package management | uv | `uv add`, not `pip install` |
 | API | FastAPI + Pydantic v2 | |
-| Ayarlar | pydantic-settings | Tüm config ortam değişkeninden |
-| DB | PostgreSQL + SQLAlchemy 2 (veya SQLModel) | |
+| Settings | pydantic-settings | All config comes from environment variables |
+| DB | PostgreSQL + SQLAlchemy 2 (or SQLModel) | |
 | Migration | Alembic | |
-| Arka plan işleri | Cron (platform) / ARQ / Celery | İhtiyaç kadar; basit iş için cron yeter |
+| Background jobs | Cron (platform) / ARQ / Celery | Only as needed; cron is enough for simple jobs |
 | Lint + format | Ruff | |
 | Test | pytest + httpx | |
-| Paketleme | Docker | |
+| Packaging | Docker | |
 | Hosting | Railway / Fly.io / Render | |
-| Hata takibi | Sentry | |
-| Cron izleme | Healthchecks.io (dead man's switch) | İş çalışmazsa alarm |
+| Error tracking | Sentry | |
+| Cron monitoring | Healthchecks.io (dead man's switch) | Alarm if a job does not run |
 
-## Komutlar
+## Komutlar (commands)
 
 ```bash
-uv sync                                  # bağımlılıkları kur
-uv run fastapi dev app/main.py           # geliştirme
+uv sync                                  # install dependencies
+uv run fastapi dev app/main.py           # development
 uv run pytest                            # test
 uv run ruff check .                      # lint
 uv run ruff format .                     # format
-uv run alembic revision --autogenerate -m "[ad]"   # migration oluştur (çıktıyı mutlaka oku)
-uv run alembic upgrade head              # migration uygula
-uv run --with pip-audit pip-audit                            # bağımlılık açıkları
+uv run alembic revision --autogenerate -m "[ad]"   # create a migration (always read the output)
+uv run alembic upgrade head              # apply migrations
+uv run --with pip-audit pip-audit                            # dependency vulnerabilities
 docker build -t [ad] . && docker run --env-file .env -p 8000:8000 [ad]
 ```
 
-## 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).
 ```
 app/
-├── main.py                     # uygulama, router kayıtları, /health
+├── main.py                     # app, router registration, /health
 ├── config.py                   # pydantic-settings
-├── core/                       # veritabanı oturumu, güvenlik, loglama, hata işleyiciler, ortak bağımlılıklar
+├── core/                       # database session, security, logging, error handlers, shared dependencies
 ├── features/
-│   └── <özellik>/              # örn. invoice/
-│       ├── router.py           # HTTP uçları (ince)
-│       ├── service.py          # iş mantığı
-│       ├── repository.py       # veritabanı erişimi
+│   └── <feature>/              # e.g. invoice/
+│       ├── router.py           # HTTP endpoints (thin)
+│       ├── service.py          # business logic
+│       ├── repository.py       # database access
 │       ├── models.py           # SQLAlchemy modelleri
-│       ├── schemas.py          # Pydantic giriş/çıkış şemaları
+│       ├── schemas.py          # Pydantic input/output schemas
 │       ├── dependencies.py
 │       └── exceptions.py
-├── shared/                     # birden fazla özelliğin kullandığı yardımcılar
-└── jobs/                       # zamanlanmış ve arka plan işleri (idempotent)
+├── shared/                     # helpers used by more than one feature
+└── jobs/                       # scheduled and background jobs (idempotent)
 alembic/                        # migration'lar
 tests/
-├── <özellik>/                  # özelliğe göre testler (test_O_01_1_... kabul testleri dahil)
-└── live/                       # canlı izleme testleri
+├── <feature>/                   # tests by feature (test_O_01_1_... kabul testleri dahil)
+└── live/                       # live monitoring tests
 Dockerfile  pyproject.toml  uv.lock
 ```
 
-## Kodlama kuralları
+## Coding rules
 
-- Router ince, iş mantığı `services/`'te.
-- Her uç noktada Pydantic giriş şeması; dönüşte de şema (iç alanlar sızmasın).
-- Tutarlı hata biçimi: `{"error": {"code": "...", "message": "..."}}`.
-- Liste uçlarında sayfalama zorunlu.
-- **Her dış çağrıda açık timeout** (`requests`'te varsayılan timeout yoktur, istek sonsuza kadar asılı kalabilir) ve gerekiyorsa geri çekilmeli tekrar (retry + backoff).
-- İşler (jobs) **idempotent**: iki kez çalışırsa zarar vermez.
-- Loglar yapılandırılmış (JSON), istek kimliği (request id) içerir; kişisel veri ve sır içermez.
-- `/health` ucu: uygulama + DB bağlantısı.
-- Migration'lar elle gözden geçirilir; `autogenerate` her şeyi doğru yakalamaz.
-- Async uçta senkron, bloklayan kütüphane kullanma.
+- Keep the router thin; business logic goes in `services/`.
+- Every endpoint has a Pydantic input schema; the response has a schema too (internal fields must not leak).
+- Use a consistent error format: `{"error": {"code": "...", "message": "..."}}`.
+- Pagination is required on list endpoints.
+- **An explicit timeout on every external call** (`requests` has no default timeout, so a request can hang forever) and, where needed, retry with backoff.
+- Jobs are **idempotent**: running twice does no harm.
+- Logs are structured (JSON) and include the request id; they contain no personal data or secrets.
+- `/health` endpoint: the app + the DB connection.
+- Review migrations by hand; `autogenerate` does not catch everything correctly.
+- Do not use a synchronous, blocking library in an async endpoint.
 
-## Doğrulama (görev bitmeden kanıt)
+## Verification (evidence before a task is done)
 
-- Uç nokta: sunucuyu çalıştır, `curl -i` (veya httpx) ile ana senaryo + yetkisiz istek + geçersiz girdi. İstek ve yanıtı göster.
-- İş/cron: işi elle bir kez tetikle, logu ve DB'deki etkisini göster; iki kez çalıştırıp idempotent olduğunu göster.
-- Migration: `alembic upgrade head` → `alembic downgrade -1` → `alembic upgrade head` temiz geçiyor.
+- Endpoint: run the server, then use `curl -i` (or httpx) for the main scenario + an unauthorized request + invalid input. Show the request and the response.
+- Job/cron: trigger the job by hand once, show the log and its effect in the DB; run it twice and show it is idempotent.
+- Migration: `alembic upgrade head` → `alembic downgrade -1` → `alembic upgrade head` passes cleanly.
 
-## Otomatik kontroller
+## Automatic checks
 
-| Katman | Ne yapar | Kurulum |
+| Layer | What it does | Setup |
 |---|---|---|
-| Claude hook'ları | Sır yazımını engeller; `.py` dosyasını Ruff ile biçimlendirir ve lint hatasını AI'ya geri bildirir | Hazır (`.claude/settings.json`). Node.js gerekir |
-| Pre-commit | Ruff + sır taraması, commit öncesi | `uvx pre-commit install` (bir kez) |
-| CI (+ Semgrep, kopya kod, karmaşıklık bütçesi) | Lint, format, migration, test, açık taraması, Docker build, 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'a push et |
-| Dependabot | Haftalık bağımlılık PR'ları | `.github/dependabot.yml` hazır |
-| MCP | Sentry'deki hataları okuma (`/maintain`) | `.mcp.json` hazır; ilk kullanımda Sentry'ye giriş yap |
+| Claude hooks | Block writing secrets; format `.py` files with Ruff and feed lint errors back to the AI | Ready (`.claude/settings.json`). Needs Node.js |
+| Pre-commit | Ruff + secret scan, before commit | `uvx pre-commit install` (once) |
+| CI (+ Semgrep, duplicate code, complexity budget) | Lint, format, migration, test, vulnerability scan, Docker build, 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; push to GitHub |
+| Dependabot | Weekly dependency PRs | `.github/dependabot.yml` is ready |
+| MCP | Read errors in Sentry (`/maintain`) | `.mcp.json` is ready; sign in to Sentry on first use |
 
-## Kabul testleri ve özellik bayrakları
+## Acceptance tests and feature flags
 
-**Kabul testleri** (`docs/quality/test-plan.md` §1a): Test fonksiyonunun adı kriter kimliğini taşır (`test_O_01_1_...`). Pano JUnit raporunu okur:
+**Acceptance tests** (`docs/quality/test-plan.md` §1a): The test function name carries the criterion id (`test_O_01_1_...`). The dashboard reads the JUnit report:
 
 ```bash
 uv run pytest --junitxml=test-results/junit.xml
 ```
 
-**Özellik bayrakları** (`docs/operations/feature-flags.md`): Acil kapatma yeniden deploy gerektirmemeli. Veritabanında `feature_flags` tablosu (`ad`, `acik`, `yuzde`, `guncellendi`) + süreç içinde 60 sn önbellek. Okuma tek bir yerden yapılır: `app/services/bayrak.py` → `bayrak_acik("ad", kullanici_id)`. Bayrağı değiştirmek bir admin ucu veya SQL ile yapılır ve loglanır.
+**Feature flags** (`docs/operations/feature-flags.md`): An emergency shutoff must not need a redeploy. Use a `feature_flags` table in the database (`ad`, `acik`, `yuzde`, `guncellendi`) + a 60 s in-process cache. Reading happens in one place: `app/services/bayrak.py` → `bayrak_acik("ad", kullanici_id)`. Changing a flag is done through an admin endpoint or SQL and is logged.
 
-## 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 `Path(__file__).parent`, ayardan gelen kök veya testte `tmp_path` ile türet. Deterministik kapı bunu yakalar.
-- Pydantic v1 sözdizimini (`class Config`, `.dict()`) v2 ile karıştırmak.
-- Dış API çağrısında timeout koymamak, hatayı yutmak (`except: pass`).
-- CORS'u `allow_origins=["*"]` ile kimlik bilgisiyle birlikte açmak.
-- Cron işini sunucu içinde `while True: sleep` ile yazmak (yeniden başlayınca kaybolur, izlenemez).
-- DB oturumunu kapatmamak, bağlantı havuzunu tüketmek.
+- Writing a machine-specific absolute path 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 `Path(__file__).parent`, a root from settings, or `tmp_path` in a test. The deterministic gate catches this.
+- Mixing Pydantic v1 syntax (`class Config`, `.dict()`) with v2.
+- Not setting a timeout on an external API call, swallowing the error (`except: pass`).
+- Opening CORS with `allow_origins=["*"]` together with credentials.
+- Writing a cron job inside the server as `while True: sleep` (lost on restart, cannot be monitored).
+- Not closing the DB session, exhausting the connection pool.
 
-## Güvenlik (ek)
+## Security (extra)
 
-- [ ] Kimlik doğrulama: JWT doğrulaması (imza + süre + issuer) veya API anahtarı (hash'lenmiş saklanır).
-- [ ] Rate limit (slowapi veya reverse proxy).
-- [ ] Prod'da `/docs` ve `/openapi.json` kapalı veya korumalı.
-- [ ] CORS beyaz liste.
-- [ ] Docker imajı root olmayan kullanıcıyla çalışıyor, imajda `.env` yok.
+- [ ] Authentication: JWT verification (signature + expiry + issuer) or an API key (stored hashed).
+- [ ] Rate limit (slowapi or reverse proxy).
+- [ ] `/docs` and `/openapi.json` are off or protected in prod.
+- [ ] CORS allowlist.
+- [ ] The Docker image runs as a non-root user, and the image has no `.env`.
 
-## Canlıya alma (ek)
+## Go live (extra)
 
-- [ ] Dockerfile: çok aşamalı, root olmayan kullanıcı, `HEALTHCHECK`
-- [ ] Platformda health check `/health`'e bağlı
-- [ ] Migration deploy adımında otomatik veya kontrollü çalışıyor (uygulamadan önce)
-- [ ] Ortam değişkenleri platformda; `DEBUG` kapalı
-- [ ] Kaynak limitleri (bellek/CPU) ve otomatik yeniden başlatma
-- [ ] Her cron işi Healthchecks.io'ya ping atıyor; atmazsa alarm
-- [ ] Log saklama ve arama (platform logları veya Better Stack/Axiom)
-- [ ] Yük altında basit deneme (`hey`, `k6`): beklenen trafiğin 3 katında hata yok
-- [ ] Yanıt süresi hedefi: p95 < 500 ms (ana uçlar)
+- [ ] Dockerfile: multi-stage, non-root user, `HEALTHCHECK`
+- [ ] The platform health check points to `/health`
+- [ ] Migration runs automatically or in a controlled way at the deploy step (before the app)
+- [ ] Environment variables are on the platform; `DEBUG` is off
+- [ ] Resource limits (memory/CPU) and automatic restart
+- [ ] Every cron job pings Healthchecks.io; an alarm fires if it does not
+- [ ] Log retention and search (platform logs or Better Stack/Axiom)
+- [ ] A simple load trial (`hey`, `k6`): no errors at 3 times the expected traffic
+- [ ] Response time target: p95 < 500 ms (main endpoints)
 
-## Bakım (ek)
+## Maintenance (extra)
 
-- Haftalık: cron işleri başarılı mı, kuyruk birikmesi var mı, 5xx oranı.
-- Aylık: `uv lock --upgrade` + testler, `uv run --with pip-audit pip-audit`, yavaş sorgular (`pg_stat_statements`).
-- Çeyreklik: Python ve temel kütüphanelerin majör sürümleri, Docker taban imajı güncellemesi, DB indeks ve boyut gözden geçirme.
+- Weekly: did the cron jobs succeed, is the queue backing up, the 5xx rate.
+- Monthly: `uv lock --upgrade` + tests, `uv run --with pip-audit pip-audit`, slow queries (`pg_stat_statements`).
+- Quarterly: major versions of Python and core libraries, Docker base image update, DB index and size review.

package/kit/templates/backend/docs/architecture/structure.md

@@ -1,62 +1,62 @@
-# Proje yapısı: Backend (FastAPI)
+# Project structure: Backend (FastAPI)
 
-> 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-readable description of the `.claude/structure.json` map; update both together.
+> Following the structure is mandatory: the hook checks at write time, CI on every PR, the board Architect and `/findings-tech` also check.
 
-## Kod
+## Code
 
 ```
 app/
-├── main.py                     # uygulama, router kayıtları, /health
+├── main.py                     # app, router registrations, /health
 ├── config.py                   # pydantic-settings
-├── core/                       # veritabanı oturumu, güvenlik, loglama, hata işleyiciler, ortak bağımlılıklar
+├── core/                       # database session, security, logging, error handlers, common dependencies
 ├── features/
-│   └── <özellik>/              # örn. invoice/
-│       ├── router.py           # HTTP uçları (ince)
-│       ├── service.py          # iş mantığı
-│       ├── repository.py       # veritabanı erişimi
-│       ├── models.py           # SQLAlchemy modelleri
-│       ├── schemas.py          # Pydantic giriş/çıkış şemaları
+│   └── <feature>/              # e.g. invoice/
+│       ├── router.py           # HTTP endpoints (thin)
+│       ├── service.py          # business logic
+│       ├── repository.py       # database access
+│       ├── models.py           # SQLAlchemy models
+│       ├── schemas.py          # Pydantic input/output schemas
 │       ├── dependencies.py
 │       └── exceptions.py
-├── shared/                     # birden fazla özelliğin kullandığı yardımcılar
-└── jobs/                       # zamanlanmış ve arka plan işleri (idempotent)
-alembic/                        # migration'lar
+├── shared/                     # helpers used by more than one feature
+└── jobs/                       # scheduled and background jobs (idempotent)
+alembic/                        # migrations
 tests/
-├── <özellik>/                  # özelliğe göre testler (test_O_01_1_... kabul testleri dahil)
-└── live/                       # canlı izleme testleri
+├── <feature>/                  # tests by feature (including test_O_01_1_... acceptance tests)
+└── live/                       # live monitoring tests
 Dockerfile  pyproject.toml  uv.lock
 ```
 
-## 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 an interface)
+│   ├── 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 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) lives under `features/<feature>/`. When two features start using the same code, it moves to the shared layer (`components/`, `lib/`, `shared/`).
+3. **Features do not reach into each other.** `features/a` does not import another feature's internal files; it uses only what that feature exposes through its `index` file.
+4. **Naming:** Folders and files use `kebab-case`. React component files may be `PascalCase.tsx`; Python modules use `snake_case.py`. A feature folder name is singular and in English (`invoice`, `customer`).
+5. **Temporary and unrelated work** goes under `sandbox/`. If something useful comes out of it, 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/mobile/.claude/structure.json

@@ -1,5 +1,5 @@
 {
-  "description": "Mobil (Expo Router, özellik bazlı). Yeni dosyalar sadece bu kalıplara uyan yerlere yazılır; değiştirmek teknik bir karardır. Ayrıntı: docs/architecture/structure.md",
+  "description": "Mobile (Expo Router, by feature). New files are written only to places that match these patterns; changing them is a technical decision. Details: docs/architecture/structure.md",
   "allow": [
     "README.md",
     "CHANGELOG.md",

package/kit/templates/mobile/.env.example

@@ -1,14 +1,14 @@
-# Bu dosya commit edilir; GERÇEK DEĞER YAZMA. Kopyala: cp .env.example .env
-# Yerel değerler sadece GELİŞTİRME (dev) projesinden gelir. Prod değerleri sadece EAS ortam değişkenlerinde durur; bu makineye ve AI ortamına girmez.
-# EXPO_PUBLIC_ ile başlayanlar uygulama paketine gömülür = herkese açık.
-# Gizli anahtar gerektiren her işlem sunucuda (Supabase Edge Function / backend) yapılır.
+# This file is committed; DO NOT WRITE REAL VALUES. Copy: cp .env.example .env
+# Local values come only from the DEVELOPMENT (dev) project. Production values live only in EAS environment variables; they never reach this machine or the AI environment.
+# Variables starting with EXPO_PUBLIC_ are embedded in the app bundle = public.
+# Anything that needs a secret key runs on the server (Supabase Edge Function / backend).
 
 EXPO_PUBLIC_API_URL=
 EXPO_PUBLIC_SUPABASE_URL=
-EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=   # sb_publishable_… (gizli anahtar uygulamaya girmez)
+EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=   # sb_publishable_… (the secret key never goes into the app)
 EXPO_PUBLIC_REVENUECAT_IOS_KEY=
 EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=
 EXPO_PUBLIC_SENTRY_DSN=
 
-# Sadece build/EAS tarafında (pakete girmez; EAS Secrets'a da ekle)
+# Build/EAS side only (not bundled in the app; add to EAS Secrets too)
 SENTRY_AUTH_TOKEN=

package/kit/templates/mobile/.github/dependabot.yml

@@ -1,5 +1,5 @@
-# Expo SDK'ya bağlı paketler Dependabot ile değil, 'npx expo install --fix' ile güncellenir.
-# Güvenlik güncellemeleri için: GitHub > Settings > Code security > Dependabot security updates: Açık.
+# Packages tied to the Expo SDK are updated with 'npx expo install --fix', not with Dependabot.
+# For security updates: GitHub > Settings > Code security > Dependabot security updates: On.
 version: 2
 updates:
   - package-ecosystem: npm

package/kit/templates/mobile/.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-# Her push ve PR'da çalışır. Build (EAS) burada değil, EAS'ta yapılır.
+# Runs on every push and PR. The build (EAS) is not done here; it is done on EAS.
 name: CI
 
 on:
@@ -6,7 +6,7 @@ on:
     branches: [main]
   pull_request:
 
-# İşler depoyu sadece okur; ele geçirilen bir adım token ile depoya yazamasın
+# Jobs only read the repo; a hijacked step must not be able to write to the repo with the token
 permissions:
   contents: read
 
@@ -23,16 +23,16 @@ jobs:
       - run: npx expo lint
       - run: npx tsc --noEmit
       - run: npm run --if-present test
-      - name: SDK uyumu
+      - name: SDK compatibility
         run: npx expo-doctor
-      - name: Bağımlılık açıkları (yüksek ve üstü)
+      - name: Dependency vulnerabilities (high and above)
         run: npm audit --audit-level=high --omit=dev
 
   structure:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - name: Klasör yapısı (.claude/structure.json)
+      - name: Folder structure (.claude/structure.json)
         run: node .claude/hooks/structure-guard.mjs --check
 
   karmasiklik:
@@ -40,14 +40,14 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          fetch-depth: 0 # base commit'iyle karşılaştırmak için
-      - name: Karmaşıklık bütçesi (değişen dosyalar; fonksiyon karmaşıklığı 15, fonksiyon 80, dosya 400 satır)
+          fetch-depth: 0 # to compare with the base commit
+      - name: Complexity budget (changed files; function complexity 15, function 80, file 400 lines)
         env:
           BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
         run: node .claude/hooks/budget.mjs --check --base "$BASE"
 
-  # RLS saldırgan testi: CI içinde boş bir yerel Supabase açılır, migration'lar uygulanır. Sır gerekmez; dev ve prod'a dokunmaz.
-  # Supabase kullanılmıyorsa (supabase/config.toml yoksa) adımlar atlanır.
+  # RLS adversarial test: an empty local Supabase starts inside CI and the migrations are applied. No secrets needed; it does not touch dev or prod.
+  # If Supabase is not used (no supabase/config.toml), the steps are skipped.
   rls:
     runs-on: ubuntu-latest
     steps:
@@ -59,13 +59,13 @@ jobs:
           cache: npm
       - if: hashFiles('supabase/config.toml') != ''
         run: npm ci
-      - name: Yerel Supabase
+      - name: Local Supabase
         if: hashFiles('supabase/config.toml') != ''
         run: npx -y supabase@2.120.0 start -x studio,imgproxy,edge-runtime,logflare,vector,realtime,storage-api,supavisor,postgres-meta
-      - name: RLS saldırgan testi (anonim ve ikinci kullanıcı)
+      - name: RLS adversarial test (anonymous and second user)
         if: hashFiles('supabase/config.toml') != ''
         run: |
-          # Sadece gereken anahtarlar alınır; çıktı kabuk komutu olarak çalıştırılmaz
+          # Only the needed keys are taken; the output is not run as a shell command
           anahtarlar=$(npx -y supabase@2.120.0 status -o env | grep -E '^(API_URL|ANON_KEY|SERVICE_ROLE_KEY|DB_URL|PUBLISHABLE_KEY|SECRET_KEY)=')
           while IFS="=" read -r ad deger; do deger="${deger%\"}"; export "$ad=${deger#\"}"; done <<< "$anahtarlar"
           node --test tests/security/rls.mjs
@@ -76,29 +76,29 @@ jobs:
       image: semgrep/semgrep
     steps:
       - uses: actions/checkout@v7
-      - name: Statik güvenlik analizi (yüksek önemli bulgular CI'ı durdurur)
+      - name: Static security analysis (high severity findings stop CI)
         run: semgrep scan --config p/default --config p/owasp-top-ten --severity ERROR --error
 
   kopya-kod:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - name: Kopya kod oranı (eşik %5)
+      - name: Duplicate code ratio (threshold 5%)
         run: npx --yes jscpd@4 --threshold 5 --silent --ignore "**/node_modules/**,**/.next/**,**/dist/**,**/build/**,**/.venv/**,**/coverage/**,**/.expo/**" .
 
   sir-taramasi:
     runs-on: ubuntu-latest
-    # gitleaks PR'da commit listesini okur (pulls/{n}/commits); özel depoda bu izin olmadan 403
+    # gitleaks reads the commit list on a PR (pulls/{n}/commits); in a private repo this gives 403 without this permission
     permissions:
       contents: read
       pull-requests: read
     steps:
       - uses: actions/checkout@v7
         with:
-          fetch-depth: 0 # tüm geçmiş taranır
-      # Kişisel hesapta ücretsiz; organizasyon deposunda GITLEAKS_LICENSE sırrı gerekir
+          fetch-depth: 0 # the whole history is scanned
+      # Free on a personal account; an organization repo needs the GITLEAKS_LICENSE secret
       - uses: gitleaks/gitleaks-action@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Token salt okunur: PR yorumu kapalı, sızıntı işi kırmızı yapar
+          # The token is read-only: PR comments are off, a leak turns the job red
           GITLEAKS_ENABLE_COMMENTS: "false"