​

Vedaya UI

​

Table of Contents

• Introduction
• Architecture Overview
• Technology Stack
• Core Features
• Codebase Structure
• UI Components
• State Management
• API Integration
• Internationalization
• Theme System
• Authentication Flow
• Python Integration with Pyodide
• Real-time Communication
• Development Workflow
• Testing Strategy
• Building and Deployment
• Performance Optimizations
• Contributing
• Troubleshooting

​

Introduction

​

Architecture Overview

​

Frontend Architecture Layers

1. Presentation Layer
   • Svelte components (UI elements, layouts, pages)
   • Theme system (light/dark/system themes)
   • Animation and transitions
2. Application Layer
   • State management (Svelte stores)
   • Route handling (SvelteKit routing)
   • Event handling and user interactions
3. Domain Layer
   • Business logic
   • Data transformation and validation
   • Service interfaces
4. Infrastructure Layer
   • API clients (REST, WebSocket)
   • Authentication
   • Storage (local, session, indexedDB)
   • Analytics and monitoring
5. Cross-Cutting Concerns
   • Internationalization (i18n)
   • Error handling
   • Logging
   • Configuration management

​

Technology Stack

• Core Framework
  • SvelteKit 2.x: A framework for building high-performance web applications
  • Vite: Next generation frontend tooling for faster builds and development
• UI and Styling
  • Tailwind CSS 4.x: Utility-first CSS framework for rapid UI development
  • SASS: For advanced styling capabilities
  • Tippy.js: For tooltips and popovers
  • Bits UI: Component primitives for Svelte
• State Management
  • Svelte stores: For reactive and persistent state management
• Code Editing and Visualization
  • CodeMirror 6: For code editing capabilities
  • TipTap: For rich text editing
  • Mermaid: For diagram visualization
  • Xyflow: For node-based flow visualization
• Data Handling and Processing
  • Pyodide: For running Python code in the browser
  • Socket.io: For real-time communications
  • DayJS: For date manipulation
  • File-saver: For handling file downloads
• AI and Machine Learning
  • Transformers.js: For running transformer models directly in the browser
  • MediaPipe: For vision-related ML tasks
• Authentication
  • MSAL Browser: Microsoft Authentication Library for browser-based authentication
• Testing and Quality Assurance
  • Cypress: For end-to-end testing
  • Vitest: For unit and integration testing
  • TypeScript: For static type checking
  • ESLint and Prettier: For code quality and formatting

​

Core Features

​

1. Multi-model AI Chat Interface

• Support for various AI models (OpenAI, local models via Ollama, and more)
• Chat history management
• Message formatting with markdown and code highlighting
• File attachments and context sharing

​

2. Workspace Environment

• Multi-workspace support with isolated contexts
• File management system
• Collaborative features

​

3. Knowledge Management

• Document storage and retrieval
• Context-aware AI interactions
• Memory systems for persistent context

​

4. Code Execution

• In-browser Python execution via Pyodide
• Code highlighting and intelligent editing
• Output visualization and interactive notebooks

​

5. Visual Playground

• Flow-based visual programming interface
• Node-based model chaining
• Visual debugging and execution tracking

​

6. Authentication and User Management

• Multi-provider authentication
• User profile management
• Role-based access control

​

7. Theme System

• Light/dark mode support
• System preference detection
• Customizable theme components

​

8. Internationalization

• Multi-language support
• Automatic language detection
• Translation management

​

9. Media Processing

• Image generation and manipulation
• Audio transcription and processing
• Document parsing and analysis

​

10. Real-time Collaboration

• Socket-based real-time updates
• Presence indicators
• Collaborative editing

​

Codebase Structure

