Upload 2 files

docs/flare-tasarim.md

@@ -0,0 +1,444 @@
+# Flare Platform - Güncel Tasarım Dokümanı
+
+## 🏗 Genel Mimari
+
+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.
+
+### 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
+
+## 📋 Konfigürasyon Yapısı
+
+### 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
+}
+```
+
+### Provider Sistemi
+
+#### 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"
+}
+```
+
+#### Provider Settings
+```json
+{
+  "name": "provider_name",
+  "api_key": "enc:encrypted_key",
+  "endpoint": "https://endpoint",
+  "settings": {
+    // Provider-specific ayarlar
+  }
+}
+```
+
+### 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
+}
+```
+
+### 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ı"
+}
+```
+
+### 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"
+}
+```
+
+## 🔄 Session ve State Yönetimi
+
+### 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
+```
+
+### State Machine Flow
+```
+start_session → welcome_prompt
+     ↓
+    idle ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←
+     ↓                                             ↑
+detect_intent → collect_params → approval? → call_api → humanize
+                      ↑              ↓
+                      ← await_param ←
+```
+
+## 🔐 Onay Mekanizması
+
+Intent'te `requiresApproval: true` olduğunda:
+
+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
+
+## 🌍 Multi-Language Destek
+
+### Locale Yönetimi
+- Project seviyesinde `default_locale` ve `supported_locales`
+- LocalizedExample ve LocalizedCaption yapıları
+- Locale JSON dosyaları (`tr.json`, `en.json`, vb.)
+
+### 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")
+```
+
+## 🎤 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)
+```
+
+## 📡 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}"
+```
+
+## 🔒 Güvenlik
+
+### Encryption
+- API key'ler `enc:` prefix ile şifrelenmiş saklanır
+- Fernet encryption (symmetric)
+- Environment variable: `FERNET_KEY`
+
+### Authentication
+- JWT-based session yönetimi
+- Bcrypt password hashing
+- Session timeout kontrolü
+
+### Race Condition Koruması
+- `last_update_date` ile optimistic locking
+- Thread-safe session store
+- Concurrent update kontrolü
+
+## 📊 Monitoring ve Logging
+
+### Activity Log
+```json
+{
+  "timestamp": "2024-01-01T00:00:00Z",
+  "username": "admin",
+  "action": "CREATE_PROJECT",
+  "entity_type": "project",
+  "entity_id": 1,
+  "entity_name": "project_name",
+  "details": "Additional info"
+}
+```
+
+### 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
+
+## 🧪 Test ve Development
+
+### Mock Backend
+- Scenario-based testing
+- Configurable responses
+- Error simulation
+
+### Debug Features
+- Detailed timestamped logging
+- Request/Response tracking
+- Performance metrics
+
+## 🔄 Import/Export
+
+### Project Export Format
+```json
+{
+  "name": "project_name",
+  "caption": "Project Caption",
+  "icon": "folder",
+  "description": "Description",
+  "default_locale": "tr",
+  "supported_locales": ["tr", "en"],
+  "versions": [
+    {
+      "caption": "v1",
+      "general_prompt": "...",
+      "llm": {...},
+      "intents": [...]
+    }
+  ]
+}
+```
+
+## 🚦 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
+```
+
+### Health Check
+```python
+@app.get("/")
+def health():
+    return {"status": "ok"}
+
+# Hugging Face için daemon thread
+threading.Thread(target=run_health_server, daemon=True).start()
+```

docs/flare-ui-tasarim.md

