Appearance
Sistem Mimarisi (System Overview)
Bu doküman, Humindx platformunun yüksek seviye mimarisini (High-Level Design) ve genel sistem bileşenlerini açıklar.
Kapsam Uyarısı: Bu doküman, sistemin "kuş bakışı" görünümünü sunar. Detaylı olay akışları için
data-flow-diagrams.mddosyasına, veritabanı seviyesindeki izolasyon politikaları için isecontext-rooms-design.mddosyasına bakınız.
1. Mimari Felsefe
Humindx mimarisi üç temel prensip üzerine inşa edilmiştir:
- AI-First (Yapay Zeka Öncelikli): Yapay zeka, sisteme sonradan eklenen bir özellik (add-on) değil, temel veri toplama motorudur. Kullanıcı arayüzleri, statik formlar yerine LLM tabanlı ajanlarla gerçek zamanlı etkileşim (WebSockets) üzerine kuruludur. Ajanlar, bağlam zenginleştirme (RAG) ile kullanıcının geçmiş profilinden beslenir.
- Event-Driven Asynchrony (Olay Güdümlü Asenkron Yapı): Kullanıcı deneyimi ("Sohbet") ile Psikometrik Analiz ("Beyin") birbirini beklememelidir. Kullanıcı anında yanıt alırken, metnin analizi ve skorlanması arka planda asenkron olarak kuyruk mimarisi üzerinden yapılır.
- Privacy-by-Design (Tasarımdan Gelen Gizlilik): Veri hiçbir zaman monolitik bir havuza atılmaz. Bağlam Odaları (Context Rooms) mimarisi gereği, veriler doğdukları kaynağa göre fiziksel ve mantıksal olarak izole edilir.
2. Yüksek Seviye Sistem Tasarımı (C4 Model - Konteyner Görünümü)
Sistem, temel olarak "Sıcak Hat" (kullanıcı ile etkileşim) ve "Soğuk Hat" (psikometrik işleme ve arşivleme) olarak iki bağımsız akışa bölünmüştür.
Not: Diyagramdaki
B2B Tenant Engine, İşe Alım ve Yetenek Yönetimi modüllerini multi-tenant izolasyonla barındırır. İzolasyon detayları için bkz:../modules/b2b-tenant-os.md
3. Temel Bileşenler (Core Components)
3.1. API Gateway ve Kimlik Doğrulama
Tüm dış trafik API Gateway üzerinden geçer. JWT ve OAuth2 tabanlı yetkilendirme (Authorization) burada yapılır.
- Akıllı Gizlilik Sözleşmesi (Smart Privacy Contract) Uygulaması: Gateway, B2B paneli bir istek yaptığında kullanıcının güncel iznini (Level 1, 2 veya 3) kontrol eder. Eğer kullanıcı sadece Level 1 izni vermişse, B2B API yanıtından Level 2/3 verilerini (Yönetim Reçeteleri vb.) henüz motor (backend) seviyesindeyken strip eder (çıkarır).
3.2. B2C Chat Engine & LLM Orchestrator
- WebSocket (WSS) Sunucusu: Kullanıcı ile ajanın gerçek zamanlı konuşmasını sağlar.
- LLM Orchestrator: Sistemdeki ajanların (Gölge, Ayna, Mentor vb.) sistem prompt'larını yönetir, Retrieval-Augmented Generation (RAG) gerekiyorsa vektör veritabanından bağlamı çeker ve harici LLM servislerine yönlendirir.
3.3. Event Bus / Mesaj Kuyruğu (Kafka / RabbitMQ)
Etkileşim (Hot Path) ve Analiz (Cold Path) katmanlarını de-couple (birbirinden bağımsız) hale getiren omurgadır. LLM Orchestrator bir yanıt ürettiğinde, bu yanıtı doğrudan veritabanına yazmaz; CHAT_MESSAGE_PRODUCED veya SCENARIO_COMPLETED gibi bir olay (event) fırlatır.
3.4. Psikometrik Motor (Cold Path)
Mesaj kuyruğundan beslenen arka plan işleyicisidir.
- Scoring Engine: Ham metni veya LLM analizlerini alır, algoritmik çapraz doğrulama ile Big Five / RIASEC vb. sürekli spektrum (continuous spectrum) skorlarına çevirir.
- Vectorization & Privacy Firewall: Gelen ham metni vektörel özetlere (embeddings) dönüştürür.
[SOCIAL]etiketli bir olayın matematiksel etkisinin Profesyonel odaya sıçramaması için burada "Veri Sızdırmazlık" kuralları işletilir. - Confidence & Audit Engine: Her skor güncellemesini, kaynağı (kullanıcı müdahalesi mi, yapay zeka mı?) ile birlikte mühürler.
3.5. Veri Katmanı (Storage)
- RDBMS (PostgreSQL): Kullanıcı profilleri, izin ayarları ve Bağlam Odalarındaki skorlar tutulur. Row-Level Security (RLS) ile veri izolasyonu veri tabanı seviyesinde garanti edilir.
- Vector DB: Kullanıcı metinlerinin gürültü eklenmiş (noise-injected) vektörlerini depolar. Bağlamsal benzerlik aramaları ve "Kara Kutu" imhasından kurtulan kalıcı bellek burada yaşar.
- Immutable Log Store: Sistemin denetlenebilirliğini sağlayan (Audit Trail), silinemez veri soy ağacı (Data Lineage) depoları.
4. Asenkron İşleme Stratejisi (Neden?)
Bir LLM'den yanıt beklemek 1 ila 5 saniye sürebilir. Kullanıcının psikometrik analizi ise daha kompleks prompt zincirleri gerektirdiği için 10-15 saniyeyi bulabilir.
Eğer mimari senkron tasarlansaydı, kullanıcı her mesaj attığında analizin bitmesini beklemek zorunda kalacaktı. Event-Driven (Olay Güdümlü) yapı sayesinde:
- Kullanıcı mesajı atar → LLM yanıtlar → Ekran güncellenir (Hızlı döngü).
- Mesaj Event Bus'a düşer → Psikometrik motor veriyi işler → Sonraki adımda kullanıcının DNA sarmalı güncellenir (Yavaş/Derin döngü).
5. Önerilen Teknoloji Yığını (Tech Stack)
Sistemin ihtiyaç duyduğu gerçek zamanlı performans ve veri güvenliği gereksinimleri doğrultusunda belirlenmiş teknoloji yığını:
| Katman | Teknoloji / Araç | Gerekçe |
|---|---|---|
| Mobil (B2C) | React Native veya Flutter | Tek codebase ile iOS/Android, WebSocket desteği. |
| API / Hot Path | Node.js (NestJS) veya Go | WebSocket yönetimi ve yüksek eşzamanlı bağlantılar için optimal. |
| Psychometric Motor | Python (FastAPI / Celery) | Veri bilimi, LangChain/LlamaIndex kullanımı ve scoring algoritmaları için ekosistem avantajı. |
| Database | PostgreSQL (RLS aktif) | Bağlam Odaları izolasyonu için güçlü şema ve rol yönetimi. |
| Vector Search | pgvector (PostgreSQL eklentisi) | Başlangıç aşamasında ayrı bir DB kurmadan RDBMS ile vektör tutarlılığını sağlamak için.* |
| Event Bus | Apache Kafka veya Redis Streams | Kayıpsız asenkron veri iletimi (Event replay yeteneği). |
Bu karar (pgvector seçimi) ileride Pinecone/Weaviate geçiş referansı olması için
guides/architecture-decisions/altında bir ADR olarak kayıt altına alınacaktır.
Son Güncelleme: 2026-04-15 — High-Level mimari, C4 modeli, Tech Stack (Mobil dahil) ve asenkron yapı tanımlandı.