Upload 2 files

flare-tasarim.md

@@ -1,512 +1,444 @@
-# 🏗 Genel Mimari
+# Flare Platform - Güncel Tasarım Dokümanı
 
-Flare, Spark LLM motorunun üstünde çalışan, çok adımlı ve akıllı bir orchestration katmanıdır. Görevleri:
+## 🏗 Genel Mimari
 
-✅ Kullanıcıdan gelen mesajları Spark kullanarak sohbet halinde sürdürmek,
-✅ Spark ile, kullanıcı mesajından intent ve parametre extraction akışını yönetmek,
-✅ Eksik parametre değerleri için system prompt oluşturup, Spark ile insani mesaja dönüştürerek bu parametrelerin değerlerini kullanıcıya tamamlatmak,
-✅ Doğru parameter değerleri ile API çağrıları yapmak,
-✅ API cevabını Spark üzerinden insanileştirilmiş metne dönüştürmek ve kullanıcıya iletmek,
-✅ Her şeyi session bazında, state machine mantığında takip etmek.
-✅ TTS (Text-to-Speech) desteği ile bot yanıtlarını sesli olarak sunmak.
-✅ STT (Speech-to-Text) desteği ile kullanıcıdan sesli girdi almak (gelecek özellik).
+Flare, modüler LLM provider desteği ile çalışan çok adımlı ve akıllı bir orchestration katmanıdır. Provider-agnostic tasarımı sayesinde farklı LLM, TTS ve STT motorları ile çalışabilir.
 
-Bu yapı Parloa gibi sistemlerde kullanılan "flow engine + LLM + tool orchestration" yaklaşımına dayanır.
+### Temel Özellikler
+- ✅ Provider-based mimari (LLM, TTS, STT)
+- ✅ Intent detection ve parameter extraction
+- ✅ Akıllı parametre toplama (smart grouping)
+- ✅ Onay mekanizması (requiresApproval)
+- ✅ Multi-language destek (LocalizedExample, LocalizedCaption)
+- ✅ Session-based state machine
+- ✅ API orchestration ve response mapping
+- ✅ Activity logging ve audit trail
 
-# LLM Provider Abstraction
+## 📋 Konfigürasyon Yapısı
 
-Flare, farklı LLM provider'larını desteklemek için abstraction layer kullanır. Desteklenen provider'lar:
+### service_config.jsonc - Ana Yapı
+```json
+{
+  "config": {
+    // Provider tanımları
+    "llm_provider": {
+      "name": "spark|gpt4o|gpt4o-mini",
+      "api_key": "enc:...",  // Şifrelenmiş
+      "endpoint": "https://...",
+      "settings": {
+        "internal_prompt": "Global LLM yönergesi",
+        "parameter_collection_config": {
+          "max_params_per_question": 2,
+          "smart_grouping": true,
+          "retry_unanswered": true,
+          "collection_prompt": "..."
+        }
+      }
+    },
+    "tts_provider": {
+      "name": "no_tts|elevenlabs|blaze",
+      "api_key": "enc:...",
+      "endpoint": null,
+      "settings": {}
+    },
+    "stt_provider": {
+      "name": "no_stt|google|azure|flicker",
+      "api_key": "/path/to/credentials.json",
+      "endpoint": null,
+      "settings": {
+        "language": "tr-TR",
+        "model": "latest_long"
+      }
+    },
+    "providers": [
+      // Kullanılabilir provider tanımları
+    ],
+    "users": [...]
+  },
+  "projects": [...],
+  "apis": [...],
+  "activity_log": [...],
+  "project_id_counter": 1,
+  "last_update_date": null,
+  "last_update_user": null
+}
+```
 
-- **Spark (HuggingFace)**: On-premise ve HuggingFace cloud deployment'lar için
-- **GPT-4o (OpenAI)**: OpenAI API üzerinden GPT-4o modeli kullanımı için
-- **GPT-4o-mini (OpenAI)**: Düşük maliyetli alternatif için GPT-4o-mini modeli
+### Provider Sistemi
 
-Work mode'a göre (`hfcloud`, `cloud`, `on-premise`, `gpt4o`, `gpt4o-mini`) uygun LLM provider seçilir ve tüm LLM çağrıları bu abstraction üzerinden yapılır. Bu sayede farklı LLM'ler aynı intent detection, parameter extraction ve response generation mantığıyla çalışabilir.
+#### Provider Config
+```json
+{
+  "type": "llm|tts|stt",
+  "name": "spark",
+  "display_name": "Spark LLM",
+  "requires_endpoint": true,
+  "requires_api_key": true,
+  "requires_repo_info": false,
+  "description": "YTU Cosmos Spark LLM"
+}
+```
 
-# Spark Entegrasyonu
+#### Provider Settings
+```json
+{
+  "name": "provider_name",
+  "api_key": "enc:encrypted_key",
+  "endpoint": "https://endpoint",
+  "settings": {
+    // Provider-specific ayarlar
+  }
+}
+```
 
-Spark servisinin base url'i service_config.jsonc dosyasında config.spark_endpoint olarak tanımlanmıştır.
+### Project Yapısı
+```json
+{
+  "id": 1,
+  "name": "project_name",
+  "caption": "Proje Başlığı",
+  "icon": "folder",
+  "description": "Açıklama",
+  "enabled": true,
+  "default_locale": "tr",
+  "supported_locales": ["tr", "en"],
+  "timezone": "Europe/Istanbul",
+  "region": "tr-TR",
+  "versions": [...],
+  "version_id_counter": 1,
+  "deleted": false,
+  "created_date": "2024-01-01T00:00:00Z",
+  "created_by": "username",
+  "last_update_date": null,
+  "last_update_user": null
+}
+```
 
-Spark'a gönderilecek tüm request'lerde header'a Authorization: Bearer <SPARK_TOKEN> eklenmelidir. SPARK_TOKEN, .env dosyasında tanımlıdır.
+### Version Yapısı
+```json
+{
+  "id": 1,
+  "no": 1,
+  "caption": "v1",
+  "description": "Version açıklaması",
+  "published": true,
+  "deleted": false,
+  "general_prompt": "Asistan için genel yönerge",
+  "welcome_prompt": "Hoşgeldin mesajı yönergesi",
+  "llm": {
+    "repo_id": "model-id",
+    "generation_config": {},
+    "use_fine_tune": false,
+    "fine_tune_zip": ""
+  },
+  "intents": [...],
+  "created_date": "2024-01-01T00:00:00Z",
+  "created_by": "username",
+  "publish_date": null,
+  "published_by": null
+}
+```
+
+### Intent Yapısı
+```json
+{
+  "name": "intent_name",
+  "caption": "Intent Başlığı",
+  "requiresApproval": false,
+  "dependencies": [],
+  "examples": [
+    {
+      "locale_code": "tr",
+      "example": "Örnek cümle"
+    }
+  ],
+  "detection_prompt": "Intent algılama yönergesi",
+  "parameters": [...],
+  "action": "api_name",
+  "fallback_timeout_prompt": "Zaman aşımı mesajı",
+  "fallback_error_prompt": "Hata mesajı"
+}
+```
 
-# GPT-4o Entegrasyonu
+### Parameter Yapısı
+```json
+{
+  "name": "param_name",
+  "caption": [
+    {
+      "locale_code": "tr",
+      "caption": "Parametre Başlığı"
+    }
+  ],
+  "type": "str|int|float|bool|date",
+  "required": true,
+  "variable_name": "variable_name",
+  "extraction_prompt": "Parametre çıkarma yönergesi",
+  "validation_regex": "^pattern$",
+  "invalid_prompt": "Geçersiz değer mesajı",
+  "type_error_prompt": "Tip hatası mesajı"
+}
+```
+
+### API Yapısı
+```json
+{
+  "name": "api_name",
+  "description": "{{variables.x}} için işlem açıklaması",
+  "url": "https://api-endpoint",
+  "method": "GET|POST|PUT|DELETE",
+  "headers": "{}",  // JSON string
+  "body_template": "{}",  // JSON string
+  "timeout_seconds": 10,
+  "retry": {
+    "max_attempts": 3,
+    "backoff_seconds": 2,
+    "strategy": "static|exponential"
+  },
+  "auth": {
+    "enabled": true,
+    "token_endpoint": "https://auth-endpoint",
+    "response_token_path": "access_token",
+    "token_request_body": "{}",
+    "token_refresh_endpoint": null,
+    "token_refresh_body": "{}"
+  },
+  "response_mappings": [
+    {
+      "variable_name": "result",
+      "caption": "Sonuç",
+      "type": "str",
+      "json_path": "$.data.result"
+    }
+  ],
+  "response_prompt": "Response insanileştirme yönergesi",
+  "deleted": false,
+  "created_date": "2024-01-01T00:00:00Z",
+  "created_by": "username"
+}
+```
 
-Work mode `gpt4o` veya `gpt4o-mini` seçildiğinde, Spark yerine OpenAI API kullanılır. OpenAI API key, config.cloud_token alanında şifrelenmiş olarak saklanır (mevcut encryption_utils kullanılarak).
+## 🔄 Session ve State Yönetimi
 
-GPT-4o için özel konfigürasyonlar:
-- Model seçimi: gpt-4o veya gpt-4o-mini
-- Temperature: 0-2 arası (varsayılan 0.3)
-- Max tokens: Response uzunluğu limiti
-- System prompt ve conversation history OpenAI format'ına dönüştürülür
+### Session Özellikleri
+```python
+class Session:
+    session_id: str
+    project_name: str
+    version_number: int
+    version_config: VersionConfig
+    
+    # State machine
+    state: str  # idle | await_param | call_api | humanize
+    last_intent: str | None
+    awaiting_parameters: List[str]
+    missing_ask_count: int
+    
+    # Data storage
+    variables: Dict[str, str]
+    auth_tokens: Dict[str, Dict]
+    chat_history: List[Dict[str, str]]
+    
+    # Smart parameter tracking
+    asked_parameters: Dict[str, int]
+    unanswered_parameters: List[str]
+    parameter_ask_rounds: int
+    
+    # Real-time support
+    is_realtime_session: bool
+    active_websocket: Any
+```
 
-**Maliyet Optimizasyonu**: 
-- gpt-4o: ~$0.01-0.03 per konuşma
-- gpt-4o-mini: ~$0.001-0.003 per konuşma (10x daha ucuz)
+### State Machine Flow
+```
+start_session → welcome_prompt
+     ↓
+    idle ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←
+     ↓                                             ↑
+detect_intent → collect_params → approval? → call_api → humanize
+                      ↑              ↓
+                      ← await_param ←
+```
 
-# TTS/STT Entegrasyonu
+## 🔐 Onay Mekanizması
 
