Geliştirici için derin teknik rehber

heyirona'ya teknik bakış

Bu sayfa heyirona'nın çalışan iskeletini özetler: stack, /build ve /toplanti mimarisi, state machine'leri, tüm API endpoint'leri, Postgres şeması, RLS deseni, env değişkenleri, anonimlik kuralı ve katkı süreci. Inora'yı çalıştırırken referans olarak açık tut.

Bölüm 01

Stack

Üretimde olan kütüphane sürümleri ve rolleri. package.json tek doğru kaynak; aşağıdakiler hızlı referans.

Paket	Sürüm	Rol
Next.js	16.x (Turbopack)	App Router, RSC, server actions, SSE stream'ler.
React	19.x	Suspense, useTransition, ref-as-prop, async server component.
Tailwind CSS	v4	Token-bazlı utility; CSS-first config (@theme).
Anthropic SDK	@anthropic-ai/sdk ^0.96	Claude tabanlı ajan ürünü; iterate ve toplantı motoru.
Supabase	@supabase/ssr ^0.10	Auth (telefon OTP + Google), Postgres, RLS, server-side cookie session.
Stripe	Checkout + webhook	Pro / Team abonelik; stripe_events ile idempotency.
DeepSeek	REST TTS	Toplantı sahnesinde ajan başına ses; /api/tts proxy üzerinden.
Vercel	Deploy API	/api/deploy üretilen projeyi Vercel'e push eder.

Bölüm 02

Mimari

İki ana akış: /build (kod üretim) ve /toplanti (council toplantısı). İkisi de SSE üzerinden ajan stream'i tüketir.

/build akışı

BuildClientV2 tek bir React state'i tutar. Kullanıcı brief'ini POST /api/iterate'e gönderir; sunucu Claude'dan gelen XML benzeri akışı FileStreamParser ile parse eder ve <file path=...> blokları SSE event olarak akıtılır. V2 leaf component'ler (BuildCenter, BuildChat, BuildSidebar...) salt sunum yapar; state mutasyonu yalnızca BuildClientV2 içinden geçer.

