architecture.md

# Cursor Rules Oluşturucu Mimari Tasarımı

Bu doküman, Gemini, OpenRouter, OpenAI API ve tüm modellerini destekleyen dinamik bir Cursor Rules oluşturucu için mimari tasarımı açıklamaktadır.

## 1. Genel Mimari Yapı

Cursor Rules oluşturucu, aşağıdaki ana bileşenlerden oluşan bir web uygulaması olarak tasarlanmıştır:

```
+----------------------------------+
|           Web Arayüzü            |
|  (HTML, CSS, JavaScript, React)  |
+----------------------------------+
                 |
                 v
+----------------------------------+
|         API Katmanı              |
|  (Flask/FastAPI, API Endpoint)   |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       LLM Entegrasyon Katmanı    |
|  (Adaptörler, Fabrika Deseni)    |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       Kural Oluşturma Motoru     |
|  (MDC Format, Şablonlar)         |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       Depolama Katmanı           |
|  (Dosya Sistemi, Veritabanı)     |
+----------------------------------+
```

### 1.1 Katmanlar ve Sorumlulukları

1. **Web Arayüzü**: Kullanıcı etkileşimi için frontend arayüzü
   - Kural oluşturma formu
   - LLM sağlayıcı seçimi
   - Kural tipi ve parametreleri yapılandırma
   - Önizleme ve indirme fonksiyonları

2. **API Katmanı**: Frontend ve backend arasındaki iletişim
   - HTTP endpoint'leri
   - İstek/yanıt işleme
   - Doğrulama ve hata yönetimi

3. **LLM Entegrasyon Katmanı**: Farklı LLM sağlayıcılarıyla iletişim
   - Adaptör deseni ile sağlayıcı entegrasyonu
   - API anahtarı yönetimi
   - İstek formatı dönüşümleri

4. **Kural Oluşturma Motoru**: Cursor Rules oluşturma mantığı
   - MDC format dönüşümü
   - Şablon yönetimi
   - Kural tipi işleme (Always, Auto Attached, Agent Requested, Manual)

5. **Depolama Katmanı**: Veri saklama ve erişim
   - Oluşturulan kuralları saklama
   - Şablonları yönetme
   - Kullanıcı tercihlerini saklama

## 2. Modül Organizasyonu

Uygulama, aşağıdaki modüllerden oluşacaktır:

```
cursor-rules-generator/
├── frontend/                  # Frontend uygulaması
│   ├── public/                # Statik dosyalar
│   ├── src/                   # Kaynak kodlar
│   │   ├── components/        # React bileşenleri
│   │   ├── services/          # API servisleri
│   │   ├── utils/             # Yardımcı fonksiyonlar
│   │   └── App.js             # Ana uygulama
│   └── package.json           # Bağımlılıklar
│
├── backend/                   # Backend uygulaması
│   ├── api/                   # API endpoint'leri
│   │   ├── __init__.py
│   │   └── routes.py          # API rotaları
│   │
│   ├── llm/                   # LLM entegrasyon katmanı
│   │   ├── __init__.py
│   │   ├── adapter.py         # Adaptör arayüzü
│   │   ├── gemini_adapter.py  # Gemini adaptörü
│   │   ├── openai_adapter.py  # OpenAI adaptörü
│   │   ├── openrouter_adapter.py # OpenRouter adaptörü
│   │   └── factory.py         # LLM fabrikası
│   │
│   ├── engine/                # Kural oluşturma motoru
│   │   ├── __init__.py
│   │   ├── rule_generator.py  # Kural oluşturucu
│   │   ├── mdc_formatter.py   # MDC format dönüştürücü
│   │   └── templates.py       # Şablon yöneticisi
│   │
│   ├── storage/               # Depolama katmanı
│   │   ├── __init__.py
│   │   └── repository.py      # Veri erişim nesnesi
│   │
│   ├── config/                # Konfigürasyon
│   │   ├── __init__.py
│   │   └── settings.py        # Uygulama ayarları
│   │
│   ├── utils/                 # Yardımcı modüller
│   │   ├── __init__.py
│   │   └── helpers.py         # Yardımcı fonksiyonlar
│   │
│   ├── app.py                 # Uygulama girişi
│   └── requirements.txt       # Bağımlılıklar
│
├── huggingface/               # Hugging Face dağıtım dosyaları
│   ├── app.py                 # Hugging Face uygulaması
│   └── requirements.txt       # Bağımlılıklar
│
└── README.md                  # Proje dokümantasyonu
```

