# Architecture

## Overview

loco-web-admin is a SvelteKit web application for managing the infrastructure of AI agents. Users manage agents and their dependencies (models, tools, skills, knowledge bases, memory, ...) through the web UI. The backend persists all resources as Kubernetes Custom Resources (CRs) via a GitOps repository, reads live runtime status directly from the K8s API server. A separate K8s operator (out of scope) reconciles the infrastructure.

loco-web-admin is mainly used for observability for all users and management for advanced users. To manage resources, using AI agents in the GitOps repository is recommended over using this web UI directly. The GitOps repository is the SSoT and all changes will be reflected on the UI for further inspections and modifications.

loco-web-admin can be deployed locally for local development or as a PaaS with multi-tenancy.

```
┌──────────────────────────────────────────────────────────┐
│                        Browser                           │
│   ┌──────────────────────────────────────────────────┐   │
│   │              SvelteKit Frontend                  │   │
│   └─────────────────────┬────────────────────────────┘   │
└─────────────────────────┼────────────────────────────────┘
                          │ HTTP
┌─────────────────────────▼────────────────────────────────┐
│                  SvelteKit Backend                       │
│       (auth, multi-tenancy, resource management, ...)    │
└──────┬─────────────────────────────────┬─────────────────┘
       │ Git API                         │ K8s API
       │ (CRUD via CRs + PRs)            │ (live status)
┌──────▼──────┐                   ┌──────▼──────┐
│  Git Repo   │                   │ K8s API     │
│  (GitOps)   │                   │ Server      │
└─────────────┘                   └──────┬──────┘
                                         │
                                  ┌──────▼───────┐
                                  │ K8s Operator │ ← out of scope
                                  │              │
                                  └──────────────┘
```

## Domain Model

Core entities:

- **Stack**, a collection of all essential components required for running agents (such as gateway, database, vector store, ...) that are shared among agents and other components
- **Model**, a self-hosted or a third-party API for model inference, including language models, embedding models, and reranker models
- **Tool**, a self-hosted or a third-party MCP server
- **Knowledge Base**, a self-hosted or third-party API for retrieval (and RAG pipeline)
- **Skill**, a bundle of definitions for a reusable agent skill
- **Memory**, a self-hosted database for short-term agent memory
- **Agent**, a self-hosted instance of an AI agent

| Primitive          | Answers                                                     |
| ------------------ | ----------------------------------------------------------- |
| **Model**          | How does the agent reason/generate?                         |
| **Tool**           | How does the agent act on external systems?                 |
| **Knowledge Base** | What external/static information can it retrieve?           |
| **Skill**          | How does the agent perform a reusable capability?           |
| **Memory**         | What has it learned or experienced?                         |
| **Agent**          | What autonomous reasoning loop composes these capabilities? |

## GitOps Flow

1. User creates/edits an agent (or other resource) in the UI
2. On "Save", the backend renders a K8s CR YAML containing the full spec
3. Backend commits the CR file in the configured Git repository
4. Backend calls the K8s API server to create/patch the resource
5. The K8s operator (out of scope) picks up the CR and reconciles the components

## Route Structure

```
/api/workspaces                                                  → workspaces available to the user
/api/workspaces/[workspaceId]/[resource=resource]                → list/create resource entities
/api/workspaces/[workspaceId]/[resource=resource]/[id]           → get/update/delete resource entities
/api/workspaces/[workspaceId]/[resource=resource]/[id]/status    → live status from K8s resources
/api/workspaces/[workspaceId]/[resource=resource]/[id]/changes   → Git history and change context
/api/workspaces/[workspaceId]/[resource=resource]/[id]/resources → child K8s resources (deployments/pods/services)

/workloads/models                       → model management
/workloads/tools                        → tool management
/workloads/kbs                          → knowledge base management
/workloads/skills                       → skill management
/workloads/memories                     → memory management
/workloads/agents                       → agent management

/auth/login                                                   → credential-based sign-in page
/auth/logout                                                  → session clear + redirect
```

## Frontend Stack

| Layer      | Technology               |
| ---------- | ------------------------ |
| Framework  | SvelteKit 5 (Runes mode) |
| Language   | TypeScript (strict)      |
| Styling    | Tailwind CSS v4          |
| Unit tests | Vitest (browser + node)  |
| E2E tests  | Playwright               |
| Linting    | ESLint + Prettier        |

## Key Modules

### `src/lib/server/`

Server modules for initialization, auth, workspace management, Git-backed catalog, and K8s resource access.

### `src/routes/api/workspaces/`

SvelteKit endpoint handlers that bridge HTTP requests to workspace-scoped catalog/resources operations.

### `src/lib/components/`

Reusable UI components shared across routes (forms, selectors, tables, badges).

## Multi-tenancy

Resources are isolated into workspaces. User has access to one or more workspaces.

Only one workspace will be active in local mode.

## Authentication

File-based credential auth (JWT cookie) is enabled when auth env vars are configured; otherwise auth is bypassed with a local default admin user.