› src/app/build/BuildClientV2.tsx
› src/components/build/*
› src/app/api/iterate/route.ts
› src/lib/fileStreamParser.ts

/toplanti akışı

MeetingRoomV2 council toplantısını yönetir. POST /api/toplanti SSE üzerinden ajan turlarını yayınlar; istemci SAX-tarzı bir parser ile speaker/note callback'lerini chunk chunk işler. Konuşma bitince ilgili ajan için /api/tts çağrılır ve per-agent ses dosyası AgentTile altında oynatılır.

› src/app/toplanti/MeetingRoomV2.tsx
› src/components/toplanti/*
› src/app/api/toplanti/route.ts
› src/app/api/tts/route.ts

Bölüm 03

State machine

Hem /build hem /toplanti faz tabanlı (discriminated union). Phase değişimi her zaman tek bir reducer noktasından geçer.

BuildPhase

src/components/build/types.ts

idle: Welcome surface, prompt input açık; proje yüklü değil.
preparing: İlk brief gönderildi; ilk stream byte'ı bekleniyor.
building: Dosyalar akıyor (ilk üretim turu).
review: Build bitti; preview render edildi, iteration açık.
iterating: Review sonrası tekrar stream; değişiklikler uygulanıyor.
saving: Arka planda Supabase'e persist; UI etkileşimli kalır.
error: Hata yüzeyi; retryable ise CTA ile yeniden denetir.

MeetingPhase

src/components/toplanti/types.ts

idle: Konu girişi açık; council henüz başlamadı.
intro: Inora orkestratör konuyu açar; ajanlar tanışır.
discussion: Ajanlar sırayla konuşur; SSE turn akışı sürer.
user-input: Patron araya girer; mikrofon veya yazılı yorum.
summary: Inora özet ve aksiyon listesi üretir.
handoff: Toplantı çıktısı /build'e taşınır (MeetingHandoff).
error: Hata yüzeyi; transcript korunur.

Bölüm 04

API endpoint'leri

Tüm rotalar src/app/api altında. auth kolonu: public = anon, auth = Supabase session, webhook = imza doğrulamalı.

Method	Path	Auth	Not
POST	/api/iterate	auth	Multi-variant, image input ve priorTurns destekli ana akış endpoint'i.
POST	/api/iterate/variants	auth	Aynı brief için paralel varyant üretimi (BuildVariantStrip).
POST	/api/iterate/inline-edit	auth	Editor içinden seçili bloğa noktasal düzenleme.
POST	/api/iterate/explain	auth	Üretilen kodu doğal dilde açıklar (BuildExplainCode).
GET / POST	/api/projects	auth	Kullanıcının projelerini listele veya yeni proje aç.
GET / PATCH / DELETE	/api/projects/[id]	auth	Tek proje oku, başlık/dosya güncelle, sil.
GET / POST	/api/projects/[id]/iterations	auth	Proje için iteration listesi ve yeni snapshot.
GET	/api/projects/[id]/export	auth	Projeyi JSZip ile paketler; tarayıcıya ZIP olarak akıtır.
GET / POST / DELETE	/api/cloud-data	auth	Bundled Cloud KV. Iframe içindeki window.cloud SDK postMessage bridge ile bu endpoint'i çağırır. 256 KB değer/limit.
POST	/api/projects/import	auth	Daha önce dışa aktarılan ZIP'i geri yükler.
GET	/api/projects/search	auth	Başlık / prompt üzerinde tam-metin arama.
POST	/api/projects/fork	auth	Başka bir projeyi (kendi veya paylaşılan) çatallar.
POST	/api/toplanti	auth	SSE; council turlarını chunked olarak akıtır.
POST	/api/toplanti/save	auth	Toplantı transcript'ini iteration olarak kalıcılaştırır.
POST	/api/tts	auth	ElevenLabs proxy; per-agent ses üretir.
POST	/api/deploy	auth	Vercel Deploy API'sine push; deployment id döner.
GET	/api/deploy/status/[id]	auth	Deployment progress polling.
GET / POST / DELETE	/api/share	auth	Sahibin oluşturduğu paylaşım slug'larını yönetir.
GET	/api/share/[slug]	public	Anonim ziyaretçi paylaşılan projeye read-only erişir.
POST	/api/billing/checkout	auth	Stripe Checkout session açar (Pro / Team price).
POST	/api/billing/webhook	webhook	Stripe imza doğrular; stripe_events tablosu ile idempotent işler.
POST	/api/github/sync	auth	Üretilen projeyi GitHub repo'suna senkron eder.
POST / GET	/api/whatsapp/webhook	webhook	GET verify_token, POST imza doğrulamalı mesaj alımı.
GET	/api/whatsapp/status	auth	Bağlı WhatsApp numarası ve son aktivite durumu.
POST	/api/auth/phone-otp/request	public	Telefon numarasına OTP gönderir (rate-limit + IP_SALT_SECRET).
POST	/api/auth/phone-otp/verify	public	OTP'yi doğrular ve Supabase session cookie kurar.
GET / PATCH	/api/me	auth	Mevcut kullanıcı profili (plan, email, tercihler).
POST	/api/contact	public	İletişim formu; CONTACT_EMAIL_WEBHOOK'a iletir.
GET	/api/health	public	Liveness ucu; HEALTH_TOKEN varsa header zorunlu.

Bölüm 05

DB şeması

5 tablo, hepsi RLS açık. Migration dosyaları supabase/migrations/ altında, sırayla 0001 → 0003.

Tablo	Kolonlar	Not
profiles	id (auth.users), email, plan (free\|pro\|team), created_at	Her auth user için 1 satır; trigger ile otomatik açılır.
projects	id, owner_id, title, prompt, files (jsonb), created_at, updated_at	Tüm üretilen dosya ağacı files kolonunda saklanır.
iterations	id, project_id, prompt, files (jsonb), created_at	Proje başına tarihçe; her iterate turu yeni satır.
shares	slug (pk), project_id, created_by, created_at, revoked_at, view_count	Anonim okuma için public read-only policy.
stripe_events	id (pk = event.id), type, received_at, processed_at, processing_error	Webhook idempotency ledger; sadece service role yazar.
cloud_data	id, owner_id, project_id, collection, key, value (jsonb), created_at, updated_at	Bundled Cloud KV — üretilen uygulamalar window.cloud ile yazıp okur. unique (owner, project, collection, key).

supabase/migrations/0001_init.sql · 0002_shares.sql · 0003_stripe_events.sql · 0004_share_grants.sql · 0005_project_metadata.sql · 0006_agent_metrics.sql · 0007_cloud_data.sql

Bölüm 06

RLS — owner_id = auth.uid()

Tüm kullanıcı verisi sahibine kilitli. Service-role anahtarı sadece webhook'larda kullanılır; RLS'i bypass edebildiği için hiçbir route handler'a sızdırılmaz.

Desen tüm tablolarda aynı: enable row level security + her CRUD action için ayrı policy. projects tablosunun policy seti tipik bir örnektir:

-- select
using (auth.uid() = owner_id)

-- insert
with check (auth.uid() = owner_id)

-- update
using (auth.uid() = owner_id)
with check (auth.uid() = owner_id)

-- delete
using (auth.uid() = owner_id)

·iterations: erişim, bağlı projenin sahibi üzerinden zincirlenir (subquery).
·shares: sahip yönetir; anon ziyaretçi sadece slug üzerinden public-read policy ile okur.
·stripe_events: RLS açık, policy yok — yalnızca service-role yazar.

Bölüm 07

Env değişkenleri

.env.local içinde tutulur; Vercel'de Project Settings → Environment Variables üzerinden yansıtılır. Zorunlu olanlar olmadan üretim build'i ayağa kalkmaz.

Anahtar	Zorunlu	Not
ANTHROPIC_API_KEY	zorunlu	Claude ajan motoru.
NEXT_PUBLIC_SUPABASE_URL	zorunlu	Browser + server tarafı Supabase URL.
NEXT_PUBLIC_SUPABASE_ANON_KEY	zorunlu	Anon istemci anahtarı.
SUPABASE_SERVICE_ROLE_KEY	zorunlu	Webhook + bypass RLS gerektiren server işleri.
NEXT_PUBLIC_BASE_URL	zorunlu	Canonical site URL (canonical, OG, redirect).
STRIPE_SECRET_KEY	opsiyonel	Billing açık değilse boş bırakılabilir.
STRIPE_WEBHOOK_SECRET	opsiyonel	/api/billing/webhook imzası.
STRIPE_PRICE_ID_PRO	opsiyonel	Pro plan price id.
STRIPE_PRICE_ID_TEAM	opsiyonel	Team plan price id.
ELEVENLABS_API_KEY	opsiyonel	Toplantı sesi; yoksa toplantı sessiz çalışır.
VERCEL_TOKEN	opsiyonel	/api/deploy için gerekli.
VERCEL_TEAM_ID	opsiyonel	Team scope deploy ediliyorsa.
VERCEL_PROJECT_PREFIX	opsiyonel	Üretilen proje adlarına prefix.
GITHUB_APP_ID	opsiyonel	GitHub App entegrasyonu.
GITHUB_APP_TOKEN	opsiyonel	App seviyesi token.
GITHUB_CLIENT_ID	opsiyonel	OAuth akışı.
GITHUB_CLIENT_SECRET	opsiyonel	OAuth secret.
GITHUB_TOKEN	opsiyonel	PAT yedeği (CI / debug).
WHATSAPP_ACCESS_TOKEN	opsiyonel	Cloud API token.
WHATSAPP_APP_SECRET	opsiyonel	Webhook imza doğrulama.
WHATSAPP_PHONE_NUMBER_ID	opsiyonel	Gönderim numarası id.
WHATSAPP_VERIFY_TOKEN	opsiyonel	Webhook verify handshake.
IP_SALT_SECRET	opsiyonel	Telefon OTP rate-limit hash salt.
SHARE_SLUG_SECRET	opsiyonel	Share slug üretiminde HMAC tohumu.
ADMIN_EMAIL	opsiyonel	Yönetim bildirimleri.
CONTACT_EMAIL_WEBHOOK	opsiyonel	/api/contact gönderim hedefi.
HEALTH_TOKEN	opsiyonel	/api/health için header doğrulaması.
SENTRY_DSN	opsiyonel	Server-side error reporting.
NEXT_PUBLIC_ERROR_WEBHOOK	opsiyonel	Client error reporting.
NEXT_PUBLIC_PLAUSIBLE_DOMAIN	opsiyonel	Plausible domain (analytics).
NEXT_PUBLIC_PLAUSIBLE_HOST	opsiyonel	Self-host Plausible varsa.

Bölüm 08

Anonimlik kuralı

Bu kural pazarlama veya stilistik değil; mimari bir invaryant. heyirona kod tabanında, commit author'da ve deploy izinde gerçek isim geçmez.

›Tüm git commit'leri local <local@heyirona> author ile düşer. Ortam değişkenleri GIT_AUTHOR_NAME=local, GIT_AUTHOR_EMAIL=local@heyirona shell'de export edilir.
›Kod, yorum, seed, deploy logu, doküman veya release notu; hiçbiri gerçek isim, takım üyesi adı veya kişisel iletişim bilgisi içermez. Marka adı olarak yalnızca Inora, proje kod adı olarak heyirona geçer.
›İletişim noktası tek bir kurumsal e-posta / /contact formudur. Geliştirici PR açarken kendi adını commit author'a koymaz; yerel git config'i yukarıdaki değerlere ayarlayıp gönderir.

Bölüm 09

Katkıda bulun

Küçük, odaklanmış PR'lar. Tek bir lane, tek bir sorun, yeşil tsc.

Code style

TypeScript strict; any yasak.
Server bileşenler varsayılan; client'a sadece gerek varsa indirilir.
Tailwind v4 token'ları kullan; renk kodu hard-code etme.
State mutasyonu tek bir reducer noktasından geçer.
Yorumlar kısa Türkçe; niye'yi anlatır, ne'yi değil.

Branch naming

feat/<scope>-<kisa-ad>
fix/<scope>-<kisa-ad>
chore/<scope>-<kisa-ad>
docs/<scope>-<kisa-ad>
Örn: feat/build-variant-strip

Commit message

Conventional Commits:
feat(build): add variant strip
fix(api): guard iterate auth
İlk satır 72 karakteri geçmez; gövde opsiyonel.
Author hep local.

Daha fazlası için kaynağa in

Bu sayfa kontrat; gerçek davranış kodda. AGENTS.md ve PROGRESS.md kök dizinde, migration'lar supabase/ altında, ajan prompt'ları ise route handler'ların yanı başında.

Tüm dokümanlara dön /build'i çalıştır

Paket

Sürüm

Rol

Next.js

16.x (Turbopack)

App Router, RSC, server actions, SSE stream'ler.

React

19.x

Suspense, useTransition, ref-as-prop, async server component.

Tailwind CSS

Token-bazlı utility; CSS-first config (@theme).

Anthropic SDK

@anthropic-ai/sdk ^0.96

Claude tabanlı ajan ürünü; iterate ve toplantı motoru.

Supabase

@supabase/ssr ^0.10

Auth (telefon OTP + Google), Postgres, RLS, server-side cookie session.

Stripe

Checkout + webhook

Pro / Team abonelik; stripe_events ile idempotency.

DeepSeek

REST TTS

Toplantı sahnesinde ajan başına ses; /api/tts proxy üzerinden.

Vercel

Deploy API

/api/deploy üretilen projeyi Vercel'e push eder.

Method

Path

Auth

Not

POST

/api/iterate

auth

Multi-variant, image input ve priorTurns destekli ana akış endpoint'i.

POST

/api/iterate/variants

auth

Aynı brief için paralel varyant üretimi (BuildVariantStrip).

POST

/api/iterate/inline-edit

auth

Editor içinden seçili bloğa noktasal düzenleme.

POST

/api/iterate/explain

auth

Üretilen kodu doğal dilde açıklar (BuildExplainCode).

GET / POST

/api/projects

auth

Kullanıcının projelerini listele veya yeni proje aç.

GET / PATCH / DELETE

/api/projects/[id]

auth

Tek proje oku, başlık/dosya güncelle, sil.

GET / POST

/api/projects/[id]/iterations

auth

Proje için iteration listesi ve yeni snapshot.

GET

/api/projects/[id]/export

auth

Projeyi JSZip ile paketler; tarayıcıya ZIP olarak akıtır.

GET / POST / DELETE

/api/cloud-data

auth

Bundled Cloud KV. Iframe içindeki window.cloud SDK postMessage bridge ile bu endpoint'i çağırır. 256 KB değer/limit.

POST

/api/projects/import

auth

Daha önce dışa aktarılan ZIP'i geri yükler.

GET

/api/projects/search

auth

Başlık / prompt üzerinde tam-metin arama.

POST

/api/projects/fork

auth

Başka bir projeyi (kendi veya paylaşılan) çatallar.

POST

/api/toplanti

auth

SSE; council turlarını chunked olarak akıtır.

POST

/api/toplanti/save

auth

Toplantı transcript'ini iteration olarak kalıcılaştırır.

POST

/api/tts

auth

ElevenLabs proxy; per-agent ses üretir.

POST

/api/deploy

auth

Vercel Deploy API'sine push; deployment id döner.

GET

/api/deploy/status/[id]

auth

Deployment progress polling.

GET / POST / DELETE

/api/share

auth

Sahibin oluşturduğu paylaşım slug'larını yönetir.

GET

/api/share/[slug]

public

Anonim ziyaretçi paylaşılan projeye read-only erişir.

POST

/api/billing/checkout

auth

Stripe Checkout session açar (Pro / Team price).

POST

/api/billing/webhook

webhook

Stripe imza doğrular; stripe_events tablosu ile idempotent işler.

POST

/api/github/sync

auth

Üretilen projeyi GitHub repo'suna senkron eder.

POST / GET

/api/whatsapp/webhook

webhook

GET verify_token, POST imza doğrulamalı mesaj alımı.

GET

/api/whatsapp/status

auth

Bağlı WhatsApp numarası ve son aktivite durumu.

POST

/api/auth/phone-otp/request

public

Telefon numarasına OTP gönderir (rate-limit + IP_SALT_SECRET).

POST

/api/auth/phone-otp/verify

public

OTP'yi doğrular ve Supabase session cookie kurar.

GET / PATCH

/api/me

auth

Mevcut kullanıcı profili (plan, email, tercihler).

POST

/api/contact

public

İletişim formu; CONTACT_EMAIL_WEBHOOK'a iletir.

GET

/api/health

public

Liveness ucu; HEALTH_TOKEN varsa header zorunlu.

Tablo

Kolonlar

Not

profiles

id (auth.users), email, plan (free|pro|team), created_at

Her auth user için 1 satır; trigger ile otomatik açılır.

projects

id, owner_id, title, prompt, files (jsonb), created_at, updated_at

Tüm üretilen dosya ağacı files kolonunda saklanır.

iterations

id, project_id, prompt, files (jsonb), created_at

Proje başına tarihçe; her iterate turu yeni satır.

slug (pk), project_id, created_by, created_at, revoked_at, view_count

Anonim okuma için public read-only policy.

stripe_events

id (pk = event.id), type, received_at, processed_at, processing_error

Webhook idempotency ledger; sadece service role yazar.

cloud_data

id, owner_id, project_id, collection, key, value (jsonb), created_at, updated_at

Bundled Cloud KV — üretilen uygulamalar window.cloud ile yazıp okur. unique (owner, project, collection, key).

-- select using (auth.uid() = owner_id) -- insert with check (auth.uid() = owner_id) -- update using (auth.uid() = owner_id) with check (auth.uid() = owner_id) -- delete using (auth.uid() = owner_id)

Anahtar

Zorunlu

Not

ANTHROPIC_API_KEY

zorunlu

Claude ajan motoru.

NEXT_PUBLIC_SUPABASE_URL

zorunlu

Browser + server tarafı Supabase URL.

NEXT_PUBLIC_SUPABASE_ANON_KEY

zorunlu

Anon istemci anahtarı.

SUPABASE_SERVICE_ROLE_KEY

zorunlu

Webhook + bypass RLS gerektiren server işleri.

NEXT_PUBLIC_BASE_URL

zorunlu

Canonical site URL (canonical, OG, redirect).

STRIPE_SECRET_KEY

opsiyonel

Billing açık değilse boş bırakılabilir.

STRIPE_WEBHOOK_SECRET

opsiyonel

/api/billing/webhook imzası.

STRIPE_PRICE_ID_PRO

opsiyonel

Pro plan price id.

STRIPE_PRICE_ID_TEAM

opsiyonel

Team plan price id.

ELEVENLABS_API_KEY

opsiyonel

Toplantı sesi; yoksa toplantı sessiz çalışır.

VERCEL_TOKEN

opsiyonel

/api/deploy için gerekli.

VERCEL_TEAM_ID

opsiyonel

Team scope deploy ediliyorsa.

VERCEL_PROJECT_PREFIX

opsiyonel

Üretilen proje adlarına prefix.

GITHUB_APP_ID

opsiyonel

GitHub App entegrasyonu.

GITHUB_APP_TOKEN

opsiyonel

App seviyesi token.

GITHUB_CLIENT_ID

opsiyonel

OAuth akışı.

GITHUB_CLIENT_SECRET

opsiyonel

OAuth secret.

GITHUB_TOKEN

opsiyonel

PAT yedeği (CI / debug).

WHATSAPP_ACCESS_TOKEN

opsiyonel

Cloud API token.

WHATSAPP_APP_SECRET

opsiyonel

Webhook imza doğrulama.

WHATSAPP_PHONE_NUMBER_ID

opsiyonel

Gönderim numarası id.

WHATSAPP_VERIFY_TOKEN

opsiyonel

Webhook verify handshake.

IP_SALT_SECRET

opsiyonel

Telefon OTP rate-limit hash salt.

SHARE_SLUG_SECRET

opsiyonel

Share slug üretiminde HMAC tohumu.

ADMIN_EMAIL

opsiyonel

Yönetim bildirimleri.

CONTACT_EMAIL_WEBHOOK

opsiyonel

/api/contact gönderim hedefi.

HEALTH_TOKEN

opsiyonel

/api/health için header doğrulaması.

SENTRY_DSN

opsiyonel

Server-side error reporting.

NEXT_PUBLIC_ERROR_WEBHOOK

opsiyonel

Client error reporting.

NEXT_PUBLIC_PLAUSIBLE_DOMAIN

opsiyonel

Plausible domain (analytics).

NEXT_PUBLIC_PLAUSIBLE_HOST

opsiyonel

Self-host Plausible varsa.