Kavramlar ve mimari

Bu dokümantasyonu nasıl okumalısınız?

• Kavramları önce özümseyin; sonra Öğrenme yolu ile sayfa sayfa ilerleyin.
• Uygulama içi işlemler için Arayüz rehberi ve ilgili Usage sayfalarına bakın.
• Geliştirici entegrasyonu için API bölümünü kullanın.

Sistem mimarisi (yüksek seviye)

Cere Insight 2.0 tipik olarak üç ana katmandan oluşur:

1. Web uygulaması (frontend)
   Next.js (App Router), React 19 kullanan tarayıcı arayüzü. Çoğu sayfa oturum açıldıktan sonra sol menü + üst çubuk + içerik alanı düzenindedir.

2. API sunucusu (backend)
   NestJS ile yazılmış REST API. Kimlik doğrulama, organizasyon kapsamı, abonelik limitleri ve iş mantığı burada çalışır. Veri erişimi Prisma üzerinden veritabanına gider.

3. Canlı mesajlaşma ve kuyruklar
   Müşteri görüşmeleri platformun yerleşik canlı mesajlaşma katmanı üzerinden yürür. Proje yanıtları ve test modu gibi işler için Redis üzerinde BullMQ kuyrukları kullanılır; böylece ağır veya uzun süren işler ana isteği bloke etmez.

Basit bir veri akışı:

flowchart LR
  subgraph client [Tarayıcı]
    UI[Next.js arayüzü]
  end
  subgraph api [Backend]
    REST[NestJS REST]
    Q[Redis / BullMQ]
  end
  subgraph channels [Kanallar ve yapay zekâ]
    LC[Canlı mesajlaşma]
    LLM[LLM sağlayıcıları]
  end
  UI -->|JWT + X-Organization-Id| REST
  REST --> Q
  REST --> LLM
  REST <-->|REST / webhook| LC

Süper yönetici farkı

SUPERADMIN platform genelinde org’ları ve mesajlaşma ortamı kayıtlarını yönetebilir; ancak proje CRUD işlemleri normal kullanıcılar gibi bir organizasyon bağlamı gerektirir — backend bu durumda erişimi özellikle reddeder. Günlük proje yapılandırması org üyeleri ile yapılır.

Temel kavramlar sözlüğü

Kavram	Kısa tanım
Organizasyon	Projelerin, bilgi tabanlarının ve faturalandırmanın toplandığı kiracı (tenant). Kullanıcılar bir veya daha fazla org’a üye olabilir.
Üyelik rolü	Org içinde ORG_ADMIN (yönetici) veya MEMBER (üye). Projeyi kimin oluşturabileceği gibi kuralların çoğu buna bağlıdır.
Hesap rolü	Kullanıcı kaydında USER veya SUPERADMIN. Süper yönetici sol menüde ek öğeler görür (ör. mesajlaşma ortamı instanceları).
Proje	Tek bir sohbet deneyiminin tanımı: sistem mesajı, LLM ayarları, tahta (board), ajanlar, araçlar ve entagrasyonlar.
Ajan (Agent)	Bir rol için çalışan LLM örneği; kendi system prompt ve model ayarları olabilir. Router ajanı akışı dallandırmak için kullanılabilir.
Araç (Tool)	Ajanın çağırabileceği yetenek: örneğin bilgi tabanı araması veya harici API uç noktası. Bazı araçlar proje düzeyinde tanımlanıp ajanlara bağlanır.
API entegrasyonu	Harici REST servisine bağlantı (base URL, kimlik bilgisi, varsayılan istek ayarları). Araçlar bu entegrasyonu kullanarak HTTP çağrısı yapar.
Bilgi tabanı	Belgelerin gömülü (embedding) arama ile sorgulanması; RAG senaryolarında ajan yanıtını kaynaklarla destekler.
Tahta (Board)	React Flow tarzı görsel düzenleyici: düğümler ve kenarlar ile “kim kimi çağırır” akışını modellemek için.
Gelen kutusu (Inbox)	Platformdaki mesaj hattı; web, e-posta, WhatsApp gibi kanallar buraya bağlanır ve projedeki ajan ile canlı ajanlara eşlenebilir.
Analitik ajan	SQL / Excel / sohbet ile pano oluşturma ve veriye soru sorma deneyimi; projelerden ayrı bir modüldür.
Orkestrasyon	Org bazlı iş akışları (workflow): olay tetikleme ve adımlar (abonelikte workflows özelliği ile sınırlı olabilir).
Raporlar	Canlı mesajlaşma ve canlı ajan operasyon verilerinden türetilen özetler; ayrıca kişi bazlı raporlar için /reports/users yolu vardır.

İstek ve oturum modeli (web → API)

Tarayıcıdan giden neredeyse her korumalı istekte iki başlık kritiktir:

• Authorization: Bearer <accessToken> — JWT; kim olduğunuzu belirler.
• X-Organization-Id: <uuid> — Hangi organizasyonun verisinde çalıştığınızı belirler. Çoklu org üyeliğinde organizasyon değiştirici bu değeri günceller.

Next.js middleware yalnızca çerezde access_token olup olmadığına bakarak sayfayı /login’e yönlendirir veya korumalı alana alır. Gerçek token kullanımında istemci hem çerez hem localStorage ile uyumluluk için token-storage katmanını kullanır (geliştirme ve alt alan SSO senaryoları için).

401 davranışı

