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

{
  "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

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)

   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

<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

   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

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

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

@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

interface Variable {
  name: string;
  source: 'intent' | 'api' | 'system';
  type: string;
}

Features:

• Categorized dropdown
• Search functionality
• Type indicators
• Copy to clipboard

3. JSON Editor Wrapper

@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

interface ConfirmData {
  title: string;
  message: string;
  confirmText?: string;
  cancelText?: string;
  dangerous?: boolean;
}

🎯 Services Architecture

Core Services

// 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

@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

// 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

.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

$mobile: 640px;
$tablet: 768px;
$desktop: 1024px;
$wide: 1280px;

Mobile Adaptations

• Collapsible sidebar
• Bottom sheet dialogs
• Touch-optimized controls
• Simplified layouts

🚀 Performance Optimizations

Lazy Loading

const routes: Routes = [
  {
    path: 'projects',
    loadChildren: () => import('./projects/projects.module')
      .then(m => m.ProjectsModule)
  }
];

Change Detection

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})

Virtual Scrolling

<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

{
  "production": {
    "optimization": true,
    "sourceMap": false,
    "namedChunks": false,
    "extractLicenses": true,
    "vendorChunk": false
  }
}

Environment Files

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