# aditthyass/iloveagents architecture

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

- Interactive diagram: https://gitdiagram.com/aditthyass/iloveagents
- Repository: https://github.com/aditthyass/iloveagents

## Overview

1. **Overall shape**
   - This is a **client-side React SPA** built with **Vite** and styled with **Tailwind CSS**.
   - It is deployed as a static app on **Vercel**, with SPA routing handled by `vercel.json`.
   - The core architectural choice is **no custom backend for AI execution**: browser requests go directly to OpenAI, Anthropic, or Google Gemini using the user’s own API key.

2. **Primary domain: configurable AI agents**
   - The app is organized around a registry of independent “agent” definitions in `src/agents/definitions/`.
   - Each agent is a config object describing its identity, category, icon, provider preference, inputs, system prompt, and output format.
   - `src/agents/registry.js` auto-discovers these definitions, so adding a new agent is mostly a file addition rather than a wiring change.
   - `src/agents/categories.js` provides the classification layer used by browsing and filtering.

3. **Agent execution pipeline**
   - The generic execution path is centered on `src/components/AgentRunner.jsx`.
   - User input is collected from agent-specific fields, transformed into a prompt, and sent through the unified LLM adapter in `src/lib/llmAdapter.js`.
   - The response is then rendered by `src/components/OutputRenderer.jsx`, with specialized output handling such as scorecards in `ScorecardOutput.jsx`.
   - This creates a clear boundary between **agent configuration**, **prompt orchestration**, and **response rendering**.

4. **Provider abstraction boundary**
   - `src/lib/llmAdapter.js` is the main integration layer for the three supported AI providers.
   - Provider/model selection is runtime-driven through UI state rather than build-time configuration.
   - `src/lib/useApiKey.js` manages API key state in the browser, reinforcing the “bring your own key” model.
   - Because keys are entered locally and not routed through a server, the repo avoids persistence and server-side secrets management for provider credentials.

5. **Main browsing and single-agent UX**
   - `HomePage.jsx` likely serves the agent catalog entry point, with `AgentCard.jsx` used for the grid/list presentation.
   - `AgentPage.jsx` is the per-agent view where the selected agent’s config is loaded into the runner UI.
   - Supporting chrome components such as `Navbar.jsx`, `Sidebar.jsx`, `ScrollToTop.jsx`, and `Logo.jsx` provide shared navigation and layout.
   - `RecentRuns.jsx`, `SuggestedChainPills.jsx`, and `ApiKeyBar.jsx` add UX layers around recent activity, chaining hints, and provider/key controls.

6. **Battle Mode as a parallel execution subsystem**
   - Battle Mode is a distinct flow with its own pages: `BattleModeLanding.jsx`, `BattleModeSetup.jsx`, `BattleModeArena.jsx`, and `BattleModeWinner.jsx`.
   - The same user prompt is sent to multiple providers in parallel, and each provider’s result is rendered in separate columns.
   - The architecture here emphasizes **independent provider execution** and **failure isolation**: one provider can fail without blocking the others.
   - The final “winner” selection is user-driven, not algorithmically decided by the app.

7. **Workflow Builder and sequential orchestration**
   - The workflow feature is a second major subsystem with `WorkflowLibrary.jsx`, `WorkflowBuilder.jsx`, `WorkflowDetail.jsx`, and `WorkflowRunner.jsx`.
   - Workflows chain multiple agents in sequence: output from step N becomes input to step N+1.
   - `src/hooks/useWorkflows.js` appears to encapsulate workflow CRUD, execution state, and realtime updates.
   - This subsystem is the app’s main orchestration boundary, distinct from single-agent runs because it adds step-wise state, stop-on-failure behavior, and multi-step output aggregation.

8. **Shared persistence and realtime data**
   - `src/lib/supabase.js` indicates the app uses **Supabase** for workflow-related persistence and realtime functionality.
   - The README confirms workflows need `.env.local` values for Supabase, while AI provider keys remain runtime-only.
   - This suggests a split between **ephemeral client-side AI execution** and **shared application data** for community workflows, counters, and library browsing.
   - The architecture therefore has one external data plane for AI providers and a separate data plane for workflow metadata/realtime state.

9. **Local state and browser-bound features**
   - Features like favorites, history, and API key handling are implemented through client-side hooks such as `useFavorites.js`, `useHistory.js`, and `useApiKey.js`.
   - These are likely backed by browser storage rather than server persistence, which matches the repo’s no-backend design.
   - `VoiceInput.jsx` adds browser input capture as an optional UX layer, but it does not change the overall data flow architecture.

10. **Rendering and output specialization**
   - The app supports multiple output shapes: markdown, plain text, and structured JSON.
   - `OutputRenderer.jsx` is the polymorphic display layer, while `ScorecardOutput.jsx` handles visually rich structured results for certain agent types.
   - This is important architecturally because the agent registry and UI are designed around **output type as part of the contract**, not just text generation.