src/
├── app.css                # Global CSS styles
├── app.html               # HTML template with theme handling
├── app.d.ts               # TypeScript declarations
├── tailwind.css           # Tailwind CSS entry point
├── lib/                   # Shared library code
│   ├── apis/              # API integration layer
│   ├── components/        # Reusable UI components
│   ├── stores/            # State management stores
│   ├── utils/             # Utility functions
│   ├── actions/           # Svelte actions
│   ├── constants.ts       # Application constants
│   ├── i18n/              # Internationalization
│   ├── themes/            # Theme definitions
│   ├── themeLoader.ts     # Theme loading logic
│   ├── pyodide/           # Python integration
│   ├── types/             # TypeScript type definitions
│   └── workers/           # Web Workers
├── routes/                # SvelteKit routes
│   ├── +layout.svelte     # Root layout
│   ├── +layout.js         # Layout load function
│   ├── +error.svelte      # Error handling
│   ├── auth/              # Authentication routes
│   ├── (app)/             # Main application routes
│   ├── s/                 # Sharing routes
│   ├── watch/             # Monitoring routes
│   └── vedaya/            # Core functionality routes
└── scripts/               # Build and utility scripts

​

UI Components

​

Layout Components

• Navigation bars
• Sidebars
• Panels
• Splitters
• Responsive containers

​

Common Components

• Buttons and input controls
• Cards and containers
• Modals and dialogs
• Tooltips and popovers
• Loading indicators

​

Feature-specific Components

• Chat interfaces
• Code editors
• File browsers
• Visual programming nodes
• Profile management

​

Component Architecture

• Props interface for type-safe property passing
• Event dispatching for parent-child communication
• Self-contained styles using Tailwind utility classes
• Reactive statements for handling state changes
• Lifecycle hooks for setup and cleanup

​

State Management

​

Store Types

1. Writable Stores: For state that can be modified from any component
2. Readable Stores: For derived state that depends on other stores
3. Derived Stores: For computed values based on other stores
4. Local Stores: For component-specific state

​

Key Stores

• Authentication Store: Manages user session and authentication state
• Theme Store: Handles theme preferences and switching
• Workspace Store: Manages current workspace context and settings
• Chat Store: Handles chat messages, history, and interactions
• Model Store: Manages available AI models and their configurations
• File Store: Tracks uploaded and generated files
• Settings Store: Handles user preferences and application settings
• Notification Store: Manages system notifications and alerts

​

Persistence

• LocalStorage for user preferences and settings
• SessionStorage for temporary session data
• IndexedDB for larger datasets and offline capabilities
• Server synchronization for critical user data

​

API Integration

​

API Organization

• Authentication (auths/)
• Chat interactions (chats/)
• File management (files/)
• Model management (models/)
• User management (users/)
• Tool integration (tools/)
• Knowledge management (knowledge/)

​

Implementation Details

• Base Client: A foundational client that handles common concerns like authentication, error handling, and request/response formatting
• Domain-specific Clients: Specialized clients for each domain area
• Request/Response Types: TypeScript interfaces for type-safe API interactions
• Error Handling: Consistent error handling with appropriate fallbacks
• Caching: Strategic caching for performance optimization
• Retry Logic: Automatic retry for transient failures
• Streaming: Support for streaming responses from AI models

​

WebSocket Integration

• Bi-directional communication
• Event-based messaging
• Reconnection handling
• Room-based collaboration

​

Internationalization

​

Features

• Multi-language Support: Built-in support for multiple languages
• Automatic Detection: Language detection based on browser settings
• Runtime Switching: On-the-fly language switching without reload
• Namespace Organization: Logically organized translation namespaces
• Formatting: Date, number, and currency formatting
• Pluralization: Proper handling of plural forms
• Context-based Translations: Support for context-specific translations

​

Implementation

• Translation files are stored in src/lib/i18n/
• A parser script extracts translatable strings from the codebase
• The i18next library provides the core translation functionality
• Browser language detection is used for initial language selection
• User language preferences are persisted in local storage

​

Theme System

​

Theme Implementation

• Theme Definitions: Located in src/lib/themes/
• ThemeLoader: Handles runtime theme switching via src/lib/themeLoader.ts
• CSS Variables: Dynamic CSS variables for consistent theming
• Tailwind Integration: Theme colors mapped to Tailwind config
• System Preference Detection: Media query tracking for system theme changes
• User Preference: User-selected theme stored in local storage

​

Theme Switching

1. Setting theme before DOM rendering
2. Using CSS transitions for smooth color changes
3. Persisting theme preference in localStorage
4. Detecting and reacting to system preference changes

​

Authentication Flow

​

Authentication Providers

