From cd9ecacec58c7ca432561ee0020df5cdbc294a1b Mon Sep 17 00:00:00 2001 From: Thorsten Sommer Date: Wed, 10 Dec 2025 20:15:41 +0100 Subject: [PATCH] Added CLAUDE.md with project setup and architecture details (#589) --- CLAUDE.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..14aba589 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,200 @@ +# 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 +```bash +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:** +```bash +cd runtime +cargo tauri dev --no-watch +``` + +**Terminal 2 - Start .NET app:** +```bash +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 +```bash +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 ` +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 <` +- **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