DESIGN.md 7.7 KB
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)
├── 10-layout/ — overall UI designs
└── 11-models/ — model page designs
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.