# Design ## Detailed Design Docs Component-level design docs live under `specs/designs/`, organized by category: ``` specs/designs/ ├── 00-foundation/ — core server infrastructure (server lifecycle, auth, config) └── 01-data/ — external data sources (Git, Kubernetes) ``` --- ## Domain Models The UI maintains a stable set of domain models — its canonical, backend-agnostic representation of each resource, used by all forms and stores. They are an intermediate representation: they translate to and from the Custom Resources of whichever backend the deployment targets — the platform's own operator, or a community standard such as kagent or KServe. Field-level detail is defined in the individual entity design specs. ### External vs Managed Every major resource type exists in two variants that the UI must handle: - **External**: third-party or externally hosted (e.g. the OpenAI API, a SaaS MCP server). The requests will be proxied via a Gateway. The user provides an endpoint URL and credentials. - **Managed**: deployed in-cluster by the operator (e.g. a self-hosted llama.cpp model, a custom MCP server). The user provides a container image reference and configuration; the operator manages the Deployment. The UI unifies each pair into a single entity concept with a variant discriminator. Form fields and validation rules differ by variant. ### Core Entities - **Model** — an LLM provider configuration (language, embedding, or reranker). Holds provider identity, endpoint, credentials, and inference defaults. - **Tool** — an MCP server endpoint. Holds the URL, transport type, and authentication method. - **Knowledge Base** — a RAG data source. Holds chunking strategy, embedding model reference, and indexed document configuration. - **Skill** - a collection of prompts and configurations for a reusable skill that will be mounted onto agents. - **Memory** - a service for storing and retrieving shared transient/short-term memories. - **Agent** — the primary deployable unit. References a model, a set of tools, a set of skills, a set of memories, and a set of knowledge bases. ### Supporting Entities - **Stack** - Shared components such as gateway and databases. - **Secret** - API keys for third-party authentications. --- ## Core User Flows Two major paths are supported: ### Manual - Search for a component (model, tool, knowledge base, skill, memory, agent, ...) - Create, read, update, or delete a component - Inspect the live status of a deployed component - Test a component - Check and manage the cost generated by a component ### AI-Assisted - All manual operations, but initiated and driven through the embedded AI chatbot - Ask questions about the platform, configuration options, and the UI itself --- ## Multi-tenancy The platform is designed for shared use across multiple teams. Each team operates within a **workspace** — an isolated namespace that owns its own models, tools, knowledge bases, skills, memories, and agents. Workspace membership and permissions are managed through the workspace settings. --- ## Information Architecture ### Sitemap ``` Home ├── Playground │ ├── Session list │ └── [Session] → Active chat session with a selected agent ├── Usage │ ├── Cost dashboard │ └── Cost settings ├── Utilities │ ├── Agent test │ ├── Knowledge base test │ ├── Tool (MCP) test │ └── Model test ├── Workloads │ ├── Agents │ │ ├── Agent list │ │ ├── New agent │ │ └── [Agent] │ │ ├── Detail & status │ │ └── Edit │ ├── Memories │ │ ├── Memory list │ │ ├── New memory │ │ └── [Memory] │ │ ├── Detail & status │ │ └── Edit │ ├── Skills │ │ ├── Skill list │ │ ├── New skill │ │ └── [Skill] │ │ ├── Detail & definitions │ │ └── Edit │ ├── Knowledge Bases │ │ ├── Knowledge base list │ │ ├── New knowledge base │ │ └── [Knowledge Base] │ │ ├── Detail & documents & status │ │ └── Edit │ ├── Tools │ │ ├── Tool list │ │ ├── New tool │ │ └── [Tool] │ │ ├── Detail & status │ │ └── Edit │ ├── Models │ │ ├── Model list │ │ ├── New model │ │ └── [Model] │ │ ├── Detail & status │ │ └── Edit │ └── Stacks │ ├── Stack list │ ├── New Stack │ └── [Stack] │ ├── Detail & status │ └── Edit ├── Workspace settings └── User settings ``` ### Application Shell The shell is a three-column layout: ``` ┌──────────┬─────────────────────────────────┬───────────┐ │ │ Top bar │ │ │ ├─────────────────────────────────┤ │ │ Sidebar │ │ Assistant │ │ │ Main content │ panel │ │ │ │ │ │ │ │ │ └──────────┴─────────────────────────────────┴───────────┘ ``` - **Sidebar** (left): primary navigation — workspace switcher, section links, user menu. Collapsible to an icon rail to maximise content width. - **Main content** (center): page content with a top bar carrying the page title, breadcrumbs, and contextual actions. - **AI assistant panel** (right): persistent but collapsed by default; expands as a fixed-width drawer. --- ## UI Principles - **Clarity over decoration**: no gratuitous animations or chrome. Every element earns its space. - **Inline editing**: prefer editing in-place over separate edit pages where feasible. - **Immediate feedback**: loading states, optimistic updates, clear error messages. - **CR transparency**: users can always see the YAML their config will produce. - **Desktop-first**: primary use case is a developer at a workstation. --- ## Visual Design ### Component Library **shadcn-svelte** is the component library. Components are installed into `$lib/components/controls/` via the shadcn-svelte CLI and customized in place. Do not wrap shadcn components in extra abstraction layers — edit them directly when customization is needed. shadcn-svelte uses **bits-ui** for headless primitives and is fully compatible with Svelte 5 Runes. ### Aesthetic Dark theme with a **Glassmorphism** aesthetic: frosted-glass panels floating over a gradient mesh background. Card, dialog, and popover surfaces use `backdrop-filter` blur with semi-transparent fills. The background is a deep navy with subtle radial gradient accents. ### Color System - Accent / primary: oklch(0.496 0.265 301.924) - Glass surfaces: low-opacity fills with subtle white borders - Status colors: blue (open), green (healthy), slate (pending), red (error), amber (warning) ### Elevation & Depth Three glass levels of increasing blur and opacity: background panels → cards/forms → dialogs/popovers. ### Icons Lucide via `lucide-svelte`. Slightly muted at rest, full opacity on hover/active.