## 3. Veri Akışı Diyagramı

```
+-------------+     1. Kural Oluşturma İsteği     +-------------+
|             |------------------------------>|             |
|  Kullanıcı  |                               |  Web        |
|             |<------------------------------|  Arayüzü    |
+-------------+     8. Oluşturulan Kural      +-------------+
                                                     |
                                                     | 2. API İsteği
                                                     v
                                              +-------------+
                                              |             |
                                              |  API        |
                                              |  Katmanı    |
                                              |             |
                                              +-------------+
                                                     |
                                                     | 3. LLM İsteği
                                                     v
                                              +-------------+
                                              |             |
                                              |  LLM        |
                                              |  Entegrasyon|
                                              |             |
                                              +-------------+
                                                     |
                                                     | 4. LLM Yanıtı
                                                     v
                                              +-------------+
                                              |             |
                                              |  Kural      |
                                              |  Oluşturma  |
                                              |  Motoru     |
                                              |             |
                                              +-------------+
                                                     |
                                                     | 5. Kural Kaydetme
                                                     v
                                              +-------------+
                                              |             |
                                              |  Depolama   |
                                              |  Katmanı    |
                                              |             |
                                              +-------------+
                                                     |
                                                     | 6. Kayıt Onayı
                                                     v
                                              +-------------+
                                              |             |
                                              |  API        |
                                              |  Katmanı    |
                                              |             |
                                              +-------------+
                                                     |
                                                     | 7. API Yanıtı
                                                     v
                                              +-------------+
                                              |             |
                                              |  Web        |
                                              |  Arayüzü    |
                                              |             |
                                              +-------------+
```

## 4. API Entegrasyon Stratejisi

### 4.1 Adaptör Deseni

Her LLM sağlayıcısı için ayrı bir adaptör sınıfı oluşturulacaktır. Tüm adaptörler ortak bir arayüzü uygulayacaktır:

```python
# adapter.py
from abc import ABC, abstractmethod

class LLMAdapter(ABC):
    """LLM sağlayıcıları için temel adaptör arayüzü."""
    
    @abstractmethod
    def initialize(self, api_key, **kwargs):
        """Adaptörü başlatır ve yapılandırır."""
        pass
    
    @abstractmethod
    def generate_rule(self, rule_type, description, content, parameters=None):
        """Belirtilen parametrelerle bir Cursor Rule oluşturur."""
        pass
    
    @abstractmethod
    def get_available_models(self):
        """Kullanılabilir modellerin listesini döndürür."""
        pass
    
    @abstractmethod
    def validate_api_key(self, api_key):
        """API anahtarının geçerliliğini doğrular."""
        pass
```

### 4.2 Fabrika Deseni

Kullanıcı seçimine göre doğru adaptörü oluşturmak için bir fabrika sınıfı kullanılacaktır:

```python
# factory.py
from .gemini_adapter import GeminiAdapter
from .openai_adapter import OpenAIAdapter
from .openrouter_adapter import OpenRouterAdapter

class LLMAdapterFactory:
    """LLM adaptörlerini oluşturmak için fabrika sınıfı."""
    
    @staticmethod
    def create_adapter(provider_name):
        """Belirtilen sağlayıcı için bir adaptör oluşturur."""
        if provider_name.lower() == "gemini":
            return GeminiAdapter()
        elif provider_name.lower() == "openai":
            return OpenAIAdapter()
        elif provider_name.lower() == "openrouter":
            return OpenRouterAdapter()
        else:
            raise ValueError(f"Desteklenmeyen sağlayıcı: {provider_name}")
```

### 4.3 Konfigürasyon Yönetimi

API anahtarları ve diğer ayarlar için merkezi bir konfigürasyon modülü kullanılacaktır:

```python
# settings.py
import os
from dotenv import load_dotenv

# .env dosyasını yükle
load_dotenv()

class Settings:
    """Uygulama ayarları."""
    
    # Uygulama ayarları
    APP_NAME = "Cursor Rules Generator"
    DEBUG = os.getenv("DEBUG", "False").lower() == "true"
    
    # API anahtarları
    GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "")
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
    OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY", "")
    
    # Varsayılan ayarlar
    DEFAULT_PROVIDER = os.getenv("DEFAULT_PROVIDER", "gemini")
    DEFAULT_RULE_TYPE = os.getenv("DEFAULT_RULE_TYPE", "Always")
    
    # Depolama ayarları
    STORAGE_TYPE = os.getenv("STORAGE_TYPE", "file")  # "file" veya "database"
    STORAGE_PATH = os.getenv("STORAGE_PATH", "./data")
    
    # Hugging Face dağıtım ayarları
    HF_SPACE_ID = os.getenv("HF_SPACE_ID", "")
    HF_TOKEN = os.getenv("HF_TOKEN", "")
```

