# bluenot3/agent-arena-template architecture

> Architecture diagram of the GitHub repository bluenot3/agent-arena-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluenot3/agent-arena-template
- Repository: https://github.com/bluenot3/agent-arena-template

## Overview

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`](https://github.com/bluenot3/agent-arena-template/blob/main/App.tsx) (App), [`stores/AgentStore.tsx`](https://github.com/bluenot3/agent-arena-template/blob/main/stores/AgentStore.tsx) (Agent Store), [`components/shell/AppShell.tsx`](https://github.com/bluenot3/agent-arena-template/blob/main/components/shell/AppShell.tsx) (AppShell), [`services/ai.ts`](https://github.com/bluenot3/agent-arena-template/blob/main/services/ai.ts) (AI Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_bootstrap["Bootstrap"]
  node_node_app["App<br/>bootstrap<br/>[App.tsx]"]
  node_node_index["Entry<br/>bootstrap<br/>[index.tsx]"]
end

subgraph group_group_shell["Shell"]
  node_node_shell["AppShell<br/>layout<br/>[AppShell.tsx]"]
  node_node_layout["Layout<br/>chrome<br/>[Layout.tsx]"]
  node_node_error_boundary["Error Boundary<br/>resilience"]
  node_node_ui["UI Kit<br/>design system<br/>[Button.tsx]"]
end

subgraph group_group_pages["Pages"]
  node_node_dashboard["Dashboard<br/>route<br/>[DashboardPage.tsx]"]
  node_node_agents["Agents<br/>route<br/>[AgentsPage.tsx]"]
  node_node_agent_detail["Agent Detail<br/>route"]
  node_node_marketplace["Marketplace<br/>route"]
  node_node_labs["Labs<br/>route<br/>[LabsPage.tsx]"]
  node_node_settings["Settings<br/>route<br/>[SettingsPage.tsx]"]
  node_node_workspace["Workspace<br/>route<br/>[Workspace.tsx]"]
  node_node_botbuilder["Bot Builder<br/>route<br/>[BotBuilder.tsx]"]
end

subgraph group_group_domain["Domain"]
  node_node_agent_store[("Agent Store<br/>state<br/>[AgentStore.tsx]")]
  node_node_agent_model["Agent Model<br/>domain schema<br/>[agent.ts]"]
  node_node_types["Types<br/>[types.ts]"]
end

subgraph group_group_services["Services"]
  node_node_agent_registry[("Registry<br/>local persistence<br/>[agentRegistry.ts]")]
  node_node_instrumentation["Instrumentation<br/>analytics hooks<br/>[instrumentation.ts]"]
  node_node_ai["AI Services<br/>model integration<br/>[ai.ts]"]
  node_node_catalog["Model Catalog<br/>model metadata<br/>[modelCatalog.ts]"]
  node_node_search["Web Search<br/>retrieval<br/>[webSearch.ts]"]
  node_node_insights["Agent Insights<br/>[agentInsights.ts]"]
end

node_node_index -->|"bootstraps"| node_node_app
node_node_app -->|"wraps"| node_node_shell
node_node_shell -->|"uses"| node_node_layout
node_node_shell -->|"guards"| node_node_error_boundary
node_node_shell -->|"renders with"| node_node_ui
node_node_app -->|"routes to"| node_node_dashboard
node_node_app -->|"routes to"| node_node_agents
node_node_app -->|"routes to"| node_node_agent_detail
node_node_app -->|"routes to"| node_node_marketplace
node_node_app -->|"routes to"| node_node_labs
node_node_app -->|"routes to"| node_node_settings
node_node_app -->|"routes to"| node_node_workspace
node_node_app -->|"routes to"| node_node_botbuilder
node_node_agent_store -->|"stores"| node_node_agent_model
node_node_agent_store -->|"shares"| node_node_types
node_node_agent_store -->|"persists via"| node_node_agent_registry
node_node_agent_registry -.->|"records"| node_node_instrumentation
node_node_ai -->|"uses"| node_node_catalog
node_node_ai -->|"uses"| node_node_search
node_node_insights -->|"reads"| node_node_agent_store
node_node_dashboard -->|"consumes"| node_node_agent_store
node_node_agents -->|"consumes"| node_node_agent_store
node_node_agent_detail -->|"consumes"| node_node_agent_store
node_node_botbuilder -->|"creates"| node_node_agent_store
node_node_marketplace -.->|"depends on"| node_node_ai
node_node_settings -->|"configures"| node_node_agent_registry

click node_node_app "https://github.com/bluenot3/agent-arena-template/blob/main/App.tsx"
click node_node_index "https://github.com/bluenot3/agent-arena-template/blob/main/index.tsx"
click node_node_shell "https://github.com/bluenot3/agent-arena-template/blob/main/components/shell/AppShell.tsx"
click node_node_layout "https://github.com/bluenot3/agent-arena-template/blob/main/components/Layout.tsx"
click node_node_error_boundary "https://github.com/bluenot3/agent-arena-template/blob/main/components/AppErrorBoundary.tsx"
click node_node_ui "https://github.com/bluenot3/agent-arena-template/blob/main/components/ui/Button.tsx"
click node_node_agent_store "https://github.com/bluenot3/agent-arena-template/blob/main/stores/AgentStore.tsx"
click node_node_agent_model "https://github.com/bluenot3/agent-arena-template/blob/main/models/agent.ts"
click node_node_types "https://github.com/bluenot3/agent-arena-template/blob/main/types.ts"
click node_node_agent_registry "https://github.com/bluenot3/agent-arena-template/blob/main/services/agentRegistry.ts"
click node_node_instrumentation "https://github.com/bluenot3/agent-arena-template/blob/main/services/instrumentation.ts"
click node_node_ai "https://github.com/bluenot3/agent-arena-template/blob/main/services/ai.ts"
click node_node_catalog "https://github.com/bluenot3/agent-arena-template/blob/main/services/modelCatalog.ts"
click node_node_search "https://github.com/bluenot3/agent-arena-template/blob/main/services/webSearch.ts"
click node_node_insights "https://github.com/bluenot3/agent-arena-template/blob/main/services/agentInsights.ts"
click node_node_dashboard "https://github.com/bluenot3/agent-arena-template/blob/main/pages/DashboardPage.tsx"
click node_node_agents "https://github.com/bluenot3/agent-arena-template/blob/main/pages/AgentsPage.tsx"
click node_node_agent_detail "https://github.com/bluenot3/agent-arena-template/blob/main/pages/AgentDetailPage.tsx"
click node_node_marketplace "https://github.com/bluenot3/agent-arena-template/blob/main/pages/MarketplacePage.tsx"
click node_node_labs "https://github.com/bluenot3/agent-arena-template/blob/main/pages/LabsPage.tsx"
click node_node_settings "https://github.com/bluenot3/agent-arena-template/blob/main/pages/SettingsPage.tsx"
click node_node_workspace "https://github.com/bluenot3/agent-arena-template/blob/main/pages/Workspace.tsx"
click node_node_botbuilder "https://github.com/bluenot3/agent-arena-template/blob/main/pages/BotBuilder.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_app,node_node_index toneBlue
class node_node_shell,node_node_layout,node_node_error_boundary,node_node_ui toneAmber
class node_node_dashboard,node_node_agents,node_node_agent_detail,node_node_marketplace,node_node_labs,node_node_settings,node_node_workspace,node_node_botbuilder toneMint
class node_node_agent_store,node_node_agent_model,node_node_types toneRose
class node_node_agent_registry,node_node_instrumentation,node_node_ai,node_node_catalog,node_node_search,node_node_insights toneIndigo
```

