​
Vedaya UI

​
Table of Contents

​
Introduction

Vedaya UI is a sophisticated frontend application built with SvelteKit that provides a modern, responsive interface for interacting with various AI models and services. The application serves as a complete AI playground and workspace environment, allowing users to create, manage, and interact with AI-powered features including chat interfaces, code execution, data visualization, and more.

The UI is designed with a focus on performance, extensibility, and user experience, leveraging the latest web technologies to deliver a seamless and intuitive interface for AI interactions.

​
Architecture Overview

Vedaya UI follows a component-based architecture built on the SvelteKit framework. The application employs a modular design pattern that separates concerns across different layers:

​
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

This layered approach ensures separation of concerns, making the codebase maintainable, testable, and scalable.

​
Technology Stack

Vedaya UI leverages a modern web 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

Vedaya UI provides a comprehensive set of features designed to enable powerful AI interactions:

​
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

The Vedaya UI codebase follows a structured organization that facilitates navigation and maintenance:

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

The component system in Vedaya UI is built with reusability, composability, and performance in mind. Components are organized into logical groupings:

​
Layout Components

Located in src/lib/components/layout/, these handle the overall structure of the application, including:

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

​
Common Components

Located in src/lib/components/common/, these are the building blocks of the UI:

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

​
Feature-specific Components

Organized by feature area (chat, workspace, playground, etc.), these implement specific application features:

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

​
Component Architecture

Each component follows a consistent pattern:

  • 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

Vedaya UI uses Svelte’s built-in stores system for state management, providing a reactive and efficient approach to handling application state:

​
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

State persistence is implemented using various strategies:

  • 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

Vedaya UI connects to backend services through a comprehensive API layer located in src/lib/apis/. This layer abstracts the complexity of API calls and provides a clean interface for components to interact with server resources.

​
API Organization

APIs are organized by domain:

  • 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

Real-time features are powered by Socket.io, providing:

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

​
Internationalization

Vedaya UI implements a comprehensive internationalization system using i18next:

​
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

The theming system provides visual customization with seamless switching between light, dark, and system preference modes:

​
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

Theme switching is implemented with minimal flicker by:

  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

The authentication system supports multiple providers and implements a secure, seamless login experience:

​
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

Vedaya UI incorporates Pyodide to enable Python execution directly in the browser:

​
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

Real-time features are implemented using Socket.io:

​
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

The development environment is configured for an optimal developer experience:

​
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

For containerized 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

Vedaya UI implements a comprehensive 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

Tests are organized by feature area and testing level, with a focus on critical paths and user interactions.

​
Building and Deployment

Vedaya UI uses a static site generation approach with SvelteKit’s adapter-static:

​
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

The GitHub Actions workflow automates:

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

​
Performance Optimizations

Vedaya UI implements various 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

Contributions to Vedaya UI are welcome! Please see the CONTRIBUTING.md file for guidelines.

​
Troubleshooting

For common issues and their solutions, please refer to the TROUBLESHOOTING.md file.

This documentation provides an in-depth overview of the Vedaya UI architecture, features, and implementation details. For specific questions or issues, please refer to the documentation or open an issue on the repository.