The operator-facing admin UI lives in its own repository: spora-ai/spora-frontend. It is a Vue 3 single-page application built with Vite, shipped as a Composer package (spora-frontend, type spora-frontend), and served by the Spora host out of public/dist/.

This document covers how the frontend is structured, how it talks to the backend, and where to plug in new pages and apps.

Tech stack

Concern	Choice	Notes
Framework	Vue 3 (<script setup>)	Composition API everywhere; SFCs are the unit of reuse.
Build tool	Vite	npm run dev for HMR, npm run build for production.
Language	TypeScript (vue-tsc)	Strict mode; npm run build runs vue-tsc before bundling.
Styling	Tailwind CSS + radix-vue primitives	Utility-first; radix-vue supplies accessible headless components (dialogs, dropdowns, tooltips).
State	Pinia	One store per resource; composables wrap derived state.
Icons	lucide-vue-next	Tree-shaken; the shared <Icon> component resolves names from the lucide palette.
HTTP	fetch via the shared api/client.ts	Same envelope handling as the backend ({ data } / { error }).
Routing	vue-router 4	Route guards read the auth store.

Build & deploy

From spora-frontend/:

npm install
npm run dev      # Vite dev server with HMR (proxies /api/v1 to the host)
npm run build    # vue-tsc + vite build → dist/
npm run lint     # ESLint
npm test         # Vitest