Korumalı bir API uç noktası 401 döndürdüğünde axios interceptor token’ı temizler ve tarayıcıyı /login sayfasına yönlendirir; login / register / forgot-password uçları bu kuraldan muaf tutulur — böylece “yanlış şifre” ile oturumunuz silinmez.

Proje yaşam döngüsü (operasyonel bakış)

1. Org yöneticisi abonelik limitleri dahilinde yeni proje oluşturur (ORG_ADMIN + projects özelliği).
2. Ajanlar tanımlanır; gerekirse bir router ajanı akışı böler.
3. Entegrasyonlar ve proje araçları eklenir; bilgi tabanı araçları bilgi tabanı kaynağına bağlanır.
4. Tahta üzerinde düğümler yerleştirilir ve kenarlarla ilişki verilir.
5. Test modu ile mesaj gönderilip yanıt zinciri doğrulanır.
6. Canlı için gelen kutusu bağlanır, proje ve canlı ajan atamaları yapılır, widget veya kanal yayına alınır.

Her adımda limit veya özellik kontrolü başarısız olursa backend 403 / 402 veya anlamlı hata mesajı dönebilir; ayrıntılar için Abonelik ve Hata kodları.

Tahta üzerinde düğüm tipleri (ne zaman hangisi?)

Düğüm	Ne zaman kullanılır?
Router	Aynı girişi farklı uzman ajanlara yönlendirmek için; routing açıklaması ve öncelik alanları önemlidir.
Alt ajan	Görevi başka bir ajan bağlamına devretmek için.
Araç	LLM’in function-calling ile çağıracağı somut eylem (API, KB araması vb.).
Entegrasyon	Ortak bir dış servis tanımına referans; birden çok araç aynı entegrasyonu paylaşabilir.
Bilgi tabanı	RAG akışını tahta üzerinde görünür kılmak için.
Gelen kutu	Bu projeye bağlı platform gelen kutusunu göstermek için.

Analitik ve orkestrasyon: projeden farkı

• Projeler son kullanıcı sohbetinde ne söylenir sorusuna cevap verir.
• Analitik ajanlar iş verinize doğal dille soru sormanızı ve pano ile KPI üretmenizi sağlar (veri kaynakları, widget’lar).
• Orkestrasyon canlı mesajlaşma olayları gibi tetiklerle arka plan iş akışları çalıştırır; sohbet içeriğinden bağımsız otomasyon içindir.

Geliştirici için modül haritası (backend)

Aşağıdaki tablo, kaynak kodda hızlı gezinmek içindir; üretim API yolu ortamınıza göre önek içerebilir (/api/v1 gibi):

Nest modülü	Controller yolu (özet)	Sorumluluk
Auth	auth	Giriş, kayıt, JWT
User	users	Profil, org listesi
Organization	organizations	Üyeler, davet, org değiştirme
Subscription	subscriptions	Plan, limit, özellik bayrakları
Projects	projects	Project app, ajan, araç, tahta, inbox
Knowledge base	knowledgebases	Belgeler, embedding
Dashboard	dashboard	Ana sayfa özetleri, aktivite
Analytics	analytics	Pano, widget, analytics agent
Reports	reports	Konuşma ve gelen kutu özet metrikleri
Canlı mesajlaşma	(platform içi API)	Gelen kutular, kanal eşlemesi, müşteri iletişimi
Mesajlaşma ortamı	(süper yönetici)	Ortam tabanı ve kimlik bilgisi kayıtları
Orchestration	orchestration	Workflow CRUD ve tetikleme
AI autofill	ai	Form / alan doldurma yardımcıları
AI Builder	projects/:appId/builder	Doğal dille proje oturumu
Kanal olayları	(webhook girişleri)	Dış kanallardan gelen olayların işlenmesi

Ön uç (Next.js) sayfa haritası

Sol menüdeki öğeler Gerçek yollarla eşleşir:

Menü	Rota (örnek)
Ana sayfa	/
Projeler	/projects, detay /projects/[id]
Proje sohbet testi	/projects/[id]/chat
Bilgi tabanları	/knowledge-bases, detay /knowledge-bases/[id]
Analitik ajanlar	/analytic-agents, pano /analytic-agents/[dashboardId]
Orkestrasyon	/orchestration
Raporlar	/reports/overview, …, /reports/users
Organizasyon	/organizations
Abonelik	/subscription
Profil	/profile
Mesajlaşma ortamı instanceları	/chat-platform-instances (yalnızca süper yönetici)

Kimlik sayfaları (auth) altında /login, /register, /forgot-password olarak düzenlenmiştir; bu rotalarda ana uygulama kabuğu (sidebar) gösterilmez.

Güvenlik ve uyumluluk notları (özet)

• Token’ları tarayıcı konsolunda veya destek ekranında paylaşmayın.
• X-Organization-Id başlığını müşteri tarafı script’lerinizde org dışına taşınmayacak şekilde yönetin.
• Kişisel veri ve KVKK / GDPR yükümlülükleri, iletişim kanallarınız, iş ortaklarınız ve LLM sağlayıcılarınızın veri işleme sözleşmeleri ile birlikte değerlendirilmelidir — bu dokümantasyon hukuki danışmanlık yerine geçmez.

Sonraki adımlar

• Öğrenme yolu — sıralı okuma listesi
• Kimlik doğrulama — roller, çoklu org, Google OAuth
• Proje yönetimi — tahta ve test modu pratiği
• API kimlik doğrulama — entegrasyon için teknik detay