## Components

### Bootstrap

Client entry and app composition

- [App](https://github.com/bluenot3/agent-arena-template/blob/main/App.tsx): bootstrap · Application root composition · `App.tsx`
- [Entry](https://github.com/bluenot3/agent-arena-template/blob/main/index.tsx): bootstrap · Vite/React client entrypoint · `index.tsx`

### Shell

Persistent app chrome and shared UI

- [AppShell](https://github.com/bluenot3/agent-arena-template/blob/main/components/shell/AppShell.tsx): layout · Persistent navigation and workspace layout · `components/shell/AppShell.tsx`
- [Layout](https://github.com/bluenot3/agent-arena-template/blob/main/components/Layout.tsx): chrome · Shared outer layout wrapper · `components/Layout.tsx`
- [Error Boundary](https://github.com/bluenot3/agent-arena-template/blob/main/components/AppErrorBoundary.tsx): resilience · UI fault isolation · `components/AppErrorBoundary.tsx`
- [UI Kit](https://github.com/bluenot3/agent-arena-template/blob/main/components/ui/Button.tsx): design system · Shared presentation primitives · `components/ui/Button.tsx`

### Pages

Route-driven experiences

- [Dashboard](https://github.com/bluenot3/agent-arena-template/blob/main/pages/DashboardPage.tsx): route · Main overview page · `pages/DashboardPage.tsx`
- [Agents](https://github.com/bluenot3/agent-arena-template/blob/main/pages/AgentsPage.tsx): route · Agent list and management · `pages/AgentsPage.tsx`
- [Agent Detail](https://github.com/bluenot3/agent-arena-template/blob/main/pages/AgentDetailPage.tsx): route · Selected agent workspace · `pages/AgentDetailPage.tsx`
- [Marketplace](https://github.com/bluenot3/agent-arena-template/blob/main/pages/MarketplacePage.tsx): route · Catalog and upgrade surface · `pages/MarketplacePage.tsx`
- [Labs](https://github.com/bluenot3/agent-arena-template/blob/main/pages/LabsPage.tsx): route · Experimental and legacy experiences · `pages/LabsPage.tsx`
- [Settings](https://github.com/bluenot3/agent-arena-template/blob/main/pages/SettingsPage.tsx): route · Preferences and access management · `pages/SettingsPage.tsx`
- [Workspace](https://github.com/bluenot3/agent-arena-template/blob/main/pages/Workspace.tsx): route · General working area · `pages/Workspace.tsx`
- [Bot Builder](https://github.com/bluenot3/agent-arena-template/blob/main/pages/BotBuilder.tsx): route · Agent creation and tuning · `pages/BotBuilder.tsx`

### Domain

Canonical agent model and state

- [Agent Store](https://github.com/bluenot3/agent-arena-template/blob/main/stores/AgentStore.tsx): state · Context and reducer for agent lifecycle · `stores/AgentStore.tsx`
- [Agent Model](https://github.com/bluenot3/agent-arena-template/blob/main/models/agent.ts): domain schema · Canonical agent entities and types · `models/agent.ts`
- [Types](https://github.com/bluenot3/agent-arena-template/blob/main/types.ts): shared types · Cross-cutting type definitions · `types.ts`

### Services

Local-first persistence and AI/integration layer

- [Registry](https://github.com/bluenot3/agent-arena-template/blob/main/services/agentRegistry.ts): local persistence · LocalStorage-backed agent persistence · `services/agentRegistry.ts`
- [Instrumentation](https://github.com/bluenot3/agent-arena-template/blob/main/services/instrumentation.ts): analytics hooks · Event tracking API · `services/instrumentation.ts`
- [AI Services](https://github.com/bluenot3/agent-arena-template/blob/main/services/ai.ts): model integration · LLM and agent intelligence boundary · `services/ai.ts`
- [Model Catalog](https://github.com/bluenot3/agent-arena-template/blob/main/services/modelCatalog.ts): model metadata · Available model definitions and selection data · `services/modelCatalog.ts`
- [Web Search](https://github.com/bluenot3/agent-arena-template/blob/main/services/webSearch.ts): retrieval · Search and web intel services · `services/webSearch.ts`
- [Agent Insights](https://github.com/bluenot3/agent-arena-template/blob/main/services/agentInsights.ts): insights · Derived agent analysis and recommendations · `services/agentInsights.ts`

## Connections

- 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