11. **Operational and deployment boundaries**
   - The repo is designed for static hosting with minimal operational footprint.
   - `index.html`, `vite.config.js`, `tailwind.config.js`, and `postcss.config.js` define the frontend build/runtime pipeline.
   - `public/` contains static assets and metadata, while `.env.example` documents the expected local environment shape for optional services like Supabase.
   - There is no traditional application server, job worker, or database inside the repository itself.

12. **How to read the architecture diagram**
   - The main boxes are: **UI/pages**, **generic agent runtime**, **provider adapter**, **workflow orchestration**, and **optional Supabase-backed shared workflow data**.
   - The main external boundaries are: **browser**, **LLM provider APIs**, and **Supabase**.
   - The most important flows are:
     - user input → agent page/runner → LLM adapter → provider API → rendered output
     - prompt → battle mode → three provider calls in parallel → comparison UI
     - workflow input → sequential agent steps → realtime workflow state/persistence → final combined output

Main entry points: [`src/App.jsx`](https://github.com/aditthyass/iloveagents/blob/main/src/App.jsx) (App router), [`src/components/AgentRunner.jsx`](https://github.com/aditthyass/iloveagents/blob/main/src/components/AgentRunner.jsx) (Runner), [`src/lib/llmAdapter.js`](https://github.com/aditthyass/iloveagents/blob/main/src/lib/llmAdapter.js) (LLM adapter), [`src/hooks/useWorkflows.js`](https://github.com/aditthyass/iloveagents/blob/main/src/hooks/useWorkflows.js) (Workflow hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_app["App router<br/>spa shell<br/>[App.jsx]"]
  node_home["Home<br/>catalog page<br/>[HomePage.jsx]"]
  node_agent_page["Agent page<br/>detail page<br/>[AgentPage.jsx]"]
end

subgraph group_agents["Agent system"]
  node_registry["Registry<br/>agent catalog<br/>[registry.js]"]
  node_categories["Categories<br/>taxonomy<br/>[categories.js]"]
  node_definitions["Agent defs<br/>config modules"]
  node_runner["Runner<br/>prompt orchestrator<br/>[AgentRunner.jsx]"]
  node_renderer["Output renderer<br/>display layer<br/>[OutputRenderer.jsx]"]
  node_scorecard["Scorecard<br/>structured output"]
  node_adapter["LLM adapter<br/>provider gateway<br/>[llmAdapter.js]"]
end

subgraph group_battle["Battle mode"]
  node_battle_landing["Battle start<br/>battle page"]
  node_battle_arena["Battle arena<br/>parallel compare"]
  node_battle_winner["Battle winner<br/>selection page"]
end

subgraph group_workflows["Workflows"]
  node_workflow_library["Library<br/>workflow page"]
  node_workflow_builder["Builder<br/>workflow editor"]
  node_workflow_detail["Workflow detail<br/>workflow page<br/>[WorkflowDetail.jsx]"]
  node_workflow_runner["Workflow runner<br/>orchestrator<br/>[WorkflowRunner.jsx]"]
  node_workflows_hook["Workflow hook<br/>state orchestration<br/>[useWorkflows.js]"]
  node_supabase[("Supabase<br/>shared data backend<br/>[supabase.js]")]
end

subgraph group_state["Browser state"]
  node_apikey["API key state<br/>browser secret state<br/>[useApiKey.js]"]
  node_favorites["Favorites<br/>local state<br/>[useFavorites.js]"]
  node_history["History<br/>local state<br/>[useHistory.js]"]
end

subgraph group_infra["Build & deploy"]
  node_build["Vite build<br/>frontend build<br/>[vite.config.js]"]
  node_deploy["Vercel<br/>static hosting<br/>[vercel.json]"]
end

node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_agent_page
node_app -->|"routes to"| node_battle_landing
node_app -->|"routes to"| node_workflow_library
node_app -->|"routes to"| node_workflow_builder
node_app -->|"routes to"| node_workflow_detail
node_app -->|"routes to"| node_workflow_runner
node_home -->|"lists agents"| node_registry
node_home -->|"filters by"| node_categories
node_agent_page -->|"loads agent into"| node_runner
node_runner -->|"reads config"| node_definitions
node_runner -->|"invokes"| node_adapter
node_runner -->|"renders result"| node_renderer
node_renderer -->|"specializes to"| node_scorecard
node_adapter -->|"uses"| node_apikey
node_adapter -.->|"does not use"| node_supabase
node_battle_landing -->|"starts"| node_battle_arena
node_battle_arena -->|"parallel calls"| node_adapter
node_battle_arena -->|"advances to"| node_battle_winner
node_workflow_builder -->|"uses"| node_workflows_hook
node_workflow_detail -->|"uses"| node_workflows_hook
node_workflow_runner -->|"orchestrates via"| node_workflows_hook
node_workflows_hook -->|"persists and syncs"| node_supabase
node_runner -->|"records"| node_history
node_runner -->|"updates"| node_favorites
node_runner -->|"reads"| node_apikey
node_build -->|"builds for"| node_deploy

click node_app "https://github.com/aditthyass/iloveagents/blob/main/src/App.jsx"
click node_home "https://github.com/aditthyass/iloveagents/blob/main/src/pages/HomePage.jsx"
click node_agent_page "https://github.com/aditthyass/iloveagents/blob/main/src/pages/AgentPage.jsx"
click node_battle_landing "https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeLanding.jsx"
click node_battle_arena "https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeArena.jsx"
click node_battle_winner "https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeWinner.jsx"
click node_workflow_library "https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowLibrary.jsx"
click node_workflow_builder "https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowBuilder.jsx"
click node_workflow_detail "https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowDetail.jsx"
click node_workflow_runner "https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowRunner.jsx"
click node_registry "https://github.com/aditthyass/iloveagents/blob/main/src/agents/registry.js"
click node_categories "https://github.com/aditthyass/iloveagents/blob/main/src/agents/categories.js"
click node_definitions "https://github.com/aditthyass/iloveagents/tree/main/src/agents/definitions"
click node_runner "https://github.com/aditthyass/iloveagents/blob/main/src/components/AgentRunner.jsx"
click node_renderer "https://github.com/aditthyass/iloveagents/blob/main/src/components/OutputRenderer.jsx"
click node_scorecard "https://github.com/aditthyass/iloveagents/blob/main/src/components/ScorecardOutput.jsx"
click node_adapter "https://github.com/aditthyass/iloveagents/blob/main/src/lib/llmAdapter.js"
click node_apikey "https://github.com/aditthyass/iloveagents/blob/main/src/lib/useApiKey.js"
click node_favorites "https://github.com/aditthyass/iloveagents/blob/main/src/lib/useFavorites.js"
click node_history "https://github.com/aditthyass/iloveagents/blob/main/src/lib/useHistory.js"
click node_workflows_hook "https://github.com/aditthyass/iloveagents/blob/main/src/hooks/useWorkflows.js"
click node_supabase "https://github.com/aditthyass/iloveagents/blob/main/src/lib/supabase.js"
click node_build "https://github.com/aditthyass/iloveagents/blob/main/vite.config.js"
click node_deploy "https://github.com/aditthyass/iloveagents/blob/main/vercel.json"

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_app,node_home,node_agent_page toneBlue
class node_registry,node_categories,node_definitions,node_runner,node_renderer,node_scorecard,node_adapter toneAmber
class node_battle_landing,node_battle_arena,node_battle_winner toneMint
class node_workflow_library,node_workflow_builder,node_workflow_detail,node_workflow_runner,node_workflows_hook,node_supabase toneRose
class node_apikey,node_favorites,node_history toneIndigo
class node_build,node_deploy toneTeal
```

## Components

### UI shell

Shared layout and navigation for the SPA

- [App router](https://github.com/aditthyass/iloveagents/blob/main/src/App.jsx): spa shell · Top-level client routing and page composition · `src/App.jsx`
- [Home](https://github.com/aditthyass/iloveagents/blob/main/src/pages/HomePage.jsx): catalog page · Entry point for browsing agents · `src/pages/HomePage.jsx`
- [Agent page](https://github.com/aditthyass/iloveagents/blob/main/src/pages/AgentPage.jsx): detail page · Single-agent view that loads a selected agent into the runner · `src/pages/AgentPage.jsx`

### Agent system

Catalog, execution, and output rendering for single-agent runs

- [Registry](https://github.com/aditthyass/iloveagents/blob/main/src/agents/registry.js): agent catalog · Auto-discovers agent definition modules · `src/agents/registry.js`
- [Categories](https://github.com/aditthyass/iloveagents/blob/main/src/agents/categories.js): taxonomy · Agent classification used for browsing and filtering · `src/agents/categories.js`
- [Agent defs](https://github.com/aditthyass/iloveagents/tree/main/src/agents/definitions): config modules · Collection of independent agent configuration files · `src/agents/definitions`
- [Runner](https://github.com/aditthyass/iloveagents/blob/main/src/components/AgentRunner.jsx): prompt orchestrator · Collects inputs, builds prompts, and executes agents · `src/components/AgentRunner.jsx`
- [Output renderer](https://github.com/aditthyass/iloveagents/blob/main/src/components/OutputRenderer.jsx): display layer · Polymorphic rendering for markdown, text, and structured outputs · `src/components/OutputRenderer.jsx`
- [Scorecard](https://github.com/aditthyass/iloveagents/blob/main/src/components/ScorecardOutput.jsx): structured output · Specialized rendering for rich scored results · `src/components/ScorecardOutput.jsx`
- [LLM adapter](https://github.com/aditthyass/iloveagents/blob/main/src/lib/llmAdapter.js): provider gateway · Unified client for OpenAI, Anthropic, and Gemini · `src/lib/llmAdapter.js`

### Battle mode

Parallel multi-provider comparison flow

- [Battle start](https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeLanding.jsx): battle page · Landing and setup entry for Battle Mode · `src/pages/BattleModeLanding.jsx`
- [Battle arena](https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeArena.jsx): parallel compare · Runs the same prompt across multiple providers in parallel · `src/pages/BattleModeArena.jsx`
- [Battle winner](https://github.com/aditthyass/iloveagents/blob/main/src/pages/BattleModeWinner.jsx): selection page · User chooses the preferred provider result · `src/pages/BattleModeWinner.jsx`

### Workflows

Sequential multi-agent orchestration and shared workflow data

- [Library](https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowLibrary.jsx): workflow page · Browse shared workflows · `src/pages/WorkflowLibrary.jsx`
- [Builder](https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowBuilder.jsx): workflow editor · Create and edit sequential workflows · `src/pages/WorkflowBuilder.jsx`
- [Workflow detail](https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowDetail.jsx): workflow page · Inspect a workflow and its configuration · `src/pages/WorkflowDetail.jsx`
- [Workflow runner](https://github.com/aditthyass/iloveagents/blob/main/src/pages/WorkflowRunner.jsx): orchestrator · Executes workflow steps in sequence and aggregates outputs · `src/pages/WorkflowRunner.jsx`
- [Workflow hook](https://github.com/aditthyass/iloveagents/blob/main/src/hooks/useWorkflows.js): state orchestration · Encapsulates workflow CRUD, execution state, and realtime updates · `src/hooks/useWorkflows.js`
- [Supabase](https://github.com/aditthyass/iloveagents/blob/main/src/lib/supabase.js): shared data backend · Persistence and realtime transport for workflows · `src/lib/supabase.js`

### Browser state

Client-side persistence and user preferences

- [API key state](https://github.com/aditthyass/iloveagents/blob/main/src/lib/useApiKey.js): browser secret state · Manages user-provided provider keys in the browser · `src/lib/useApiKey.js`
- [Favorites](https://github.com/aditthyass/iloveagents/blob/main/src/lib/useFavorites.js): local state · Browser-backed saved agents · `src/lib/useFavorites.js`
- [History](https://github.com/aditthyass/iloveagents/blob/main/src/lib/useHistory.js): local state · Browser-backed recent runs and activity · `src/lib/useHistory.js`

### Build & deploy

Frontend build pipeline and static hosting setup

- [Vite build](https://github.com/aditthyass/iloveagents/blob/main/vite.config.js): frontend build · Client build and dev runtime configuration · `vite.config.js`
- [Vercel](https://github.com/aditthyass/iloveagents/blob/main/vercel.json): static hosting · SPA deployment and routing configuration · `vercel.json`

## Connections

- App router → Home: routes to · Main catalog entry flow
- App router → Agent page: routes to · Selected agent view
- App router → Battle start: routes to · Battle mode entry
- App router → Library: routes to · Workflow browsing entry
- App router → Builder: routes to · Workflow authoring entry
- App router → Workflow detail: routes to · Workflow inspection entry
- App router → Workflow runner: routes to · Workflow execution entry
- Home → Registry: lists agents · Browse catalog from discovered definitions
- Home → Categories: filters by · Category-driven discovery
- Agent page → Runner: loads agent into · Single-agent execution setup
- Runner → Agent defs: reads config · Uses agent-specific identity, prompt, inputs, and output format
- Runner → LLM adapter: invokes · Sends prompt and model choice to provider gateway
- Runner → Output renderer: renders result · Displays the returned output
- Output renderer → Scorecard: specializes to · Structured output variant for select agents
- LLM adapter → API key state: uses · Reads browser-held user API key
- LLM adapter → Supabase: does not use · AI calls bypass server-side execution
- Battle start → Battle arena: starts · Launches parallel provider comparison
- Battle arena → LLM adapter: parallel calls · Sends one prompt to multiple providers
- Battle arena → Battle winner: advances to · User compares results and chooses winner
- Builder → Workflow hook: uses · Workflow editor state and actions
- Workflow detail → Workflow hook: uses · Loads workflow metadata and status
- Workflow runner → Workflow hook: orchestrates via · Sequential step execution and state updates
- Workflow hook → Supabase: persists and syncs · Shared workflows and realtime updates
- Runner → History: records · Stores recent runs locally
- Runner → Favorites: updates · Saves favorite agents in the browser
- Runner → API key state: reads · Uses current provider credential state
- Vite build → Vercel: builds for · Frontend is compiled for static hosting
