Skip to content

README.md

Latest commit

 

History

History
112 lines (89 loc) · 7.11 KB

README.md

File metadata and controls

112 lines (89 loc) · 7.11 KB

Services Module

LOC Complexity

The services module contains the TypeScript client layer for the gglib GUI frontends. These services provide a unified API for both Desktop (Tauri) and Web (Axum) platforms.

Architecture

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              React Components                                       │
└──────────────────────────────────────┬──────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                             services/ (This Module)                                 │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │  clients/   │  │ transport/  │  │  platform/  │  │   tools/    │                 │
│  │  API layer  │  │ HTTP/Tauri  │  │ OS-specific │  │MCP tooling  │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │   server/   │  │    api/     │  │  registry   │  │   events    │                 │
│  │ Safe calls  │  │   Routes    │  │Server state │  │Event bridge │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                       │
               ┌───────────────────────┼───────────────────────┐
               ▼                       ▼                       ▼
       ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
       │ Tauri (IPC)  │        │ Axum (HTTP)  │        │ SSE Events   │
       └──────────────┘        └──────────────┘        └──────────────┘

Directory Structure

Directory Description
clients/ API client functions for each domain (models, servers, chat, downloads, etc.)
transport/ Platform-agnostic transport layer (Tauri IPC vs HTTP) with type mappers
platform/ Platform-specific utilities (file dialogs, URL opening, menu sync)
tools/ MCP tool integration and builtin tool registry
server/ Safe action wrappers for server operations
api/ Route definitions for API endpoints

Key Files

File Description
serverRegistry.ts External store for server lifecycle state. Uses useSyncExternalStore for reactive React integration.
serverEvents.ts Platform adapter that initializes Tauri events (desktop). Web uses unified SSE transport.
serverEvents.tauri.ts Listens to Tauri server:* events and ingests them into the registry

Clients

The clients/ directory contains domain-specific API functions:

Client Description
chat.ts Chat completion and conversation management
downloads.ts Download queue operations and progress tracking
events.ts Event subscription and handling
huggingface.ts HuggingFace Hub search and model discovery
mcp.ts MCP server configuration management
models.ts Model CRUD operations
servers.ts llama-server lifecycle management
settings.ts Application settings
system.ts System information and probes
tags.ts Model tagging operations

Server Event Types

Events are the source of truth for server state. All events flow from the Rust backend:

Event Description
server:snapshot Initial state of all running servers (emitted on app init)
server:started Server started and ready
server:stopped Server stopped cleanly
server:error Server encountered an error
server:health_changed Server health status changed

Platform Utilities

The platform/ directory provides OS-specific functionality:

Utility Description
detect.ts Platform detection (Tauri vs Web)
fileDialogs.ts Native file picker integration
llamaInstall.ts llama.cpp installation helpers
menuEvents.ts Native menu bar event handling
menuSync.ts Menu state synchronization
openUrl.ts External URL opening
serverLogs.ts Server log streaming

Transport Layer

The transport/ directory provides a unified interface for backend communication:

  • Tauri mode: Uses @tauri-apps/api/core.invoke() for IPC
  • Web mode: Uses standard HTTP fetch with the Axum API

This abstraction ensures identical behavior across platforms while allowing each to use its optimal transport mechanism.