Skip to content
3 min read · 626 words

Frontend Overview

A thin, fast presentation layer: Next.js 15 App Router with React 19 server components for reads, one client component for the create-agent form, and a route-handler proxy for writes. No client state library, no CSS-in-JS — Tailwind tokens from a Material-inspired design system.

What the frontend does (and doesn't)

DoesDoesn't
Render the operations dashboard for an agentCall OpenAI (ever)
List agents with their config and toolsHold client-side app state beyond one form
Create agents through a proxied POSTImplement auth (none exists platform-wide)
Degrade gracefully when the backend is downPoll or stream — every view is fetch-on-render

Route map

RouteFileTypeData source
/app/page.tsxservernone — redirect("/dashboard")
/dashboardapp/dashboard/page.tsxserver (force-dynamic)GET {AGENTOPS_DASHBOARD_API_URL} (default: agent 1's dashboard)
/agentsapp/agents/page.tsxserver (force-dynamic)GET {AGENTOPS_AGENTS_API_URL}
/create-agentapp/create-agent/page.tsxserver shell + client formPOST /api/agents (proxy)
/api/agentsapp/api/agents/route.tsroute handlerforwards to backend POST /agents/

Loading states (loading.tsx) exist for /dashboard and /agents; /dashboard also has an error.tsx boundary.

Rendering diagram…

Section pages

[Pages](pages.md)Every route: what it fetches, how it renders, and its loading/error behavior.Pages [Components](components.md)All seven components — Sidebar, Topbar, StatCard, PerformanceCard, RecentActivity, AgentCard, CreateAgentForm — with props and usage.Components [API Proxy](api-proxy.md)The backend-for-frontend pattern in `app/api/agents/route.ts` and why writes go through it.API Proxy [Design System](design-system.md)The Material-inspired token system from `DESIGN.md`: colors, typography, spacing, elevation.Design System [Data Fetching](data-fetching.md)Server-component fetching, `force-dynamic`, `no-store`, and the (minimal) state management story.Data Fetching

Stack

ConcernChoice
FrameworkNext.js ^15.3 (App Router)
UIReact ^19
StylingTailwind CSS ^3.4 with custom tokens
LanguageTypeScript ^5.7 (npm run typecheck)
FontsInter (text), JetBrains Mono (code/mono), Material Symbols Outlined (icons) — loaded from Google Fonts in app/layout.tsx
StateReact useState in one client component; everything else server-rendered

There is no test runner or linter configured — see Testing.

Conventions

New backend endpoints exposed to the browser get a matching route handler under app/api/**/route.ts rather than being called directly from client components — same-origin requests, no CORS, backend URL stays server-side. Walkthrough: Add an Endpoint.

New UI uses the token classes (bg-surface-container-lowest, text-on-surface-variant, font-label-md, spacing like p-stack-md) — not raw hex values or arbitrary sizes. Reference: Design System.

Current limitations (documented, not hidden)

  • The dashboard is pinned to agent 1 unless AGENTOPS_DASHBOARD_API_URL says otherwise.
  • AgentCard's Open button links to /agents/{id} — a route that does not exist yet; Edit/Run buttons are inert.
  • Sidebar's "Workflows" and "Operations" sections are href="#" placeholders.
  • The dashboard's bar/line charts render static sample shapes, not live series (only the cost figure is real).

All tracked in Known Issues and the Roadmap.

PreviousError HandlingNextPages