docs/flare-ui-tasarim.md

# 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%+