@@ -0,0 +1,605 @@
+# Flare Administration UI - Güncel Tasarım Dokümanı
+
+## 📌 Genel Bakış
+
+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.
+
+## 🏗 Teknik Altyapı
+
+### Frontend Stack
+```json
+{
+  "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"
+}
+```
+
+### Backend Integration
+- RESTful API endpoints
+- JWT Authentication (`X-Auth-Token` header)
+- Real-time updates (WebSocket - planned)
+- File upload/download (import/export)
+
+## 🎨 UI Yapısı
+
+### 1. Layout Structure
+```
+┌────────────────────────────────────────────────────┐
+│  Flare Admin    [Environment] [User ▼] [Logout]    │  <- Header
+├────────────────────────────────────────────────────┤
+│ Projects | APIs | Users | Logs | [Config ⚙]        │  <- Tab Bar
+├────────────────────────────────────────────────────┤
+│                                                    │
+│                 [Tab Content]                      │  <- Content Area
+│                                                    │
+└────────────────────────────────────────────────────┘
+```
+
+### 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;
+}
+```
+
+**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: [...]        │
+└─────────────────┴────────────────────────┘
+```
+
+**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>
+```
+
+**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;
+}
+```
+
+**Visual JSON Path Builder:**
+- Upload sample response
+- Click to build path
+- Real-time validation
+- Type inference
+
+### 5. Environment Configuration
+
+#### Provider Management
+```
+┌─────────────────────────────────────────┐
+│ LLM Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ ⚡ Spark LLM          [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│ TTS Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ 🔊 ElevenLabs        [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│ STT Provider                            │
+│ ┌─────────────────────────────────────┐ │
+│ │ 🎤 Google STT        [Configure ▼] │ │
+│ └─────────────────────────────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+**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;
+}
+```
+
+**Features:**
+- Infinite scroll
+- Real-time updates
+- Filter by action/user/date
+- Export functionality
+- Detailed view dialog
+
+### 7. Test Console
+
+#### 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    │
+└─────────────────────────────────────────┘
+```
+
+**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();
+}
+```
+
+### 2. Variable Selector
+```typescript
+interface Variable {
+  name: string;
+  source: 'intent' | 'api' | 'system';
+  type: string;
+}
+```
+
+**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>
+  `
+})
+```
+
+### 4. Confirmation Dialog
+```typescript
+interface ConfirmData {
+  title: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  dangerous?: boolean;
+}
+```
+
+## 🎯 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>
+}
+
+// Authentication
+@Injectable()
+export class AuthService {
+  login(credentials: LoginData): Observable<AuthResponse>
+  logout(): void
+  getToken(): string | null
+  isAuthenticated(): boolean
+}
+
+// Environment state
+@Injectable()
+export class EnvironmentService {
+  ttsEnabled$: BehaviorSubject<boolean>
+  sttEnabled$: BehaviorSubject<boolean>
+  currentProvider$: BehaviorSubject<ProviderInfo>
+}
+```
+
+### 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);
+  }
+}
+```
+
+## 🎨 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
+  )
+));
+```
+
+### 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;
+  }
+}
+```
+
+## 📱 Responsive Design
+
+### 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)
+  }
+];
+```
+
+### Change Detection
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+```
+
+### Virtual Scrolling
+```html
+<cdk-virtual-scroll-viewport itemSize="50">
+  <div *cdkVirtualFor="let item of items">
+    {{ item }}
+  </div>
+</cdk-virtual-scroll-viewport>
+```
+
+## 🔒 Security Considerations
+
+### XSS Prevention
+- Sanitized HTML rendering
+- Template validation
+- CSP headers
+
+### Authentication Flow
+```
+Login → JWT Token → Local Storage → HTTP Header → API Validation
+         ↓                ↓
+     Redirect        Auto Logout
+```
+
+### Sensitive Data
+- Encrypted API keys (visual: `•••••••xyz`)
+- No plaintext passwords
+- Secure cookie options
+
+## 🧪 Testing Strategy
+
+### Unit Tests
+- Component logic
+- Service methods
+- Pipe transformations
+
+### E2E Tests
+- User workflows
+- API integration
+- Error scenarios
+
+## 📊 Analytics and Monitoring
+
+### User Activity Tracking
+- Feature usage metrics
+- Performance timing
+- Error reporting
+
+### Dashboard Metrics
+- Active projects count
+- API call statistics
+- User engagement
+
+## 🚦 Deployment
+
+### Build Configuration
+```json
+{
+  "production": {
+    "optimization": true,
+    "sourceMap": false,
+    "namedChunks": false,
+    "extractLicenses": true,
+    "vendorChunk": false
+  }
+}
+```
+
+### Environment Files
+```typescript
+// environment.prod.ts
+export const environment = {
+  production: true,
+  apiUrl: '/api',
+  wsUrl: 'wss://flare.example.com'
+};
+```
+
+## 🔄 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%+