The operator skeleton pulls the prebuilt spora-frontend Composer package, which lands at public/dist/. The host serves dist/index.html and dist/assets/* directly — there is no Node runtime in production.

Build provenance: the package’s composer.json ships a dist/ directory containing the Vite output. Operators do not run npm install / npm run build in production; rebuilding the frontend happens in the spora-frontend repo and is published as a new tag of the spora-frontend Composer package.

Talking to the backend

All HTTP traffic goes through one client: src/api/client.ts. It handles:

• Base URL — import.meta.env.VITE_API_URL (empty string in production; the SPA is served from the same origin as the API).
• CSRF — X-CSRF-Token header injected on POST/PUT/PATCH/DELETE, sourced from the auth store. Falls back to GET /auth/me when the token is missing but the user looks logged in.
• Session expiry — setupSessionHandler() lets the router register a callback that fires on a 401 UNAUTHENTICATED response, so the user gets a single toast instead of a flood of failures.
• Envelope unwrapping — body.data ?? body returns the inner payload transparently; body.error is parsed into an ApiError (with code, status, message) and thrown.
• Logging — request() routes 5xx to log.error, 4xx to log.warn, and 401 to log.debug (the toast is the user-facing signal).

Pages never call fetch directly — they import api from @/api/client:

import { api } from '@/api/client'

const { agents } = await api.get<{ agents: Agent[] }>('/agents')
await api.post('/agents', { name: 'Researcher', prompt: '...' })

ApiError carries code and status so UI code can branch on machine-readable failures. There is no per-field error map on the class — the envelope is { error: { code, message } }, so VALIDATION_ERROR (HTTP 422) arrives as a single human-readable message for the page to render inline:

try {
  await api.post('/agents', payload)
} catch (e) {
  if (e instanceof ApiError && e.code === 'VALIDATION_ERROR') {
    formError.value = e.message
  } else {
    toast.error(e.message)
  }
}

Forms that want per-field errors derive them client-side during local validation (as AgentToolOverrideForm.vue does with its own local fieldErrors ref) — they are not read off the ApiError. The full envelope, the complete error code registry, and the toast mapping are on the Error handling page.

Composables

Composables in src/composables/ hold cross-cutting logic that doesn’t belong in a Pinia store but is reused by multiple pages. Two are wired into nearly every page:

useAdminAuth()

Returns reactive isAdmin and isForbidden flags derived from the auth store’s user.is_admin. Pages use it to gate admin-only UI (tool settings, plugin management, etc.) without re-reading the auth store directly:

const { isAdmin, isForbidden } = useAdminAuth()

<template>
  <section v-if="isAdmin">…</section>
  <div v-else-if="isForbidden" class="text-muted-foreground">…</div>
</template>

useFeatureEnabled(key)

Resolves a runtime feature flag against the public config (GET /api/v1/config). Returns a computed boolean that flips when the user reloads or the config refreshes. Use it for opt-in features that operators toggle via environment variables — for example, the Web-UI plugin installer is only shown when SPORA_PLUGIN_INSTALL_ENABLED=true, so its mount point reads:

const pluginInstallEnabled = useFeatureEnabled('plugin_install')

<RouterLink v-if="pluginInstallEnabled" :to="{ name: 'plugins-install' }">
  Install plugin
</RouterLink>

Why a composable, not a constant? Feature flags can change at runtime (the config endpoint is polled by some admin flows). Hiding the link in a computed keeps the UI honest without forcing a full refresh.

Pinia stores

One store per resource, defined in src/stores/. Convention:

• State is plain ref()s (agents, loading, error).
• Actions are async functions that call api.* and translate ApiError into a user-readable message.
• No normalisation — stores keep the shape the backend returns, so resource objects round-trip cleanly through SSR/serialisation if we ever add it.

Stores expose a load() action that pages call from onMounted and from refresh buttons. App-scoped stores (e.g. the plugin inventory at src/apps/plugins/stores/plugins.ts) live under their app folder, not in the global stores/.

Sub-task cache (sub_agent op)

The useTaskStore exposes a reactive sub-task cache for the SubAgentTool sub_agent op (src/stores/tasks.ts). subTaskCache: Map<number, TaskDetail> is keyed by child task id; fetchSubTaskDetail(id) populates it via GET /api/v1/tasks/{id} and SSE updates for non-active task ids patch the cached entry in place via applyTaskUpdate so per-row status badges flip live without a re-fetch. clearSubTaskCache() empties the map on TaskChatPage unmount so child rows do not leak across parent visits.

TaskDetail.data

The TaskDetail.data field is a free-form JSON column (snake_case, per the backend data JSON column convention) carrying tool-specific side-channel payloads. Today it is read by TaskChatMessageList to deep-link the “Handed off to …” final-response pill to the target agent via data.handover.{target_agent_id, target_agent_name} (the backend also writes target_task_id for lineage, but the chat UI no longer consumes it), and by TaskChatPage to drive the sub-agent count badge via data.spawned_sub_task_ids: number[]. Vue components normalise the snake_case payload into camelCase locals — consumers should not hard-code snake_case field access in templates.

The apps/ directory — extending the frontend

Each “app” is a self-contained bundle of pages, components, types, stores, and an API client. The pattern keeps feature work isolated — adding a new top-level page (e.g. Plugins) does not touch the rest of the app.

flowchart TD
    root["src/apps/"]
    plugins["plugins/"]
    api["api/<br/>typed wrappers around<br/>/api/v1/plugins/*"]
    components["components/<br/>PluginCard,<br/>MigrationStatusBadge,<br/>PluginDetailDialog"]
    pages["pages/<br/>PluginsPage.vue<br/>(mounted by the router)"]
    stores["stores/<br/>Pinia store for plugin<br/>inventory state"]
    types["types/<br/>PluginResource,<br/>MigrationInfo, etc."]

    root --> plugins
    plugins --> api
    plugins --> components
    plugins --> pages
    plugins --> stores
    plugins --> types

    classDef root fill:var(--spora-paper),stroke:var(--spora-warm),color:var(--spora-ink),font-weight:bold
    classDef app fill:var(--spora-paper-deep),stroke:var(--spora-warm-deep),color:var(--spora-ink),font-weight:bold
    classDef child fill:var(--spora-cream),stroke:var(--spora-warm-mist),color:var(--spora-ink)
    class root root
    class plugins app
    class api,components,pages,stores,types child

Use plugins/ as the template for new apps

When you add a new top-level page:

1. Create a folder under src/apps/<your-app>/.
2. Mirror the layout: api/, components/, pages/, stores/, types/.
3. Define resource shapes in types/ and mirror them on the backend (PluginsService ↔ PluginResource).
4. Register the page in src/router/index.ts under a clear route name and gate it behind a composable if it requires an admin or a feature flag.
5. Add tests alongside the source (*.test.ts co-located with the module they cover).

The existing plugins/ app is the canonical reference implementation — read it before adding a new one.

Routing

src/router/index.ts declares every page. Routes use named navigation guards for auth and admin gating:

{
  path: '/admin/plugins',
  name: 'admin-plugins',
  component: () => import('@/apps/plugins/pages/PluginsPage.vue'),
  meta: { requiresAdmin: true },
}

The global guard reads meta.requiresAdmin / meta.requiresAuth and short-circuits to /login or /403 accordingly.

Where to look next

• src/api/client.ts — every HTTP call in the app routes through this module.
• src/composables/useAdminAuth.ts — the canonical admin-gate pattern.
• src/composables/useFeatureEnabled.ts — runtime feature flags from /api/v1/config.
• src/components/agent/TaskChat/SubAgentToolCall.vue — the row widget rendered when the Orchestrator records a sub_agent op (one row per spawned child, live status from subTaskCache).
• src/apps/plugins/ — the template for adding a new top-level app.
• src/stores/auth.ts — session, login, CSRF token.

Edit this page on GitHub

Contributors: Fabian Graßl

Previous pageError handling

Next pageInterfaces