How bluenot3/agent-arena-template works
1. What this repo is
- A TypeScript React + Vite single-page control center for AI agents.
- It is built for static hosting and uses HashRouter, so it does not depend on server-side route rewrites.
2. Top-level composition
- App.tsx and index.tsx bootstrap the app.
- The app is organized around an AppShell layout rather than a page-only structure.
- That shell gives the app its major regions: left navigation dock, top bar, center workspace, and right inspector.
3. Navigation and page architecture
- The app is route-first: most major experiences live in pages/.
- Core routes include Dashboard, Agents, Agent Detail, Marketplace, Labs, Settings, Workspace, plus specialty builders and studios like BotBuilder, ImageStudio, GameLab, ArenaDesigner, AppForge, KeysVault, KnowledgeVault.
- The shell keeps navigation persistent while the route content changes in the center workspace.
4. Domain model boundary
- models/agent.ts and types.ts define the canonical domain objects.
- The README names the main entities as Agent, AgentVersion, ModelConfig, ToolConfig, and UsageEvent.
- This is the main contract layer shared by pages, store logic, and services.
5. Global state and agent lifecycle
- stores/AgentStore.tsx is the central state boundary.
- It uses a context + reducer pattern for agent CRUD, versioning, and run simulation.
- The store is the main source of truth for selected agent state, agent lists, and “last run” style contextual data used by the inspector.
6. Persistence and registry
- Persistence is local-first via localStorage, implemented in services/agentRegistry.ts.
- This service layer is the key swap point for later moving to Firebase or a backend API.
- The architecture intentionally keeps UI/store contracts stable so only the service implementation changes when storage changes.
7. Services layer
- services/ contains the app’s non-UI capabilities: AI access, model catalog, web search/web intel, artifact preview, instrumentation, and agent insights.
- services/instrumentation.ts provides an event-tracking API (trackEvent) for usage and product analytics hooks.
- services/llm.ts and services/ai.ts are the likely integration boundary for model execution, while modelCatalog.ts and webSearch.ts/webintel.ts support model and retrieval-oriented features.
8. UI system and interaction primitives
- components/ui/ is the shared design system: button, card, badge, input, modal, tabs, toast, tooltip, skeleton, and globe.
- Higher-level shared components such as Layout, AppShell, Logo, BrandLogos, and AppErrorBoundary compose the app chrome and resilience layer.
- This separation keeps presentation primitives isolated from feature flows.
9. Agent creation and operational flows
- The Create Agent flow is a dedicated multi-step experience in components/agents/CreateAgentWizard.tsx.
- Related feature components like ModelSelector, WalletConnectButton, CheckoutModal, UpgradeModal, CustomActionModal, MagicEnhancer, XRayVision, ArtifactPane indicate the app supports agent configuration, enhancement, inspection, and monetization-related interactions.
- The right inspector in the shell is a distinct context surface for selected-agent details and quick actions.
10. Marketplace, subscription, and access management
- Pages like Marketplace, Subscription, KeysVault, and Settings suggest the product includes plan/access management and user-managed credentials.
- The presence of checkout/upgrade UI implies a billing boundary, but the app remains browser-side and BYOK-oriented per the README.
- Secrets are expected to stay out of the client bundle; user-supplied keys are managed locally through settings flows.
11. Labs and legacy surfaces
- pages/LabsPage.tsx preserves access to older interactive experiences.
- This makes Labs a compatibility zone for experimental tools and legacy pages while the core app shifts toward the newer route-first shell.
12. Build/runtime constraints
- The app is configured with TypeScript strictness gating via tsc --noEmit before production build.
- The overall architecture assumes client-only execution, with local persistence, static deployment, and no backend dependency required for the Phase 1 template.
Main entry points: App.tsx App · AgentStore.tsx Agent Store · AppShell.tsx AppShell · ai.ts AI Services
Components 23
Bootstrap
Client entry and app composition
Shell
Persistent app chrome and shared UI
- AppShell · Persistent navigation and workspace layout
components/shell/AppShell.tsx - Layout · Shared outer layout wrapper
components/Layout.tsx - Error Boundary · UI fault isolation
components/AppErrorBoundary.tsx - UI Kit · Shared presentation primitives
components/ui/Button.tsx
Pages
Route-driven experiences
- Dashboard · Main overview page
pages/DashboardPage.tsx - Agents · Agent list and management
pages/AgentsPage.tsx - Agent Detail · Selected agent workspace
pages/AgentDetailPage.tsx - Marketplace · Catalog and upgrade surface
pages/MarketplacePage.tsx - Labs · Experimental and legacy experiences
pages/LabsPage.tsx - Settings · Preferences and access management
pages/SettingsPage.tsx - Workspace · General working area
pages/Workspace.tsx - Bot Builder · Agent creation and tuning
pages/BotBuilder.tsx
Domain
Canonical agent model and state
- Agent Store · Context and reducer for agent lifecycle
stores/AgentStore.tsx - Agent Model · Canonical agent entities and types
models/agent.ts - Types · Cross-cutting type definitions
types.ts
Services
Local-first persistence and AI/integration layer
- Registry · LocalStorage-backed agent persistence
services/agentRegistry.ts - Instrumentation · Event tracking API
services/instrumentation.ts - AI Services · LLM and agent intelligence boundary
services/ai.ts - Model Catalog · Available model definitions and selection data
services/modelCatalog.ts - Web Search · Search and web intel services
services/webSearch.ts - Agent Insights · Derived agent analysis and recommendations
services/agentInsights.ts
Connections 26
- Entry → App: bootstraps · Client entry mounts the root app
- App → AppShell: wraps · App composes the persistent shell
- AppShell → Layout: uses · Shell is built on shared layout
- AppShell → Error Boundary: guards · Shell is protected by error boundary
- AppShell → UI Kit: renders with · Shell and pages use shared UI primitives
- App → Dashboard: routes to · App routes into main dashboard experience
- App → Agents: routes to · App routes to agent management
- App → Agent Detail: routes to · App routes to selected agent detail
- App → Marketplace: routes to · App routes to marketplace
- App → Labs: routes to · App routes to labs
- App → Settings: routes to · App routes to settings
- App → Workspace: routes to · App routes to workspace
- App → Bot Builder: routes to · App routes to builder flow
- Agent Store → Agent Model: stores · State is shaped by canonical agent schema
- Agent Store → Types: shares · Store uses shared types across features
- Agent Store → Registry: persists via · Reducer state is saved to local registry
- Registry → Instrumentation: records · Persistence and actions can emit tracking events
- AI Services → Model Catalog: uses · AI features depend on model catalog metadata
- AI Services → Web Search: uses · AI features can pull web intel/retrieval data
- Agent Insights → Agent Store: reads · Insights are derived from current agent state
- Dashboard → Agent Store: consumes · Dashboard reads global agent state
- Agents → Agent Store: consumes · Agent list is backed by store state
- Agent Detail → Agent Store: consumes · Detail view uses selected agent and last run context
- Bot Builder → Agent Store: creates · Builder drives agent creation through the store
- Marketplace → AI Services: depends on · Marketplace experience can invoke AI-backed features
- Settings → Registry: configures · Settings manage local credentials and saved data