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