## 5. Kural Oluşturma Motoru

Kural oluşturma motoru, LLM'lerden gelen yanıtları Cursor Rules formatına dönüştürecektir:

```python
# rule_generator.py
from .mdc_formatter import MDCFormatter
from .templates import TemplateManager

class RuleGenerator:
    """Cursor Rules oluşturma motoru."""
    
    def __init__(self):
        self.formatter = MDCFormatter()
        self.template_manager = TemplateManager()
    
    def create_rule(self, rule_type, description, content, parameters=None):
        """Belirtilen parametrelerle bir Cursor Rule oluşturur."""
        # Şablonu al
        template = self.template_manager.get_template(rule_type)
        
        # Parametreleri hazırla
        params = {
            "description": description,
            "content": content,
        }
        
        if parameters:
            params.update(parameters)
        
        # Şablonu doldur
        rule_content = template.format(**params)
        
        # MDC formatına dönüştür
        mdc_rule = self.formatter.format_to_mdc(rule_type, rule_content)
        
        return mdc_rule
```

### 5.1 MDC Formatı

MDC (Markdown with Context) formatı, Cursor Rules için kullanılan hafif bir formattır. Aşağıdaki yapıyı takip eder:

```
---
description: RPC Service boilerplate
globs: 
alwaysApply: false
---

- Use our internal RPC pattern when defining services
- Always use snake_case for service names.

@service-template.ts
```

## 6. Frontend Arayüzü

Frontend arayüzü, kullanıcıların kolayca Cursor Rules oluşturabilmesi için sezgisel bir form sunacaktır:

### 6.1 Ana Bileşenler

1. **LLM Sağlayıcı Seçimi**: Gemini, OpenRouter veya OpenAI seçimi
2. **API Anahtarı Girişi**: Seçilen sağlayıcı için API anahtarı
3. **Model Seçimi**: Seçilen sağlayıcının kullanılabilir modelleri
4. **Kural Tipi Seçimi**: Always, Auto Attached, Agent Requested veya Manual
5. **Kural Açıklaması**: Kuralın amacını açıklayan kısa bir açıklama
6. **Kural İçeriği**: Kuralın ana içeriği (metin editörü)
7. **Ek Parametreler**: Kural tipine göre değişen ek parametreler
8. **Önizleme**: Oluşturulan kuralın önizlemesi
9. **İndirme**: Oluşturulan kuralı indirme seçeneği

### 6.2 Kullanıcı Deneyimi Akışı

1. Kullanıcı LLM sağlayıcısını seçer
2. API anahtarını girer ve doğrular
3. Kullanılabilir modeller yüklenir ve kullanıcı bir model seçer
4. Kullanıcı kural tipini seçer
5. Kullanıcı kural açıklaması ve içeriğini girer
6. Kullanıcı ek parametreleri yapılandırır
7. Kullanıcı "Önizle" düğmesine tıklar ve oluşturulan kuralı görür
8. Kullanıcı "İndir" düğmesine tıklayarak kuralı indirir

## 7. Hugging Face Dağıtım Stratejisi

Uygulama, Hugging Face Spaces'e dağıtılacaktır. Dağıtım için aşağıdaki adımlar izlenecektir:

1. Hugging Face Spaces için özel bir `app.py` dosyası oluşturulacak
2. Gradio veya Streamlit arayüzü kullanılacak
3. Gerekli bağımlılıklar `requirements.txt` dosyasında belirtilecek
4. Hugging Face Spaces API kullanılarak otomatik dağıtım yapılacak

### 7.1 Hugging Face Uygulaması