-Flare, sesli etkileşim için TTS (Text-to-Speech) ve STT (Speech-to-Text) motorlarını destekler:
+Intent'te `requiresApproval: true` olduğunda:
 
-## TTS (Text-to-Speech)
-Desteklenen motorlar:
-- **ElevenLabs**: Yüksek kaliteli, çok dilli TTS desteği
-- **Blaze**: Alternatif TTS motoru (yakında)
-- **No TTS**: TTS devre dışı
+1. **Otomatik parametre ekleme**: `is_approved` parametresi dinamik olarak eklenir
+2. **Onay sorusu oluşturma**: API description'daki placeholder'lar değiştirilir
+3. **Onay kontrolü**: 
+   - Onay verilirse → API çağrısı
+   - Onay verilmezse → İşlem iptali
 
-TTS Konfigürasyonu service_config.jsonc içinde:
-- `tts_engine`: Kullanılacak motor ("no_tts", "elevenlabs", "blaze")
-- `tts_engine_api_key`: Motor API anahtarı (şifrelenmiş)
+## 🌍 Multi-Language Destek
 
-## STT (Speech-to-Text)
-Desteklenen motorlar:
-- **ElevenLabs**: Sesli girdi desteği
-- **Flicker**: Alternatif STT motoru (yakında)
-- **No STT**: STT devre dışı
+### Locale Yönetimi
+- Project seviyesinde `default_locale` ve `supported_locales`
+- LocalizedExample ve LocalizedCaption yapıları
+- Locale JSON dosyaları (`tr.json`, `en.json`, vb.)
 
-STT Konfigürasyonu:
-- `stt_engine`: Kullanılacak motor
-- `stt_engine_api_key`: Motor API anahtarı (şifrelenmiş)
+### LocaleManager
+```python
+# Locale bilgilerini yönetir
+LocaleManager.get_locale("tr")
+LocaleManager.format_date(date, "tr")
+LocaleManager.parse_date_expression("yarın", "tr")
+LocaleManager.format_number(1234.56, "tr")
+```
 
-## Chat'te TTS Kullanımı
-1. Chat başlatılırken "Use TTS" seçeneği işaretlenebilir
-2. Bot yanıtları otomatik olarak TTS ile seslendirilebilir
-3. Her mesaj için ayrı ses dosyası üretilir ve oynatılabilir
-4. Ses oynatma sırasında waveform visualizasyon gösterilir
+## 🎤 TTS/STT Entegrasyonu
+
+### TTS Providers
+- **ElevenLabs**: Yüksek kaliteli, çok dilli
+- **Blaze**: Alternatif TTS
+- **No TTS**: Devre dışı
+
+### STT Providers
+- **Google**: Cloud Speech-to-Text
+- **Azure**: Azure Speech Services
+- **Flicker**: Alternatif STT
+- **No STT**: Devre dışı
+
+### Real-time Features
+- WebSocket-based audio streaming
+- Voice Activity Detection (VAD)
+- Noise reduction
+- Interim results
+
+## 🚀 LLM Provider Desteği
+
+### Spark
+- YTU Cosmos modelleri
+- HuggingFace Cloud veya on-premise
+- Custom fine-tuning desteği
+
+### GPT-4o / GPT-4o-mini
+- OpenAI API entegrasyonu
+- Temperature ve max_tokens kontrolü
+- Maliyet optimizasyonu
+
+### Provider Seçimi
+```python
+# chat_handler.py
+if llm_provider.name == "spark":
+    llm = SparkLLM(endpoint, token)
+elif llm_provider.name.startswith("gpt4o"):
+    llm = GPT4oLLM(api_key, model)
+```
 
-# Internal Prompt Mekanizması
+## 📡 API Yönetimi
+
+### API Çağrı Süreci
+1. **Variable substitution**: `{{variables.xxx}}` → gerçek değerler
+2. **Auth token yönetimi**: Otomatik token alma ve yenileme
+3. **Retry logic**: Configurable retry stratejisi
+4. **Response mapping**: JSON path ile veri çıkarma
+5. **Response humanization**: LLM ile insanileştirme
+
+### Auth Mekanizması
+```python
+# Token alma ve cache'leme
+if api.auth.enabled:
+    token = get_or_refresh_token(api, session)
+    headers["Authorization"] = f"Bearer {token}"
+```
 
-Flare servisi, tüm LLM isteklerinde kullanılmak üzere merkezi bir internal_prompt tanımına sahiptir. Bu prompt, service_config.jsonc dosyasında config.internal_prompt olarak saklanır ve her intent detection işleminde project version'daki general_prompt'un başına otomatik olarak eklenir.
+## 🔒 Güvenlik
 
-Internal prompt, LLM'in tutarlı davranış sergilemesi için gerekli temel kuralları içerir:
-- Intent detection formatı ve kuralları  
-- Dil ayarları (<project language> placeholder'ı ile)
-- Intent isimleri ve caption'ları (<intent names> ve <intent captions> placeholder'ları ile)
-- Selamlama ve small talk davranışları
-- Güvenlik kuralları
+### Encryption
+- API key'ler `enc:` prefix ile şifrelenmiş saklanır
+- Fernet encryption (symmetric)
+- Environment variable: `FERNET_KEY`
 
-Bu mekanizma sayesinde tüm projeler arasında ve farklı LLM provider'ları arasında tutarlı bir davranış sağlanır. Internal prompt içindeki placeholder'lar runtime'da gerçek değerlerle değiştirilir:
-- <intent names>: Proje versiyonu içinde tanımlı intentlerin name'leri, tırnak içinde ve virgülle ayrılmış şekilde
-- <intent captions>: Proje versiyonu içinde tanımlı intentlerin caption'ları, tırnak içinde ve virgülle ayrılmış şekilde  
-- <project language>: Projenin default_language alanından alınan dil (Turkish, English, German, vb.)
+### Authentication
+- JWT-based session yönetimi
+- Bcrypt password hashing
+- Session timeout kontrolü
 
-# Startup
+### Race Condition Koruması
+- `last_update_date` ile optimistic locking
+- Thread-safe session store
+- Concurrent update kontrolü
 
-Flare servisi ayağa kalktıktan sonra ilk iş olarak service_config.jsonc dosyasında tanımlı enabled=true olan her bir project için, projenin published=true olan en büyük id'ye sahip versiyonundaki bilgilerle startup işlemi yapar:
+## 📊 Monitoring ve Logging
 
-**Spark Mode (hfcloud, cloud, on-premise)**:
-Spark servisine /startup request'i gönderir:
+### Activity Log
 ```json
 {
-  "work_mode": "<config.work_mode>",
-  "cloud_token": "<config.cloud_token>",
-  "project_name": "<project.name>",
-  "project_version": <project.version.id>,
-  "repo_id": "<project.version.llm.repo_id>",
-  "generation_config": <project.version.llm.generation_config>,
-  "use_fine_tune": <project.version.llm.use_fine_tune>,
-  "fine_tune_zip": "<project.version.llm.fine_tune_zip>"
+  "timestamp": "2024-01-01T00:00:00Z",
+  "username": "admin",
+  "action": "CREATE_PROJECT",
+  "entity_type": "project",
+  "entity_id": 1,
+  "entity_name": "project_name",
+  "details": "Additional info"
 }
 ```
 
-**GPT-4o Mode**:
-OpenAI API key'in geçerliliği kontrol edilir. Ek startup işlemi gerekmez.
+### Log Actions
+- Project CRUD: CREATE, UPDATE, DELETE, ENABLE, DISABLE
+- Version: CREATE, UPDATE, PUBLISH, DELETE
+- API: CREATE, UPDATE, DELETE
+- Environment: UPDATE_ENVIRONMENT
+- Import/Export: IMPORT_PROJECT, EXPORT_PROJECT
 
-# Chat
+## 🧪 Test ve Development
 
-Chat request'leri work_mode'a göre ilgili LLM provider'a yönlendirilir:
+### Mock Backend
+- Scenario-based testing
+- Configurable responses
+- Error simulation
 
-**Spark için** /generate endpoint'ine:
-```json
-{
-  "project_name": "project1",
-  "system_prompt": "you are an helpful virtual assistant...",
-  "user_input": "en ekşi meyve nedir?",
-  "context": [
-    { "role": "user", "content": "Merhaba!" },
-    { "role": "assistant", "content": "Merhaba, nasıl yardımcı olabilirim?" }
-  ]
-}
-```
+### Debug Features
+- Detailed timestamped logging
+- Request/Response tracking
+- Performance metrics
+
+## 🔄 Import/Export
 
-**GPT-4o için** OpenAI Chat Completion API'ye uygun formatta:
+### Project Export Format
 ```json
 {
-  "model": "gpt-4o",
-  "messages": [
-    { "role": "system", "content": "you are an helpful virtual assistant..." },
-    { "role": "user", "content": "Merhaba!" },
-    { "role": "assistant", "content": "Merhaba, nasıl yardımcı olabilirim?" },
-    { "role": "user", "content": "en ekşi meyve nedir?" }
-  ],
-  "temperature": 0.3,
-  "max_tokens": 512
+  "name": "project_name",
+  "caption": "Project Caption",
+  "icon": "folder",
+  "description": "Description",
+  "default_locale": "tr",
+  "supported_locales": ["tr", "en"],
+  "versions": [
+    {
+      "caption": "v1",
+      "general_prompt": "...",
+      "llm": {...},
+      "intents": [...]
+    }
+  ]
 }
 ```
 