• Email/Password authentication
• Social login (Google, GitHub, etc.)
• Microsoft authentication via MSAL
• Token-based authentication for API access

​

Authentication Process

1. Login Initiation: User selects authentication method
2. Provider Authentication: Redirect or popup-based auth flow with the selected provider
3. Token Exchange: Exchange provider token for application token
4. Session Establishment: Store tokens and establish user session
5. Profile Loading: Load user profile and preferences
6. Route Navigation: Redirect to appropriate destination

​

Security Features

• Token refresh mechanisms
• Secure token storage
• CSRF protection
• Session timeout handling
• Logout functionality

​

Python Integration with Pyodide

​

Implementation Details

• Initialization: Pyodide is loaded asynchronously on demand
• Package Management: Python packages are installed at runtime as needed
• Code Execution: Python code is executed in an isolated environment
• Input/Output Handling: Redirected stdin/stdout for interactive execution
• File System Integration: Virtual file system for reading/writing files
• Error Handling: Python exceptions are captured and presented to the user
• Interruption: Long-running code can be interrupted
• State Persistence: Python environment state can be saved and restored

​

Use Cases

• Data analysis and visualization
• Machine learning model training and inference
• Script execution and automation
• Educational demonstrations and tutorials

​

Real-time Communication

​

Socket Management

• Connection management with automatic reconnection
• Room-based communication for multi-user scenarios
• Event-based message handling
• Binary data transfer for efficient file sharing

​

Real-time Features

• Live chat with typing indicators
• Collaborative document editing
• Presence awareness in workspaces
• Real-time notifications
• Progress tracking for long-running operations

​

Development Workflow

​

Setup and Installation

# Clone the repository
git clone https://github.com/vedaya/vedaya-ui.git
cd vedaya-ui

# Install dependencies
npm install

# Start development server
npm run dev

​

Development Commands

• npm run dev: Start development server
• npm run build: Build for production
• npm run preview: Preview production build
• npm run check: Run TypeScript checks
• npm run lint: Run linting
• npm run format: Format code
• npm run i18n:parse: Update translation files
• npm run test:frontend: Run frontend tests

​

Docker Development

# Start with Docker Compose
docker-compose up -d

# Development with GPU support
docker-compose -f docker-compose.yaml -f docker-compose.gpu.yaml up -d

​

Testing Strategy

​

Testing Layers

1. Unit Tests: Testing individual functions and components
2. Integration Tests: Testing component interactions
3. End-to-End Tests: Testing complete user flows

​

Testing Tools

• Vitest: For unit and integration testing
• Cypress: For end-to-end testing
• Svelte Testing Library: For component testing
• Mock Service Worker: For API mocking

​

Test Organization

​

Building and Deployment

​

Build Process

1. Preprocessing: Svelte and TypeScript compilation
2. Bundling: Dependency bundling and code splitting
3. Optimization: Asset optimization and minification
4. Static Generation: Generation of static HTML, CSS, and JS
5. Manifest Generation: Creation of service worker and manifest files

​

Deployment Options

• Static Hosting: Deploy to any static hosting service
• Docker Deployment: Use the provided Docker configuration
• Kubernetes: Deploy using Kubernetes manifests in the kubernetes/ directory

​

CI/CD Pipeline

• Dependency installation
• Code linting and checking
• Test execution
• Build process
• Deployment to production and staging environments

​

Performance Optimizations

​

Loading Performance

• Code Splitting: Route-based and component-based code splitting
• Preloading: Strategic preloading of critical resources
• Lazy Loading: Deferred loading of non-essential features
• Asset Optimization: Image and asset optimization
• Critical CSS: Inline critical CSS for faster rendering

​

Runtime Performance

• Virtual Lists: Efficient rendering of large lists
• Memoization: Caching of expensive computations
• Web Workers: Offloading intensive operations to background threads
• Efficient Rendering: Minimizing DOM operations
• Animation Optimization: Hardware-accelerated animations

​

Network Optimization

• Caching: Strategic API response caching
• Compression: Gzip/Brotli compression
• Bundling: Efficient module bundling
• Prefetching: Smart prefetching of likely-to-be-needed resources

​

Contributing

​

Troubleshooting