How aditthyass/iloveagents works
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: App.jsx App router · AgentRunner.jsx Runner · llmAdapter.js LLM adapter · useWorkflows.js Workflow hook
Components 24
UI shell
Shared layout and navigation for the SPA
- App router · Top-level client routing and page composition
src/App.jsx - Home · Entry point for browsing agents
src/pages/HomePage.jsx - Agent 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 · Auto-discovers agent definition modules
src/agents/registry.js - Categories · Agent classification used for browsing and filtering
src/agents/categories.js - Agent defs · Collection of independent agent configuration files
src/agents/definitions - Runner · Collects inputs, builds prompts, and executes agents
src/components/AgentRunner.jsx - Output renderer · Polymorphic rendering for markdown, text, and structured outputs
src/components/OutputRenderer.jsx - Scorecard · Specialized rendering for rich scored results
src/components/ScorecardOutput.jsx - LLM adapter · Unified client for OpenAI, Anthropic, and Gemini
src/lib/llmAdapter.js
Battle mode
Parallel multi-provider comparison flow
- Battle start · Landing and setup entry for Battle Mode
src/pages/BattleModeLanding.jsx - Battle arena · Runs the same prompt across multiple providers in parallel
src/pages/BattleModeArena.jsx - Battle winner · User chooses the preferred provider result
src/pages/BattleModeWinner.jsx
Workflows
Sequential multi-agent orchestration and shared workflow data
- Library · Browse shared workflows
src/pages/WorkflowLibrary.jsx - Builder · Create and edit sequential workflows
src/pages/WorkflowBuilder.jsx - Workflow detail · Inspect a workflow and its configuration
src/pages/WorkflowDetail.jsx - Workflow runner · Executes workflow steps in sequence and aggregates outputs
src/pages/WorkflowRunner.jsx - Workflow hook · Encapsulates workflow CRUD, execution state, and realtime updates
src/hooks/useWorkflows.js - Supabase · Persistence and realtime transport for workflows
src/lib/supabase.js
Browser state
Client-side persistence and user preferences
- API key state · Manages user-provided provider keys in the browser
src/lib/useApiKey.js - Favorites · Browser-backed saved agents
src/lib/useFavorites.js - History · Browser-backed recent runs and activity
src/lib/useHistory.js
Build & deploy
Frontend build pipeline and static hosting setup
- Vite build · Client build and dev runtime configuration
vite.config.js - Vercel · SPA deployment and routing configuration
vercel.json
Connections 27
- 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