```python
# app.py (Hugging Face)
import gradio as gr
from backend.llm.factory import LLMAdapterFactory
from backend.engine.rule_generator import RuleGenerator
from backend.config.settings import Settings

# Uygulama ayarları
settings = Settings()

# Kural oluşturucu
rule_generator = RuleGenerator()

def generate_rule(provider, api_key, model, rule_type, description, content, parameters):
    """Cursor Rule oluşturur."""
    try:
        # LLM adaptörünü oluştur
        adapter = LLMAdapterFactory.create_adapter(provider)
        
        # Adaptörü başlat
        adapter.initialize(api_key)
        
        # Kuralı oluştur
        rule = adapter.generate_rule(rule_type, description, content, parameters)
        
        return rule, None
    except Exception as e:
        return None, str(e)

# Gradio arayüzü
with gr.Blocks(title="Cursor Rules Oluşturucu") as demo:
    gr.Markdown("# Cursor Rules Oluşturucu")
    gr.Markdown("Gemini, OpenRouter, OpenAI API ve tüm modellerini destekleyen dinamik bir Cursor Rules oluşturucu.")
    
    with gr.Row():
        with gr.Column():
            provider = gr.Dropdown(
                choices=["Gemini", "OpenRouter", "OpenAI"],
                label="LLM Sağlayıcı",
                value="Gemini"
            )
            
            api_key = gr.Textbox(
                label="API Anahtarı",
                placeholder="API anahtarınızı girin",
                type="password"
            )
            
            model = gr.Dropdown(
                label="Model",
                placeholder="Önce API anahtarını doğrulayın"
            )
            
            rule_type = gr.Dropdown(
                choices=["Always", "Auto Attached", "Agent Requested", "Manual"],
                label="Kural Tipi",
                value="Always"
            )
            
            description = gr.Textbox(
                label="Kural Açıklaması",
                placeholder="Kuralın amacını açıklayan kısa bir açıklama"
            )
            
            content = gr.Textbox(
                label="Kural İçeriği",
                placeholder="Kuralın ana içeriği",
                lines=10
            )
            
            parameters = gr.JSON(
                label="Ek Parametreler (JSON)",
                placeholder="{}"
            )
            
            generate_btn = gr.Button("Kural Oluştur")
        
        with gr.Column():
            output = gr.Textbox(
                label="Oluşturulan Kural",
                lines=20
            )
            
            error = gr.Textbox(
                label="Hata Mesajı",
                visible=False
            )
            
            download_btn = gr.Button("İndir", visible=False)
    
    # API anahtarı doğrulama
    api_key.change(
        fn=lambda provider, api_key: get_models(provider, api_key),
        inputs=[provider, api_key],
        outputs=[model, error]
    )
    
    # Kural oluşturma
    generate_btn.click(
        fn=generate_rule,
        inputs=[provider, api_key, model, rule_type, description, content, parameters],
        outputs=[output, error]
    )
    
    # İndirme düğmesini göster/gizle
    output.change(
        fn=lambda output: gr.update(visible=bool(output)),
        inputs=[output],
        outputs=[download_btn]
    )

# Uygulamayı başlat
demo.launch()
```

## 8. Güvenlik ve Hata Yönetimi

### 8.1 API Anahtarı Güvenliği

- API anahtarları asla veritabanında düz metin olarak saklanmayacak
- Frontend'de API anahtarları geçici olarak tutulacak
- Hugging Face dağıtımında API anahtarları çevre değişkenleri olarak saklanacak

### 8.2 Hata Yönetimi

- Her katmanda kapsamlı hata yakalama ve işleme
- Kullanıcı dostu hata mesajları
- Detaylı günlük kaydı
- Yeniden deneme mekanizmaları

## 9. Genişletilebilirlik

Mimari, yeni LLM sağlayıcılarının kolayca eklenebilmesi için tasarlanmıştır:

1. Yeni bir adaptör sınıfı oluştur
2. Fabrika sınıfına yeni adaptörü ekle
3. Frontend'de yeni sağlayıcı seçeneğini ekle

Bu yaklaşım, uygulamanın gelecekteki LLM sağlayıcılarını ve modellerini desteklemek için minimum değişiklikle genişletilebilmesini sağlar.

## 10. Performans Optimizasyonu

- API çağrıları için önbelleğe alma
- Asenkron işleme
- Lazy loading
- Verimli veri yapıları

## 11. Sonuç

Bu mimari tasarım, Gemini, OpenRouter, OpenAI API ve tüm modellerini destekleyen dinamik bir Cursor Rules oluşturucu için kapsamlı bir çerçeve sunmaktadır. Tasarım, modülerlik, genişletilebilirlik ve kullanıcı deneyimi göz önünde bulundurularak oluşturulmuştur.