AI-Studio/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MindWork AI Studio is a cross-platform desktop application for interacting with Large Language Models (LLMs). The app uses a hybrid architecture combining a Rust Tauri runtime (for the native desktop shell) with a .NET Blazor Server web application (for the UI and business logic).

Key Architecture Points:

• Runtime: Rust-based Tauri v1.8 application providing the native window, system integration, and IPC layer
• App: .NET 9 Blazor Server application providing the UI and core functionality
• Communication: The Rust runtime and .NET app communicate via HTTPS with TLS certificates generated at startup
• Providers: Multi-provider architecture supporting OpenAI, Anthropic, Google, Mistral, Perplexity, self-hosted models, and others
• Plugin System: Lua-based plugin system for language packs, configuration, and future assistant plugins

Building and Running

Prerequisites

• .NET 9 SDK
• Rust toolchain (stable)
• Tauri v1.6.2 CLI: cargo install --version 1.6.2 tauri-cli
• Tauri prerequisites (platform-specific dependencies)
• Note: Development on Linux is discouraged due to complex Tauri dependencies that vary by distribution

One-Time Setup

cd app/Build
dotnet run build

This builds the .NET app as a Tauri "sidecar" binary, which is required even for development.

Development Workflow

Run these commands in separate terminals:

Terminal 1 - Start Rust runtime:

cd runtime
cargo tauri dev --no-watch

Terminal 2 - Start .NET app:

cd "app/MindWork AI Studio"
dotnet run

The app will start in the Tauri window. Hot reload is supported for .NET code changes.

Building for Production

cd app/Build
dotnet run build

Creates a release build for the current platform and architecture. Output is in runtime/target/release/.

Running Tests

Currently no automated test suite exists in the repository.

Architecture Details

Rust Runtime (runtime/)

Entry point: runtime/src/main.rs

Key modules:

• app_window.rs - Tauri window management, updater integration
• dotnet.rs - Launches and manages the .NET sidecar process
• runtime_api.rs - Rocket-based HTTPS API for .NET ↔ Rust communication
• certificate.rs - Generates self-signed TLS certificates for secure IPC
• secret.rs - Secure secret storage using OS keyring (Keychain/Credential Manager)
• clipboard.rs - Cross-platform clipboard operations
• file_data.rs - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.)
• encryption.rs - AES-256-CBC encryption for sensitive data
• pandoc.rs - Integration with Pandoc for document conversion
• log.rs - Logging infrastructure using flexi_logger

.NET App (app/MindWork AI Studio/)

Entry point: app/MindWork AI Studio/Program.cs

Key structure:

• Program.cs - Bootstraps Blazor Server, configures Kestrel, initializes encryption and Rust service
• Provider/ - LLM provider implementations (OpenAI, Anthropic, Google, Mistral, etc.)
  • BaseProvider.cs - Abstract base for all providers with streaming support
  • IProvider.cs - Provider interface defining capabilities and streaming methods
• Chat/ - Chat functionality and message handling
• Assistants/ - Pre-configured assistants (translation, summarization, coding, etc.)
  • AssistantBase.razor - Base component for all assistants
• Agents/ - contains all agents, e.g., for data source selection, context validation, etc.
  • AgentDataSourceSelection.cs - Selects appropriate data sources for queries
  • AgentRetrievalContextValidation.cs - Validates retrieved context relevance
• Tools/PluginSystem/ - Lua-based plugin system
• Tools/Services/ - Core background services (settings, message bus, data sources, updates)
• Tools/Rust/ - .NET wrapper for Rust API calls
• Settings/ - Application settings and data models
• Components/ - Reusable Blazor components
• Pages/ - Top-level page components

IPC Communication Flow

1. Rust runtime starts and generates TLS certificate
2. Rust starts internal HTTPS API on random port
3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key
4. .NET reads environment variables and establishes secure HTTPS connection to Rust
5. .NET requests an app port from Rust, starts Blazor Server on that port
6. Rust opens Tauri webview pointing to localhost:app_port
7. Bi-directional communication: .NET ↔ Rust via HTTPS API

Configuration and Metadata

• metadata.txt - Build metadata (version, build time, component versions) read by both Rust and .NET
• startup.env - Development environment variables (generated by build script)
• .NET project reads metadata.txt at build time and injects as assembly attributes

Plugin System

Location: app/MindWork AI Studio/Plugins/

Plugins are written in Lua and provide:

• Language plugins - I18N translations (e.g., German language pack)
• Configuration plugins - Enterprise IT configurations for centrally managed providers, settings
• Future: Assistant plugins for custom assistants

Example configuration plugin: app/MindWork AI Studio/Plugins/configuration/plugin.lua

Plugins can configure:

• Self-hosted LLM providers
• Update behavior
• Preview features visibility
• Preselected profiles
• Chat templates

RAG (Retrieval-Augmented Generation)

RAG integration is currently in development (preview feature). Architecture:

• External Retrieval Interface (ERI) - Contract for integrating external data sources
• Data Sources - Local files and external data via ERI servers
• Agents - AI agents select data sources and validate retrieval quality
• Embedding providers - Support for various embedding models
• Vector database - Planned integration with Qdrant for vector storage
• File processing - Extracts text from PDF, DOCX, XLSX via Rust runtime

Enterprise IT Support

AI Studio supports centralized configuration for enterprise environments:

• Registry (Windows) or environment variables (all platforms) specify configuration server URL and ID
• Configuration downloaded as ZIP containing Lua plugin
• Checks for updates every ~16 minutes via ETag
• Allows IT departments to pre-configure providers, settings, and chat templates

Documentation: documentation/Enterprise IT.md

Provider Confidence System

Multi-level confidence scheme allows users to control which providers see which data:

• Confidence levels: e.g. NONE, LOW, MEDIUM, HIGH, and some more granular levels
• Each assistant/feature can require a minimum confidence level
• Users assign confidence levels to providers based on trust

Implementation: app/MindWork AI Studio/Provider/Confidence.cs

Dependencies and Frameworks

Rust:

• Tauri 1.8 - Desktop application framework
• Rocket 0.5 - HTTPS API server
• tokio - Async runtime
• keyring - OS keyring integration
• pdfium-render - PDF text extraction
• calamine - Excel file parsing

.NET:

• Blazor Server - UI framework
• MudBlazor 8.12 - Component library
• LuaCSharp - Lua scripting engine
• HtmlAgilityPack - HTML parsing
• ReverseMarkdown - HTML to Markdown conversion

Security

• Encryption: AES-256-CBC with PBKDF2 key derivation for sensitive data
• IPC: TLS-secured communication with random ports and API tokens
• Secrets: OS keyring for persistent secret storage (API keys, etc.)
• Sandboxing: Tauri provides OS-level sandboxing

Release Process

1. Create changelog file: app/MindWork AI Studio/wwwroot/changelog/vX.Y.Z.md
2. Commit changelog
3. Run from app/Build: dotnet run release --action <patch|minor|major>
4. Create PR with version bump and changes
5. After PR merge, maintainer creates git tag: vX.Y.Z
6. GitHub Actions builds release binaries for all platforms
7. Binaries uploaded to GitHub Releases

Important Development Notes

• File changes require Write/Edit tools - Never use bash commands like cat <<EOF or echo >
• Spaces in paths - Always quote paths with spaces in bash commands
• Debug environment - Reads startup.env file with IPC credentials
• Production environment - Runtime launches .NET sidecar with environment variables
• MudBlazor - Component library requires DI setup in Program.cs
• Encryption - Initialized before Rust service is marked ready
• Message Bus - Singleton event bus for cross-component communication inside the .NET app