-# 🧠 İş Akışı
-
-İş akışı tüm LLM provider'lar için aynıdır:
-
-1. Sohbet için bir session ve state takibi yapılacağından, Flare'e öncelikle, request body'de project_name bilgisi içeren bir /start_session request'i gönderilir.
-2. Flare unique bir session_id üretir ve bir session objesi yaratıp, session_id üzerinden indekslenmiş olan session dictionary'sine ekler ve response'ta session_id değerini döndürür. Session objesi içinde, gönderilen project_name'e karşılık gelen proje bilgileri (id, name, caption) ve proje tanımı altındaki versions array'indeki published=true olan version'lardan en büyük id'ye sahip olanın altındaki bilgileri (llm nesnesi hariç) alıp session nesnesine set eder. Oluşturduğu session'ın işleyişinde bundan sonra bu bilgileri kullanır.
-3. Session nesnesi içinde ayrıca sohbetin context'ini takip edeceği chat_history array'i ve intent tespit etmesi durumunda, tespit ettiği intent, extract edilen parametreler ve eksik parametreleri takip edeceği property'ler, session state gibi sohbet akışında ihtiyaç duyacağı bilgileri tutar.
-4. Ardından Flare'e bu session ile gönderilen tüm request'lerin header'ında X-Session-ID key içinde session_id değeri gönderilir.
-5. Flare, kendisine gelen /chat request'lerini işletirken header'daki X-Session-ID değerini alır (yoksa hata döndürür) ve gönderilen session_id ile session dictionary'sinden ilgili session nesnesini bulur, sohbeti işletmek için session nesnesindeki değerleri kullanır.
-6. Sohbet sırasında user_input bilgisi, session_id header'ıyla Flare'in /chat endpoint'ine gönderilir.
-
-## 1️⃣ Intent Detection
-1. Kullanıcı mesajı alınır.
-2. LLM'e, kullanıcı mesajı, session'da tutulan sohbet tarihçesi ve session'da tutulan project version nesnesindeki intent tanımları birleştirilerek (detection_prompt ve intent detection'ı kolaylaştırma amaçlı örnek cümleler içeren examples kısmı) bir system prompt halinde gönderilir.
-3. Eğer kullanıcının söyledikleri bir intent içermiyorsa, LLM kullanıcıyla normal sohbet eder.
-4. LLM eğer intent belirlerse, parametreleri bu aşamada extract etmez. Bulduğu intent'in adını özel bir formatta döndürür. Örnek: `#DETECTED_INTENT:search_flight_intent`
-
-## 2️⃣ Parametre Extraction
-1. Belirlenen intent'e göre beklenen parametre listesi çıkarılır.
-2. LLM'e, user_input ile birlikte parametre extraction_prompt'ları birleştirilip tek bir system prompt olarak gönderilir. LLM buradan parametre değerlerini extract eder ve özel bir formatta döndürür. Örnek:
-   `#PARAMETERS:{ "extracted": [ { "to_city": "İstanbul" } ], "missing": [ "to_city", "date"] }`
-3. Döndürülen parametreler tanımdaki variable_name key'i ile session'a eklenir. Eğer birden fazla intent'te aynı variable_name'e sahip parametreler varsa, aynı değişken değerini paylaşırlar.
-
-## 3️⃣ Eksik Parametre Tamamlama
-1. Zorunlu parametrelerden eksik olanlar varsa, Flare bunları kullanıcıdan istemek için uygun prompt'u hazırlar ve LLM'e gönderir. Bunun için, eksik parametrelerin tanımlarındaki name ve intent.parameters.extraction_prompt'lar birleştirilerek tek bir system prompt haline getirilir.
-2. LLM, kullanıcı cevabını işleyip tekrar extraction yapar ve yukarıdaki #PARAMETERS formatında Flare'e dönüş yapar. Eksik parametre değeri kalmayan kadar Flare-LLM iletişimi bu şekilde döner.
-3. Sohbette bir intent tespit edildiğinde, bu intent'in zorunlu bir parametresinin variable_name'i session'da zaten mevcutsa ve değer içeriyorsa, bu parametre tekrar extract edilmeye çalışılmaz, session'daki ilgili variable'dan alınıp kullanılır.
-
-## 4️⃣ Parametre Validation
-1. Alınan her parameter değeri, parameter tanımındaki tip ve regex (min/max uzunluk gibi) kurallarla doğrulanır.
-2. Hatalı değerler varsa, bu parametrelerin invalid_prompt'ları birleştirilip LLM'e tek bir system prompt olarak gönderilir ve LLM kullanıcıya doğrudan döndürülecek insani hata mesajını oluşturup döndürür. Örnek: "Söylediğiniz uçuş numarası hatalı. Uçuş numaranız 6 haneli bir numara olmalıdır."
-
-## 5️⃣ API Çağrısı
-Tüm parametreler tamamlanınca Flare, intent'e bağlı API çağrısını yapar.
-Intent'e bağlı API adı, service_config.json'da ilgili intent nesnesinin action alanında tanımlıdır. Bu adı kullanarak apis altındaki ilgili api tanımına ulaşılabilir.
-
-Bu aşamada kritik bir detay:
-
-🔑 **Eğer API tanımında auth bölümü varsa:**
-- Api çağırılmadan önce, session içinde auth_tokens[api_name] var mı control edilir. Varsa bu token kullanılır.
-- Eğer yoksa, token alma işlemi yapılır.
-- Token almak için, token_endpoint ve body_template kullanılarak token api servisine request gönderilir, dönen json response içinden response_token_path json path'i kullanılarak token değeri alınır.
-- Alınan token session içinde auth_tokens[api_name] olarak saklanır.
-- Token expire ederse, token_refresh_endpoint ve token_refresh_body kullanılarak mevcut token refresh edilir.
-- Header ve body'lerdeki {auth_tokens.api_name.token} placeholder'ları bu token ile doldurulur.
-
-Eğer auth tanımı yoksa, API çağrısı doğrudan yapılır.
-Bu mekanizma API erişiminde güvenlik ve süreklilik sağlar.
-
-## 6️⃣ Response Mapping
-API'den dönen JSON response'tan belirli değerleri session değişkenlerine aktarma mekanizmasıdır. Her API tanımında response_mappings array'i ile tanımlanır:
-```json
-"response_mappings": [
-  {
-    "variable_name": "booking_id",
-    "type": "str",
-    "json_path": "booking.confirmation_number"
-  },
-  {
-    "variable_name": "departure_time", 
-    "type": "date",
-    "json_path": "flight_details.departure.time"
-  }
-]
+## 🚦 Production Deployment
+
+### Docker Support
+- HuggingFace Spaces uyumlu
+- Health check endpoint
+- Environment-based configuration
+- Volume mount için permission handling
+
+### Environment Variables
+```bash
+FERNET_KEY=...           # Encryption key
+SPARK_TOKEN=...          # Spark API token
+OPENAI_API_KEY=...       # GPT-4o key
+GOOGLE_APPLICATION_CREDENTIALS=... # STT credentials
+HF_HOME=/app/.cache      # HuggingFace cache
 ```
-Bu mapping'ler API başarılı response döndüğünde (status 200) otomatik olarak işlenir. Belirtilen json_path'teki değerler, tanımlanan type'a göre dönüştürülüp session.variables içine variable_name ile kaydedilir.
-
-Desteklenen type'lar: str, int, float, bool, date
-
-Bu mekanizma sayesinde API response'larından alınan değerler, sonraki intent'lerde veya API çağrılarında kullanılabilir hale gelir.
-
-## 7️⃣ API Cevabını İnsanileştirme
-Api'den dönen ham json, api tanımı altındaki response_prompt ile birlikte LLM'e gönderilir ve akıcı, insani bir cevap üretilir.
-
-Not: Api tanımındaki response_prompt içindeki {{api_response}} değeri, api'den dönen json string ile replace edilir.
-
-Örnek: `"response_prompt": "Aşağıdaki JSON döviz kuru bilgilerini içeriyor. Kullanıcıya anlaşılır bir Türkçe özet hazırla:\n\n{{api_response}}"`
-
-## 8️⃣ Session ve State Takibi
-Her kullanıcı sohbeti bir session ID ile takip edilir.
-Session üzerinde:
-- Son 10 adet konuşma tarihçesi,
-- Son intent,
-- Toplanan parametreler,
-- Eksik parametreler,
-- Akışın neresinde olduğumuz (intent detection, parameter extraction, api call, response humanization)
-- Api token'ları
-
-tutulur. Bu, çok adımlı akışlarda state kaybını engeller.
-
-# Date Type Desteği
-
-Parametre tanımlarında "date" type'ı desteklenmektedir. Date parametreleri:
-- ISO format (YYYY-MM-DD) olarak saklanır
-- Türkçe tarih ifadeleri otomatik olarak parse edilir (bugün, yarın, 15 Temmuz, vb.)
-- Extraction prompt'larında güncel tarih context'i sağlanır
-- Validation sırasında geçerli tarih formatı kontrolü yapılır
-
-# 🏗 Mimari Bileşenler
-
-| Bileşen | Görev |
-|---------|-------|
-| LLM Interface | Farklı LLM provider'larını abstract eden katman |
-| Spark LLM | HuggingFace Spark servisi ile iletişim |
-| GPT-4o LLM | OpenAI API ile iletişim |
-| TTS Interface | Farklı TTS provider'larını abstract eden katman |
-| ElevenLabs TTS | ElevenLabs TTS servisi ile iletişim |
-| Flare Session Manager | Her kullanıcı için session ve state takibi |
-| Flare Prompt Engine | Her aşamada LLM'e gönderilecek uygun system prompt'u dinamik hazırlayan yapı |
-| API Connector | Tanımlı API'lere parametrelerle çağrı yapan, auth/refresh yöneten katman |
-| Validation Engine | Parametre değerlerini tip ve format bazlı doğrulayan yapı |
-| UI ve Config Katmanı | Flare işleyiş konfigürasyonu ve api tanımları; version bazlı project tanımlamaları; project tanımı altında intent tanımları; intent tanımı altında parametre tanımlarını yöneten arayüz |
-
-# 📋 Yapılacaklar
-
-✅ LLM abstraction layer geliştirilmesi
-✅ Spark ile intent tespiti için system prompt tasarımı → Örnek cümlelerle zenginleştirme
-✅ GPT-4o için prompt optimization
-✅ Parametre extraction için intent bazlı prompt şablonları hazırlanması
-✅ Eksik parametre tamamlama için eksik parametre bazlı prompt oluşturma
-✅ Parametre tip tanımları ve validation engine geliştirilmesi
-✅ API connector modülü → auth, refresh, token yönetimi, timeout, retry mantığı ile geliştirme
-✅ Humanization prompt'larının API cevabına göre dinamik hazırlanması
-✅ Session ve state machine geliştirme
-✅ Response mapping mekanizması
-✅ Internal prompt sistemi
-✅ Date type desteği
-✅ Multi-provider support
-✅ TTS (Text-to-Speech) entegrasyonu
-✅ ElevenLabs TTS provider
-⏳ STT (Speech-to-Text) entegrasyonu
-⏳ Blaze TTS provider
-⏳ Flicker STT provider
-
-# 🔑 Önemli Notlar (Unutulmaması Gerekenler)
-
-1. LLM prompt'ları tek seferde şişirilmemeli; sohbetin her aşamasında sadece gereken system prompt dinamik oluşturulup gönderilmeli.
-2. Parametre extraction'da ek bir model (BERT vb.) yerine sadece seçilen LLM kullanılacak.
-3. Intent başına (proje başına max ~8-10 intent), her bir intent için max ~5-6 örnek cümle şeklinde bir kapasite planlaması düşünülebilir.
-4. Parametre tip ve regex validation başarısızsa, LLM üzerinden insani bir hata mesajı oluşturulup kullanıcıya döndürülmeli.
-5. API response'larının insanileştirilmesi, kullanıcıya daha iyi bir deneyim sunmak için LLM'den geçmeli.
-6. API token yönetimi ve refresh mekanizması, Flare içinde güvenli ve izlenebilir şekilde tutulmalı.
-7. GPT-4o kullanımında token maliyetleri göz önünde bulundurulmalı, conversation history sınırlandırılmalı.
-8. Farklı LLM'lerin response formatları normalize edilmeli (#DETECTED_INTENT ve #PARAMETERS formatları korunmalı).
-9. TTS kullanımında API key güvenliği ve maliyet kontrolü sağlanmalı.
-10. Tüm API key'ler (OpenAI, ElevenLabs, vb.) şifrelenmiş olarak saklanmalı.
-
-# Servis Konfigürasyonu
-
-Flare'in tanımlarını tutan bir document database gibi kullanacağımız service_config.jsonc dosyasının yapısı, örnek data ve alan açıklamaları ile birlikte aşağıdadır.
-
-```jsonc
-{
-  // =====================================================
-  // FLARE GLOBAL CONFIGURATION
-  // =====================================================
-  "config": {
-    "work_mode": "hfcloud", // "hfcloud" | "cloud" | "on-premise" | "gpt4o" | "gpt4o-mini"
-    "cloud_token": "<your cloud token or OpenAI API key>", // work_mode'a göre Spark token veya OpenAI API key (şifrelenmiş)
-    "spark_endpoint": "https://ucsturkey-spark.hf.space", // Spark servisi URL (GPT mode'da kullanılmaz)
-    "internal_prompt": "⚠️ **NEVER output \"#DETECTED_INTENT:\"...", // Merkezi LLM kuralları
-    "project_id_counter": 1, // Yeni proje ID'leri için counter
-    "last_update_date": "2025-06-08T12:00:00.000Z", // Race condition kontrolü için
-    "last_update_user": "admin",
-    
-    // === TTS/STT Configuration ==============
-    "tts_engine": "no_tts", // "no_tts" | "elevenlabs" | "blaze"
-    "tts_engine_api_key": "enc:...", // Şifrelenmiş TTS API key
-    "stt_engine": "no_stt", // "no_stt" | "elevenlabs" | "flicker"
-    "stt_engine_api_key": "enc:...", // Şifrelenmiş STT API key
-    
-    // === Login Users (bcrypt hash + salt): Flare UI kullanılabilecek user'lar ==============
-    "users": [
-      {
-        "username": "admin",
-        "password_hash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918",
-        "salt": "random_salt_string"
-      }
-    ]
-  },
 
-  // =====================================================
-  // PROJECTS: Her bir proje bir virtual agent'ı tanımlar
-  // =====================================================
-  "projects": [
-    {
-      "id": 1,
-      "name": "coronos_assistant", // Virtual agent adı
-      "caption": "Coronos Sanal Asistan",
-      "icon": "folder", // Material icon adı
-      "description": "Coronos müşteri hizmetleri asistanı", // Proje açıklaması
-      "enabled": true, // Kullanımda olma durumu
-      "default_language": "tr", // Varsayılan dil kodu
-      "supported_languages": ["tr", "en"], // Desteklenen diller
-      "timezone": "Europe/Istanbul", // Saat dilimi
-      "region": "tr-TR", // Bölge kodu
-      "last_version_number": 1, // Projelerin version_number için versiyon counter. Artarak ilerler.
-      "last_update_date": "2025-06-08T12:00:00.000Z",
-      "last_update_user": "admin",
-      "deleted": false,
-      "created_date": "2025-06-08T12:00:00.000Z",
-      "created_by": "admin",
-
-      // --------------------------------------------------------
-      // VERSIONS: Proje revizyonları ayrı bir version_number ile takip edilir.
-      // Yayınlanmış versiyonlar üzerinde düzenleme yapılamaz.
-      // Yeni versiyon oluşturumak için published versiyonlardan biri seçilir ve kopyası oluştulur, bu kopya üzerinde düzenleme yapılabilir.
-      // --------------------------------------------------------
-      "versions": [
-        {
-          "id": 1, // Proje versiyonu
-          "caption": "v1",
-          "published": true, // Versiyonun yayınlanma durumu.
-          
-          // === Virtual agent'ın yapabileceği işleri tarifler =========
-          "general_prompt": "You are an airline assistant. You can book tickets, give information about booked tickets ...",
-          
-          // === LLM configuration =======================
-          "llm": {
-            // Spark mode için:
-            "repo_id": "ytu-ce-cosmos/Turkish-Llama-8b-DPO-v0.1", // HuggingFace model repo ID
-            "generation_config": { // LLM generation parametreleri
-              "max_new_tokens": 128,
-              "temperature": 0.3,
-              "top_p": 0.7,
-              "repetition_penalty": 1.1
-            },
-            "use_fine_tune": false, // LoRA fine-tune model kullanılma durumu
-            "fine_tune_zip": "", // use_fine_tune: true ise, kullanılacak LoRA adapter zip'in URL'i
-            
-            // GPT-4o mode için (work_mode = "gpt4o" veya "gpt4o-mini" olduğunda kullanılır):
-            "gpt_model": "gpt-4o", // "gpt-4o" | "gpt-4o-mini"
-            "gpt_temperature": 0.3, // 0-2 arası
-            "gpt_max_tokens": 512 // Maximum response token sayısı
-          },
-          
-          // === INTENTS =================================
-          "intents": [
-            {
-              "name": "currency_rate_intent", // alt çizgi, tire yok
-              "caption": "Kur sorgulama",
-              "locale": "tr-TR",
-              "dependencies": [], // intent bağımlılıkları.
-              
-              // Intent detection
-              "examples": [
-                "What is the dollar rate?",
-                "How much is the euro?"
-              ],
-              "detection_prompt": "Identify if user is asking for currency rate information.", // Intent detection için kullanılacak system prompt.
-              
-              // Parameters: Intent tespit edildiğinde, kullanıcının ifadesinden extract edilecek parametreler
-              "parameters": [
-                {
-                  "name": "currency",
-                  "caption": "Döviz cinsi", // Eksik parametreyi tamamlarken kullanıcıya söylenebilecek parametre adı
-                  "type": "str", // "str" | "int" | "float" | "bool" | "date"
-                  "required": true,
-                  "variable_name": "currency", // Parametre değerini set edeceğimiz session değişkeni adı
-                  "extraction_prompt": "Extract the currency code (USD, EUR, TRY) from the user message.", // Parametre extraction için kullanılacak system prompt
-                  "validation_regex": "^(USD|EUR|TRY)$", // kullanıcıdan alınan parametre değerini validate etmek için kullanılacak regex. Opsiyonel.
-                  "invalid_prompt": "Geçersiz para birimi girdiniz. USD, EUR veya TRY şeklinde giriniz.", // Parametre değeri invalid ise kullanıcıya söylenecek mesajı oluşturacak system prompt
-                  "type_error_prompt": "Para birimi metin olmalıdır (ör: USD)." // Eğer parametre tipi hatalıysa kullanıcıya söylenecek mesajı oluşturacak system prompt
-                }
-              ],
-              
-              // API to call
-              "action": "currency_api", // Bu intent tespit edilip, parametreleri tamamlandığında çağırılacak api'nin adı.
-              
-              // Fallbacks
-              "fallback_timeout_prompt": "Kur servisinde gecikme yaşanıyor. Lütfen biraz sonra tekrar deneyin.", // Api timeout durumunda kullanıcıya söylenecek mesajı oluşturacak system prompt
-              "fallback_error_prompt": "Kur bilgileri alınırken bir hata oluştu, daha sonra tekrar deneyebilir misiniz?" // Api hatası durumunda kullanıcıya söylenecek mesajı oluşturacak system prompt
-            }
-            // ... başka intent'ler
-          ],
-          
-          "last_update_date": "2025-06-08T12:00:00.000Z",
-          "last_update_user": "admin",
-          "deleted": false,
-          "created_date": "2025-06-08T12:00:00.000Z",
-          "created_by": "admin",
-          "publish_date": "2025-06-08T12:00:00.000Z",
-          "published_by": "admin"
-        }
-        // ... yeni versiyonlar
-      ]
-    }
-    // ... başka projeler
-  ],
+### Health Check
+```python
+@app.get("/")
+def health():
+    return {"status": "ok"}
 
-  // =====================================================
-  // API DEFINITIONS (dict by name): Intent'lerde action olarak kullanılacak api tanımları
-  // =====================================================
-  "apis": [
-    {
-      "name": "currency_api",
-      "url": "https://mock.api/currency",
-      "method": "POST",
-      
-      // Headers as dict; placeholders destekler
-      "headers": {
-        "Content-Type": "application/json",
-        "Authorization": "Bearer {{auth_tokens.currency_api.token}}"
-      },
-      
-      // Body template
-      "body_template": {
-        "currency": "{{variables.currency}}"
-      },
-      
-      // Timeout & retry
-      "timeout_seconds": 5,
-      "retry": {
-        "retry_count": 3,
-        "backoff_seconds": 2,
-        "strategy": "static" // "static" | "exponential"
-      },
-      
-      // Auth (optional)
-      "auth": {
-        "enabled": false,
-        "token_endpoint": "https://mock.api/auth",
-        "token_request_body": {},
-        "response_token_path": "token", // json-path style. Ex: xx.yy.z
-        "token_refresh_endpoint": null, // opsiyonel
-        "token_refresh_body": {} // token_refresh_endpoint varsa zorunlu, yoksa opsiyonel.
-      },
-      
-      "proxy": "", // Proxy (optional)
-      
-      // API response → human-friendly answer
-      "response_prompt": "Aşağıdaki JSON döviz kuru bilgilerini içeriyor. Kullanıcıya anlaşılır bir Türkçe özet hazırla:\n\n{{api_response}}",
-      
-      // Response mapping
-      "response_mappings": [
-        {
-          "variable_name": "exchange_rate",
-          "type": "float",
-          "json_path": "data.rate"
-        }
-      ],
-      
-      "last_update_date": "2025-06-08T12:00:00.000Z",
-      "last_update_user": "admin",
-      "deleted": false,
-      "created_date": "2025-06-08T12:00:00.000Z",
-      "created_by": "admin"
-    }
-  ],
-
-  // =====================================================
-  // ACTIVITY LOG
-  // =====================================================
-  "activity_log": [
-    {
-      "id": 1,
-      "timestamp": "2025-06-08T12:00:00.000Z",
-      "user": "admin",
-      "action": "CREATE_PROJECT",
-      "entity_type": "project",
-      "entity_id": 1,
-      "entity_name": "airline_agent",
-      "details": "Created new project"
-    }
-  ]
-}
+# Hugging Face için daemon thread
+threading.Thread(target=run_health_server, daemon=True).start()
 ```

flare-ui-tasarim.md

@@ -1,632 +1,605 @@
-# Flare Administration UI - Tasarım Dokümanı
+# Flare Administration UI - Güncel Tasarım Dokümanı
 
-## 📌 Amaç
+## 📌 Genel Bakış
 
-Flare Administration UI (Flare Admin), kullanıcıların Flare platformunda proje tanımlayıp yönetebileceği bir web arayüzüdür. Angular ile geliştirilir, backend olarak Python ile geliştirilmiş olan Flare backend'i kullanır.
+Flare Administration UI, Flare platformunun web tabanlı yönetim arayüzüdür. Angular 16+ ile geliştirilmiş, Material Design prensiplerine uygun, responsive ve modern bir single-page application'dır.
 
-Flare Admin ekranlarında; proje tanımlama, mevcut projeyi düzenleme, projeye versiyon çıkarma, versiyonu publish etme, projeyi enable-disable etme, proje tanımını silme gibi işlemler yapılabilir.
+## 🏗 Teknik Altyapı
 
-Document database olarak Flare'in service_config.jsonc dosyasını kullanır. Tüm tanım, düzenleme, silme ve listeleme işlemlerini bu dosya üzerinde yapar.
-
-Flare Admin, Flare backend servisi üzerinden Spark veya GPT-4o ile entegre çalışır. Ayrıca TTS (Text-to-Speech) ve STT (Speech-to-Text) motorları ile sesli etkileşim desteği sunar.
-
-## Genel Kurallar
-
-Flare Admin, login ekranıyla başlar. Kullanıcı login olduktan sonra tanım ekranları görüntülenir.
-
-Tanım ekranları, tab window'lar şeklinde gruplandırılmıştır. Her tab'da birbiriyle alakalı işlemler yapılır.
-
-Tüm hatalı işlemler, işlemin yapıldığı ekranın alt kısmında kırmızı font ile uyarı şeklinde görüntülenir ve uyarı 5 sn sonra kaybolur.
-
-Boolean alanlar ekranda (hem input olarak, hem de tablo üzerinde) checkbox olarak görüntülenir.
-
-Silme işlemleri öncesinde, silinecek nesnenin diğer nesneler altında kullanımda olup olmadığı kontrol edilir. Eğer kullanımdaysa, silinmesine izin verilmez ve hangi nesneler tarafından kullanıldığını içeren bir mesaj ve hata kodu ile döndürülür. Kullanımda olmayan nesneyi silme öncesinde açılacak bir dialog'da kullanıcıdan onay alınır. Onayın ardından silme işlemi yapılır.
-
-Nesnenin **deleted** alanı varsa silme işlemi fiziksel olarak yapılmaz, deleted=true olarak değiştirilir.
-
-Ortam çok kullanıcılı olduğundan kayıt düzenleme işlemlerinde race condition kontrolü yapılır. Bunun için service_config.jsonc içinde config, project, version ve api nesnelerine **last_update_date** alanı eklenir.
-
-Kullanıcı, düzenlemek için nesneyi ekrana yüklediğinde nesne içindeki bu değeri de yükler. Save butonuna bastığında backend'e bu değeri de gönderir ve backend kayıt öncesi bu değerin service_config.jsonc'deki ilgili nesnedeki değerle aynı olup olmadığını kontrol eder, aynı ise kaydı yapar ve kaydederken bu değeri o andaki tarih-saat-dakika-saniye-milisaniye değeri ile günceller.
-
-Eğer bir başka kullanıcı aynı kaydı düzenliyorsa ve ilk kullanıcıdan sonra save'e bastıysa dosyadaki bu değer değişmiş olacağından backend kayda izin vermez ve "Kayıt başka kullanıcı tarafından düzenlendi. Lütfen tekrar yükleyin." tarzı bir uyarı ile birlikte bir hata kodu döndürür.
-
-Bir diğer durum da, kullanıcı tarafından düzenlenen kaydın, bu kullanıcı kaydetmeden önce başka bir kullanıcı tarafından silinmiş olması durumudur. Backend kayıt öncesi dosyada bu nesneyi bulamazsa "Kayıt başka kullanıcı tarafından silindi." gibi bir uyarı ve bir hata kodu döndürür, kayda izin vermez.
-
-## Auto-save ve Undo/Redo Mekanizması
-
-- Published olmayan version'lar üzerinde çalışırken her 30 saniyede bir otomatik draft kayıt yapılır
-- Son 10 işlem için undo/redo desteği (Ctrl+Z / Ctrl+Y)
-- Draft kayıtlar drafts/ klasöründe tutulur ve UI açıldığında "Recover unsaved changes?" dialog'u gösterilir
-
-## Klavye Kısayolları
-
-- Ctrl+S: Save
-- Ctrl+N: New (context'e göre project/version/intent)
-- Ctrl+F: Search/Filter
-- Ctrl+D: Duplicate
-- Esc: Cancel/Close dialog
-
-## Flare Backend Düzenlemeleri
-
-Flare backend'de Flare Admin UI işleyişi için bazı eklemeler yapılması gerekiyor.
-
-### Eklenecek endpoint'ler:
-
-#### Temel CRUD Endpoint'leri
-
-- POST /api/login - Kullanıcı girişi ve token üretimi
-- GET /api/environment - Environment bilgileri alma
-- PUT /api/environment - Environment bilgilerini kaydetme
-- GET /api/projects - Proje listeleme (pagination, filter, sort destekli)
-- POST /api/projects - Yeni proje oluşturma: Yeni proje oluşturulduğunda backend, version_id_counter alanını **1**'e ayarlar ve otomatik **Version 1** kaydını ekler. Frontend ekstra çağrı yapmaz.
-- PUT /api/projects/{id} - Mevcut projeyi düzenleme
-- DELETE /api/projects/{id} - Mevcut projeyi silme
-- PATCH /api/projects/{id}/toggle - Proje enable/disable
-- POST /api/projects/{id}/versions - Proje versiyonu oluşturma
-- DELETE /api/projects/{id}/versions/{version_id} - Versiyon silme
-- PUT /api/projects/{id}/versions/{version_id} - Versiyon düzenleme
-- POST /api/projects/{id}/versions/{version_id}/publish - Versiyon yayınlama
-- GET /api/apis - API listeleme
-- POST /api/apis - Yeni API ekleme
-- PUT /api/apis/{name} - Mevcut API'yi düzenleme
-- DELETE /api/apis/{name} - Mevcut API'yi silme
-
-#### Spark Integration Endpoint'leri
-
-- POST /api/spark/startup - Projeyi Spark'a yükle
-- GET /api/spark/projects - Spark proje listesi
-- POST /api/spark/project/enable - Projeyi aktifleştir
-- POST /api/spark/project/disable - Projeyi devre dışı bırak
-- DELETE /api/spark/project/{name} - Projeyi Spark'tan sil
-
-#### Chat Endpoint'leri
-
-- GET /api/projects/names - Chat için enabled proje listesi
-- POST /api/start_session - Chat session başlat
-- POST /api/chat - Mesaj gönder/al (Header: X-Session-ID)
-
-#### TTS/STT Endpoint'leri
-
-- POST /api/tts/generate - Text'ten ses üret
-- GET /api/tts/voices - Desteklenen ses listesi
-- POST /api/stt/transcribe - Sesten text'e dönüştür (gelecek özellik)
-
-#### Ek Yardımcı Endpoint'ler
-
-- POST /api/validate/regex - Regex pattern validasyonu
-- POST /api/apis/test - API endpoint test etme
-- GET /api/projects/{id}/versions/diff - Version karşılaştırma
-- POST /api/projects/{id}/intents/bulk-delete - Toplu intent silme
-- GET /api/activity-log - Aktivite logları
-- POST /api/projects/import - Proje import
-- GET /api/projects/{id}/export - Proje export
-- POST /api/test/run-all - Tüm testleri çalıştır
-- GET /api/test/status - Test durumu sorgula
-
-### Service_config.jsonc düzenlemeleri:
-
-```jsonc
+### Frontend Stack
+```json
 {
-  "config": {
-    // Mevcut alanlar...
-    "work_mode": "hfcloud", // "hfcloud" | "cloud" | "on-premise" | "gpt4o" | "gpt4o-mini" - Yeni: gpt4o desteği
-    "cloud_token": "", // work_mode'a göre Spark token veya OpenAI API key (şifrelenmiş)
-    "internal_prompt": "⚠️ **NEVER output \"#DETECTED_INTENT:\"...", // Yeni
-    "project_id_counter": 1, // Yeni
-    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
-    "last_update_user": "admin", // Yeni
-    
-    // TTS/STT Configuration - Yeni
-    "tts_engine": "no_tts", // "no_tts" | "elevenlabs" | "blaze"
-    "tts_engine_api_key": "enc:...", // Şifrelenmiş TTS API key
-    "stt_engine": "no_stt", // "no_stt" | "elevenlabs" | "flicker"
-    "stt_engine_api_key": "enc:..." // Şifrelenmiş STT API key
-  },
-  
-  "projects": [{
-    // Mevcut alanlar...
-    "icon": "folder", // Yeni
-    "description": "", // Yeni
-    "default_language": "tr", // Yeni
-    "supported_languages": ["tr"], // Yeni
-    "timezone": "Europe/Istanbul", // Yeni
-    "region": "tr-TR", // Yeni
-    "version_id_counter": 1, // Yeni
-    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
-    "last_update_user": "admin", // Yeni
-    "deleted": false, // Yeni
-    "created_date": "2025-06-08T12:00:00.000Z", // Yeni
-    "created_by": "admin", // Yeni
-    
-    "versions": [{
-      // Mevcut alanlar...
-      "llm": {
-        // Spark mode için:
-        "repo_id": "model-repo/id",
-        "generation_config": {},
-        "use_fine_tune": false,
-        "fine_tune_zip": "",
-        
-        // GPT-4o mode için (work_mode = "gpt4o" veya "gpt4o-mini" olduğunda kullanılır):
-        "gpt_model": "gpt-4o", // "gpt-4o" | "gpt-4o-mini"
-        "gpt_temperature": 0.3, // 0-2 arası
-        "gpt_max_tokens": 512 // Maximum response token sayısı
-      },
-      "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
-      "last_update_user": "admin", // Yeni
-      "deleted": false, // Yeni
-      "created_date": "2025-06-08T12:00:00.000Z", // Yeni
-      "created_by": "admin", // Yeni
-      "publish_date": null, // Yeni
-      "published_by": null // Yeni
-    }]
-  }],
-  
-  "apis": [{
-    // Mevcut alanlar...
-    "response_mappings": [ // Yeni
-      {
-        "variable_name": "booking_id",
-        "type": "str",
-        "json_path": "confirmation.id"
-      }
-    ],
-    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
-    "last_update_user": "admin", // Yeni
-    "deleted": false, // Yeni
-    "created_date": "2025-06-08T12:00:00.000Z", // Yeni
-    "created_by": "admin" // Yeni
-  }],
-  
-  // Yeni: Activity log
-  "activity_log": [{
-    "id": 1,
-    "timestamp": "2025-06-08T12:00:00.000Z",
-    "user": "admin",
-    "action": "CREATE_PROJECT",
-    "entity_type": "project",
-    "entity_id": 1,
-    "entity_name": "airline_agent",
-    "details": "Created new project"
-  }]
+  "framework": "Angular 16+",
+  "ui_library": "Angular Material",
+  "styling": "SCSS + Tailwind CSS (utility classes)",
+  "state_management": "RxJS + Services",
+  "http": "HttpClient with Interceptors",
+  "icons": "Material Icons + Lucide",
+  "editor": "CodeMirror (JSON/JSONC)",
+  "charts": "Chart.js",
+  "build": "Standalone Components"
 }
 ```
 
-## Tab Ekranları
-
-### 1. User Info Tab'ı
-
-Bu tab penceresinde login olan kullanıcı mevcut şifresini değiştirebilir. Ekrandaki alanlar:
+### Backend Integration
+- RESTful API endpoints
+- JWT Authentication (`X-Auth-Token` header)
+- Real-time updates (WebSocket - planned)
+- File upload/download (import/export)
 
-- Current Password (maskeli)
-- New Password (maskeli)
-- New Password (tekrar, maskeli)
-- Password Strength Indicator: Şifre girilirken güvenlik seviyesini gösterir (Weak/Medium/Strong)
-- Save butonu
+## 🎨 UI Yapısı
 
-Şifre değiştirebilmek için kullanıcı, maskeli alanlardan mevcut şifresini, yeni şifresini ve ikinci bir alanda teyit amaçlı olarak tekrar yeni şifresini girer ve kaydet butonuna basar. Şifre en az 8 karakter, büyük/küçük harf ve rakam içermelidir.
-
-### 2. Environment Tab'ı
-
-Bu tab'da aşağıdaki alanlar bulunur:
-
-- **Work Mode**: Seçenekleri **hfcloud**, **cloud**, **on-premise**, **gpt4o** ve **gpt4o-mini** olan bir combo. Zorunlu.
-- **Cloud Token / OpenAI API Key** (maskeli): 
-  - Work Mode **on-premise** seçildiğinde disable olur.
-  - Work Mode **gpt4o** veya **gpt4o-mini** seçildiğinde label "OpenAI API Key" olarak değişir
-  - Diğer modlarda "Cloud Token" olarak görünür
-- **Spark Endpoint**: URL formatında. GPT-4o mode hariç zorunlu. Yanında "Test Connection" butonu. GPT-4o seçildiğinde disable olur.
-- **TTS Engine**: Seçenekleri **no_tts**, **elevenlabs**, **blaze** olan combo.
-- **TTS API Key** (maskeli): TTS Engine **no_tts** dışında bir değer seçildiğinde zorunlu olur.
-- **STT Engine**: Seçenekleri **no_stt**, **elevenlabs**, **flicker** olan combo.
-- **STT API Key** (maskeli): STT Engine **no_stt** dışında bir değer seçildiğinde zorunlu olur.
-- **Internal System Prompt**: Expansion panel içinde multi-line textarea. LLM'in tüm projeler için kullanacağı temel kuralları içerir. Placeholder'lar:
-  - <intent names>: Runtime'da intent listesiyle değiştirilir
-  - <intent captions>: Intent caption'larıyla değiştirilir
-  - <project language>: Proje diline göre değiştirilir
-- Save butonu
-- Reload from Spark butonu: Spark'tan güncel config'i çeker (GPT mode'da disable)
-
-**GPT-4o Mode Uyarısı**: Work mode GPT-4o veya GPT-4o-mini seçildiğinde bir info alert gösterilir:
+### 1. Layout Structure
 ```
-ℹ️ GPT-4o mode uses OpenAI's API which has usage-based pricing. 
-   Please ensure you have sufficient credits in your OpenAI account.
-   Approximate cost: $0.01-0.03 per conversation turn for GPT-4o.
-   Approximate cost: $0.001-0.003 per conversation turn for GPT-4o-mini.
+┌────────────────────────────────────────────────────┐
+│  Flare Admin    [Environment] [User ▼] [Logout]    │  <- Header
+├────────────────────────────────────────────────────┤
+│ Projects | APIs | Users | Logs | [Config ⚙]        │  <- Tab Bar
+├────────────────────────────────────────────────────┤
+│                                                    │
+│                 [Tab Content]                      │  <- Content Area
+│                                                    │
+└────────────────────────────────────────────────────┘
 ```
 
-**TTS/STT Configuration**: Work mode ne olursa olsun TTS ve STT motorları konfigüre edilebilir. TTS motorları bot yanıtlarını seslendirmek, STT motorları ise kullanıcıdan sesli girdi almak için kullanılır.
-
-### 3. APIs Tab'ı
-
-Tab açıldığında, üstte bir toolbar bulunur:
-
-**Toolbar:**
-- New API butonu
-- Import butonu: JSON dosyasından API tanımları yükler
-- Export butonu: Seçili API'leri JSON olarak export eder
-- Search alanı: API adı veya URL'de arama
-- Display Deleted checkbox
-
-**API Listesi Tablosu:**
-
-| Name | URL | Method | Timeout | Auth | Deleted | Actions |
-|------|-----|---------|---------|------|---------|---------|
-| book_flight_api | https://api.example.com/book | POST | 10s | ✓ | ✗ | 🖊️ 🧪 📋 🗑️ |
+### 2. Login Component
+- Material card design
+- Username/Password fields
+- "Remember Me" checkbox
+- Error handling with snackbar
+- Auto-redirect after login
+
+### 3. Projects Tab
+
+#### Project List View
+```typescript
+interface ProjectDisplay {
+  id: number;
+  name: string;
+  caption: string;
+  icon: string;
+  enabled: boolean;
+  versionCount: number;
+  lastUpdate?: string;
+}
+```
 
-**Action İkonları:**
-- 🖊️ Edit: Edit API dialog'unu açar
-- 🧪 Test: API'yi test eder
-- 📋 Duplicate: API'nin kopyasını oluşturur
-- 🗑️ Delete: API'yi siler (kullanımda değilse)
+**Features:**
+- Grid layout (responsive cards)
+- Quick actions: Edit, Toggle Enable, Delete
+- Version count badge
+- Status indicator (enabled/disabled)
+- Search/Filter toolbar
+- "New Project" FAB
+
+#### Project Edit Dialog
+**Tabs Structure:**
+1. **Basic Info**
+   - Name, Caption, Icon selector
+   - Description (textarea)
+   - Locale settings (default + supported)
+   - Timezone and region
+
+2. **Versions**
+   - Version list with status badges
+   - Actions: Edit, Copy, Publish, Delete
+   - Published versions are read-only
+   - Version comparison (planned)
+
+3. **Settings**
+   - Advanced project settings
+   - Integration configs
+
+#### Version Editor
+**Split-panel Layout:**
+```
+┌─────────────────┬────────────────────────┐
+│ Intent List     │ Intent Details         │
+│ ─────────────── │ ───────────────────    │
+│ ✓ searchFlights │ Name: searchFlights    │
+│   bookFlight    │ Caption: Uçuş Arama    │
+│   checkBooking  │ [Requires Approval: □] │
+│ + Add Intent    │ Examples: [...]        │
+└─────────────────┴────────────────────────┘
+```
 
-### 4. Projects Tab'ı
+**Version Fields:**
+- General Prompt (CodeMirror editor)
+- Welcome Prompt (with LLM preview)
+- LLM Configuration
+  - Model selection
+  - Generation config (expandable)
+  - Fine-tune settings
+
+#### Intent Editor
+**Sections:**
+1. **Basic Info**
+   - Name (auto-slug)
+   - Caption
+   - requiresApproval toggle
+   - Dependencies (multi-select)
+
+2. **Examples** (Multilingual)
+   ```typescript
+   interface ExampleEditor {
+     locale: string;
+     examples: string[];
+   }
+   ```
+   - Tab per locale
+   - Add/Remove examples
+   - Bulk import
+
+3. **Parameters**
+   - Drag-drop reordering
+   - Inline editing
+   - Type-specific validators
+   - Multi-language captions
+
+4. **Action**
+   - API selection dropdown
+   - API preview panel
+   - Test action (planned)
+
+#### Parameter Editor Component
+```html
+<app-parameter-editor
+  [parameter]="param"
+  [locales]="['tr', 'en']"
+  [availableVariables]="variables"
+  (change)="onParameterChange($event)">
+</app-parameter-editor>
+```
 
-Tab ekranına girildiğinde üstte toolbar bulunur:
+**Features:**
+- Smart variable name generation
+- Type-specific controls
+- Regex validator with tester
+- Multi-language support
+
+### 4. APIs Tab
+
+#### API List
+**DataTable Columns:**
+- Name | URL | Method | Auth | Response | Actions
+
+**Features:**
+- Sorting and filtering
+- Inline status indicators
+- Batch operations
+- Export to CSV
+
+#### API Edit Dialog
+**Advanced Tab Structure:**
+
+1. **Basic Configuration**
+   ```typescript
+   interface APIBasic {
+     name: string;
+     description?: string;  // For approval messages
+     url: string;
+     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+   }
+   ```
+
+2. **Headers & Body**
+   - JSON editor with syntax highlighting
+   - Variable autocomplete (`{{variables.xxx}}`)
+   - Template validation
+   - Format/Beautify button
+
+3. **Authentication**
+   - Enable/Disable toggle
+   - Token endpoint configuration
+   - Token path (JSON path)
+   - Refresh mechanism setup
+
+4. **Response Configuration**
+   - Response prompt editor
+   - Response mappings builder
+   - JSON path tester
+   - Sample response upload
+
+5. **Advanced Settings**
+   - Timeout configuration
+   - Retry strategy
+   - Proxy settings
+
+#### Response Mapping Builder
+```typescript
+interface ResponseMapping {
+  variable_name: string;
+  caption: string;
+  type: string;
+  json_path: string;
+}
+```
 
-**Toolbar:**
-- New Project butonu
-- Import Project butonu
-- Search alanı
-- Display Deleted checkbox
-- View: List/Card view toggle
+**Visual JSON Path Builder:**
+- Upload sample response
+- Click to build path
+- Real-time validation
+- Type inference
 
-**Proje Listesi:** Kart görünümünde her proje için:
-```
-┌─────────────────────────────────────┐
-│ 🛩️ airline_agent                │
-│ Havayolu Müşteri Temsilcisi     │
-│ Language: Turkish (tr)          │
-│ Versions: 3 (1 published)       │
-│ Status: ✓ Enabled               │
-│ Last update: 2 hours ago        │
-│ [Edit] [Versions] [Export] [⚙️] │
-└────────────────────────────────────┘
-```
+### 5. Environment Configuration
 
-### 5. Chat Tab'ı
-
-Flare chat sistemini test etmek için kullanılır.
-
-**İşleyiş:**
-1. **Project Selection**: Enabled ve published version'u olan projeler listelenir
-2. **TTS Option**: "Use TTS" checkbox'ı ile sesli yanıt özelliği aktifleştirilebilir (TTS konfigüre edilmişse)
-3. **Start Chat**: Session başlatır, session_id alır
-4. **Chat Interface**:
-   - Mesaj history'si
-   - Input alanı
-   - Send butonu
-   - Session bilgileri (ID, project)
-   - TTS enabled ise her bot mesajı için play butonu
-   - Ses oynatılırken waveform visualizasyon
-5. **End Session**: Chat'i sonlandırır
-
-**Özellikler:**
-- Real-time mesajlaşma
-- Session takibi
-- Auto-scroll
-- Error handling
-- Loading states
-- TTS desteği (konfigüre edilmişse)
-- Audio waveform visualization
-- Otomatik ses oynatma (opsiyonel)
-
-### 6. Spark Integration Tab'ı
-
-Bu tab'da Spark servisi ile doğrudan etkileşim sağlanır. **GPT-4o mode'da bu tab disable olur ve bir bilgi mesajı gösterilir.**
-
-**GPT-4o Mode'da Görünüm:**
+#### Provider Management
 ```
-┌─────────────────────────────────────────────┐
-│ ℹ️ Spark Integration Unavailable        │
+┌─────────────────────────────────────────┐
+│ LLM Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ ⚡ Spark LLM          [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
 │                                         │
-│ Spark integration is not available when │
-│ using GPT-4o as the LLM provider.       │
+│ TTS Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ 🔊 ElevenLabs        [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
 │                                         │
-│ GPT-4o handles all language model       │
-│ operations directly through OpenAI API. │
-└─────────────────────────────────────────────┘
+│ STT Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ 🎤 Google STT        [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
+└─────────────────────────────────────────┘
 ```
 
-**Normal Mode'da (Spark):**
+**Provider Configuration:**
+- Dynamic form based on provider requirements
+- API key encryption indicator
+- Endpoint validation
+- Test connection button
+
+#### Internal Prompt Editor
+- Full-screen CodeMirror
+- Placeholder hints
+- Template variables sidebar
+- Save with validation
+
+### 6. Activity Logs
+
+#### Timeline View
+```typescript
+interface ActivityLog {
+  timestamp: string;
+  username: string;
+  action: string;
+  entity_type: string;
+  entity_name?: string;
+  details?: string;
+}
+```
 
-**Üst Bölüm:**
-- Project Selection: Dropdown ile proje seçimi
-- Proje seçildiğinde butonlar aktif olur
+**Features:**
+- Infinite scroll
+- Real-time updates
+- Filter by action/user/date
+- Export functionality
+- Detailed view dialog
 
-**Butonlar ve İşlevleri:**
+### 7. Test Console
 
-**Project Startup**
-- Seçili projeyi Spark'a yükler
-- Backend üzerinden /spark/startup endpoint'ine istek atar
-- Response'u detaylı olarak gösterir
+#### Chat Test Interface
+```
+┌─────────────────────────────────────────┐
+│ Project: [pegasus_airlines ▼] v[1 ▼]   │
+├─────────────────────────────────────────┤
+│ ┌─────────────────────────────────────┐ │
+│ │ 💬 Chat Messages                    │ │
+│ │ ─────────────────────                │ │
+│ │ 🤖 Hoş geldiniz!                    │ │
+│ │ 👤 Uçuş aramak istiyorum            │ │
+│ │ 🤖 [Intent: searchFlights]          │ │
+│ │    Nereden nereye?                  │ │
+│ └─────────────────────────────────────┘ │
+│ [Message input] [🎤] [Send]            │
+├─────────────────────────────────────────┤
+│ Session Info | Variables | API Calls    │
+└─────────────────────────────────────────┘
+```
 
-**Get Project Status**
-- Spark'taki tüm projelerin durumunu listeler
-- Tablo formatında: project_name, version, status, enabled, last_accessed
-- Status badge'leri: ready (yeşil), loading (turuncu), error (kırmızı), unloaded (gri)
+**Debug Panel Tabs:**
+- Session state and variables
+- Intent detection details
+- API call history
+- Raw LLM responses
+
+## 🧩 Reusable Components
+
+### 1. Multi-Language Input
+```typescript
+@Component({
+  selector: 'app-multilang-input',
+  template: `
+    <mat-tab-group>
+      <mat-tab *ngFor="let locale of locales">
+        <ng-template mat-tab-label>
+          {{ getLocaleName(locale) }}
+        </ng-template>
+        <mat-form-field>
+          <input matInput [(ngModel)]="values[locale]">
+        </mat-form-field>
+      </mat-tab>
+    </mat-tab-group>
+  `
+})
+export class MultilangInputComponent {
+  @Input() locales: string[];
+  @Input() values: LocalizedValue[];
+  @Output() change = new EventEmitter();
+}
+```
 
-**Enable Project**
-- Seçili projeyi Spark'ta aktif hale getirir
+### 2. Variable Selector
+```typescript
+interface Variable {
+  name: string;
+  source: 'intent' | 'api' | 'system';
+  type: string;
+}
+```
 
-**Disable Project**
-- Seçili projeyi Spark'ta devre dışı bırakır
+**Features:**
+- Categorized dropdown
+- Search functionality
+- Type indicators
+- Copy to clipboard
+
+### 3. JSON Editor Wrapper
+```typescript
+@Component({
+  selector: 'app-json-editor',
+  template: `
+    <div class="editor-container">
+      <codemirror
+        [(ngModel)]="value"
+        [options]="editorOptions"
+        (change)="onChange()">
+      </codemirror>
+      <button mat-icon-button (click)="format()">
+        <mat-icon>format_align_left</mat-icon>
+      </button>
+    </div>
+  `
+})
+```
 
-**Delete Project**
-- Seçili projeyi Spark'tan tamamen siler
-- Onay dialog'u gösterir
+### 4. Confirmation Dialog
+```typescript
+interface ConfirmData {
+  title: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  dangerous?: boolean;
+}
+```
 
-**Response Panel:**
-- Her işlemden sonra açılan expansion panel
-- Request ve response JSON'larını gösterir
-- Timestamp bilgisi
-- Success/error durumu
-- Son 10 işlem history'si
+## 🎯 Services Architecture
+
+### Core Services
+```typescript
+// API communication
+@Injectable()
+export class ApiService {
+  // Project CRUD
+  getProjects(): Observable<Project[]>
+  createProject(data: ProjectData): Observable<Project>
+  updateProject(id: number, data: ProjectData): Observable<Project>
+  
+  // Version management
+  createVersion(projectId: number): Observable<Version>
+  publishVersion(projectId: number, versionId: number): Observable<Version>
+  
+  // Environment
+  getEnvironment(): Observable<EnvironmentConfig>
+  updateEnvironment(config: EnvironmentConfig): Observable<void>
+}
 
-### 7. Test Tab'ı
+// Authentication
+@Injectable()
+export class AuthService {
+  login(credentials: LoginData): Observable<AuthResponse>
+  logout(): void
+  getToken(): string | null
+  isAuthenticated(): boolean
+}
 
-Bu tab'da sistemin end-to-end testi yapılabilir:
+// Environment state
+@Injectable()
+export class EnvironmentService {
+  ttsEnabled$: BehaviorSubject<boolean>
+  sttEnabled$: BehaviorSubject<boolean>
+  currentProvider$: BehaviorSubject<ProviderInfo>
+}
+```
 
-**Test Kategorileri:**
-- UI Tests: Component render, navigation, form validation
-- Backend Tests: API endpoint'leri, data integrity
-- Integration Tests: UI-Backend entegrasyonu
-- Spark Tests: LLM bağlantısı ve response kalitesi (GPT mode'da "GPT-4o Tests" olarak görünür)
-- TTS Tests: TTS motor bağlantısı ve ses üretimi (TTS konfigüre edilmişse)
+### HTTP Interceptor
+```typescript
+@Injectable()
+export class AuthInterceptor implements HttpInterceptor {
+  intercept(req: HttpRequest<any>, next: HttpHandler) {
+    const token = this.authService.getToken();
+    if (token) {
+      req = req.clone({
+        setHeaders: { 'X-Auth-Token': token }
+      });
+    }
+    return next.handle(req);
+  }
+}
+```
 
-**Ekran Düzeni:**
+## 🎨 Theming and Styling
+
+### Material Theme
+```scss
+// Custom theme
+$primary: mat-palette($mat-indigo);
+$accent: mat-palette($mat-pink, A200);
+$warn: mat-palette($mat-red);
+
+$theme: mat-light-theme((
+  color: (
+    primary: $primary,
+    accent: $accent,
+    warn: $warn
+  )
+));
+
+// Dark theme
+$dark-theme: mat-dark-theme((
+  color: (
+    primary: $primary,
+    accent: $accent,
+    warn: $warn
+  )
+));
 ```
-┌─────────────────────────────────────────────┐
-│ [Run All Tests] [Run Selected] [Stop]   │
-├─────────────────────────────────────────────┤
-│ □ All Tests                             │
-│   □ UI Tests (15 tests)                 │
-│     □ Login Flow                        │
-│     □ Project CRUD                      │
-│     □ Version Management                │
-│   □ Backend Tests (22 tests)            │
-│     □ Authentication                    │
-│     □ API Endpoints                     │
-│     □ Race Conditions                   │
-│   □ Integration Tests (18 tests)        │
-│   □ LLM Tests (8 tests)                 │
-│   □ TTS Tests (5 tests)                 │
-├───────────────────────────────���─────────────┤
-│ Test Results:                           │
-│ ✓ Login with valid credentials - 120ms  │
-│ ✓ Create new project - 340ms            │
-│ ✗ Delete API in use - Expected behavior │
-│ ⏳ Testing LLM connection...            │
-│                                         │
-│ Progress: ████████░░ 80% (48/60)         │
-│ Passed: 45 | Failed: 3 | Running: 5     │
-└─────────────────────────────────────────────┤
+
+### Component Styling Pattern
+```scss
+.component-container {
+  @apply p-4 h-full flex flex-col;
+  
+  .header {
+    @apply flex justify-between items-center mb-4;
+  }
+  
+  .content {
+    @apply flex-1 overflow-auto;
+  }
+  
+  .actions {
+    @apply mt-4 flex justify-end gap-2;
+  }
+}
 ```
 
-**Test Detayları:** Her test için:
-- Test adı ve açıklaması
-- Çalışma süresi
-- Hata durumunda detaylı log
-- "Re-run" butonu
+## 📱 Responsive Design
 
-### 8. Activity Log (Sağ üst notification icon'a tıklandığında açılır)
+### Breakpoints
+```scss
+$mobile: 640px;
+$tablet: 768px;
+$desktop: 1024px;
+$wide: 1280px;
+```
 
+### Mobile Adaptations
+- Collapsible sidebar
+- Bottom sheet dialogs
+- Touch-optimized controls
+- Simplified layouts
+
+## 🚀 Performance Optimizations
+
+### Lazy Loading
+```typescript
+const routes: Routes = [
+  {
+    path: 'projects',
+    loadChildren: () => import('./projects/projects.module')
+      .then(m => m.ProjectsModule)
+  }
+];
 ```
-┌─────────────────────────────────────┐
-│ 🔔 Recent Activities             │
-├─────────────────────────────────────┤
-│ 2 min ago                        │
-│ 👤 admin published version 2     │
-│ of airline_agent                 │
-├─────────────────────────────────────┤
-│ 15 min ago                       │
-│ 👤 user1 updated flight_info_api │
-├─────────────────────────────────────┤
-│ 1 hour ago                       │
-│ 👤 admin created new project     │
-│ hotel_booking                    │
-├─────────────────────────────────────┤
-│ [View All Activities]            │
-└─────────────────────────────────────┘
+
+### Change Detection
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
 ```
 
-## Dialog Ekranları
+### Virtual Scrolling
+```html
+<cdk-virtual-scroll-viewport itemSize="50">
+  <div *cdkVirtualFor="let item of items">
+    {{ item }}
+  </div>
+</cdk-virtual-scroll-viewport>
+```
 
-### Edit API Dialog (Güncelleme)
+## 🔒 Security Considerations
 
-**General Tab'a eklenenler:**
+### XSS Prevention
+- Sanitized HTML rendering
+- Template validation
+- CSP headers
 
-**Response Mappings Bölümü:**
-- Variable Name: snake_case zorunlu
-- Type: str, int, float, bool, date seçenekleri
-- JSON Path: Dot notation ile path (örn: data.result.value)
-- Add/Remove mapping butonları
-- Validation: Variable name uniqueness
+### Authentication Flow
+```
+Login → JWT Token → Local Storage → HTTP Header → API Validation
+         ↓                ↓
+     Redirect        Auto Logout
+```
 
-**Template Variables (Geliştirilmiş):**
-- Tüm intent parametrelerinden otomatik liste
-- Response mapping değişkenleri
-- Auth token değişkenleri
-- Config değişkenleri (work_mode, vb.)
-- Tıklanabilir chip'ler ile kolay ekleme
+### Sensitive Data
+- Encrypted API keys (visual: `•••••••xyz`)
+- No plaintext passwords
+- Secure cookie options
 
-**JSON Validation (Geliştirilmiş):**
-- Numeric değişkenler için akıllı validation
-- Template variable type checking
-- Syntax highlighting
+## 🧪 Testing Strategy
 
-**Test Tab (Geliştirilmiş):**
-- Editable test request JSON
-- Placeholder değerlerle doldurma
-- Reset to template butonu
-- Response preview
+### Unit Tests
+- Component logic
+- Service methods
+- Pipe transformations
 
-### Edit Project Dialog (Güncelleme)
+### E2E Tests
+- User workflows
+- API integration
+- Error scenarios
 
-Yeni alanlar eklendi:
-- Icon: Material icon seçimi (folder, work, shopping_cart, vb.)
-- Description: Proje açıklaması
-- Default Language: Varsayılan dil (tr, en, de, fr, es)
-- Supported Languages: Desteklenen diller (çoklu seçim)
-- Timezone: Saat dilimi (Europe/Istanbul, vb.)
-- Region: Bölge kodu (tr-TR, vb.)
+## 📊 Analytics and Monitoring
 
-### Edit Version Dialog
+### User Activity Tracking
+- Feature usage metrics
+- Performance timing
+- Error reporting
 
-**LLM Configuration Tab'a GPT-4o Desteği:**
+### Dashboard Metrics
+- Active projects count
+- API call statistics
+- User engagement
 
-Work mode'a göre conditional rendering:
+## 🚦 Deployment
 
-**GPT-4o Mode'da:**
-```
-┌─────────────────────────────────────┐
-│ GPT-4o Configuration             │
-├─────────────────────────────────────┤
-│ Model:                           │
-│ [▼ GPT-4o             ]          │
-│                                  │
-│ Temperature: (0 = Deterministic) │
-│ [====|==============] 0.3        │
-│                                  │
-│ Max Tokens:                      │
-│ [512                 ]           │
-│                                  │
-│ ℹ️ Cost estimate: ~$0.02/request │
-└─────────────────────────────────────┘
+### Build Configuration
+```json
+{
+  "production": {
+    "optimization": true,
+    "sourceMap": false,
+    "namedChunks": false,
+    "extractLicenses": true,
+    "vendorChunk": false
+  }
+}
 ```
 
-**Spark Mode'da (mevcut):**
-- Model Repository
-- Generation Config (detaylı parametreler)
-- Fine-tune options
-
-### Edit Intent Dialog
-
-[Mevcut içerik korunacak, değişiklik yok]
-
-### Edit Parameter Dialog
-
-Date type desteği eklendi:
-- Type combo'suna "date" seçeneği
-- Date formatı: YYYY-MM-DD (ISO format)
-- Türkçe tarih ifadeleri için özel extraction prompt'lar
-
-### Version Comparison Dialog
-
-[Mevcut içerik korunacak, değişiklik yok]
-
-## Flare Admin Test Planı
+### Environment Files
+```typescript
+// environment.prod.ts
+export const environment = {
+  production: true,
+  apiUrl: '/api',
+  wsUrl: 'wss://flare.example.com'
+};
+```
 
-[Mevcut test planına ek olarak:]
-
-### GPT-4o Integration Test Senaryoları:
-
-**1. Environment Configuration:**
-- Work mode'u GPT-4o'ya değiştir
-- OpenAI API key gir
-- Save et
-- Spark endpoint'in disable olduğunu kontrol et
-
-**2. Version Management:**
-- GPT-4o mode'da yeni version oluştur
-- LLM tab'ında sadece GPT config'lerinin göründüğünü doğrula
-- Model, temperature, max_tokens ayarla
-- Publish et
-
-**3. Spark Tab Behavior:**
-- GPT-4o mode'da Spark tab'ın disable olduğunu kontrol et
-- Bilgi mesajının göründüğünü doğrula
-
-**4. Chat Testing:**
-- GPT-4o kullanan proje ile chat başlat
-- Intent detection test et
-- Parameter extraction test et
-- Response kalitesini değerlendir
-
-**5. Cost Tracking:**
-- Chat sonrası tahmini maliyet gösterimini kontrol et
-- Token kullanım bilgilerini doğrula
-
-### TTS/STT Test Senaryoları:
-
-**1. TTS Configuration:**
-- TTS Engine'i ElevenLabs'e ayarla
-- API key gir ve save et
-- Chat'te TTS özelliğini aktifle
-
-**2. Audio Generation:**
-- Bot yanıtlarının seslendirildiğini kontrol et
-- Play butonu işlevselliği
-- Waveform visualization
-- Ses kalitesi kontrolü
-
-**3. Multi-Engine Support:**
-- Farklı TTS motorları arasında geçiş
-- API key güvenliği
-- Hata durumlarının ele alınması
-
-### Multi-Provider Switching:
-
-**1. Mode Değişimi:**
-- Spark → GPT-4o → Spark geçişleri yap
-- Her geçişte config'lerin korunduğunu kontrol et
-- Token/key bilgilerinin şifreli kaldığını doğrula
-
-**2. Project Compatibility:**
-- Aynı projeyi farklı modlarda test et
-- Intent ve parameter mantığının tutarlı çalıştığını doğrula
-
-## Güvenlik ve Performans
-
-### Token Yönetimi:
-- SPARK_TOKEN environment variable'dan alınır
-- OPENAI_API_KEY cloud_token alanında şifrelenmiş saklanır
-- TTS/STT API key'ler şifrelenmiş saklanır
-- Tüm LLM/TTS/STT isteklerinde uygun Authorization header
-- Token rotation desteği
-
-### GPT-4o Özel Güvenlik:
-- API key asla plain text olarak loglanmaz
-- Rate limit handling
-- Cost monitoring ve alerting
-- Quota management
-
-### TTS Güvenlik:
-- API key şifreleme
-- Rate limiting
-- Concurrent request kontrolü
-- Audio dosya boyutu limitleri
-
-### Race Condition Handling:
-- last_update_date kontrolü tüm CRUD işlemlerinde
-- Concurrent edit detection
-- Optimistic locking pattern
-
-### Session Management:
-- 30 dakika inactivity timeout
-- Session cleanup thread
-- Memory-efficient storage
-- GPT-4o için token count tracking
-- TTS için audio cache yönetimi
-
-## Teknoloji Stack
-
-- **Frontend**: Angular 17+ (standalone components)
-- **UI Framework**: Angular Material
-- **State Management**: RxJS
-- **Backend**: Python FastAPI
-- **Authentication**: JWT
-- **Database**: service_config.jsonc (document database pattern)
-- **LLM Integration**: 
-  - Spark servisi (HuggingFace)
-  - OpenAI API (GPT-4o, GPT-4o-mini)
-- **TTS Integration**:
-  - ElevenLabs API
-  - Blaze (planned)
-- **STT Integration**:
-  - ElevenLabs (planned)
-  - Flicker (planned)
-- **Encryption**: Fernet (cloud_token/API key şifreleme)
-- **Audio Processing**: Web Audio API (waveform visualization)
-
-Bu güncellemelerle Flare Administration UI, hem Spark hem de GPT-4o desteği, TTS/STT entegrasyonu ile çok daha esnek ve güçlü bir orchestration platform yönetim arayüzü haline gelmiştir.
+## 🔄 Future Enhancements
+
+### Planned Features
+1. **Visual Flow Builder**: Drag-drop intent flow designer
+2. **A/B Testing**: Version comparison framework
+3. **Analytics Dashboard**: Usage statistics and insights
+4. **Collaboration**: Multi-user editing with presence
+5. **Plugin System**: Extensible architecture
+6. **Mobile App**: Native mobile management app
+
+### Technical Debt
+- Migrate to signals (Angular 17+)
+- Implement state management (NgRx)
+- Add comprehensive error boundaries
+- Improve test coverage to 80%+