Skip to main content
The ouroborai web terminal is a Next.js 15 app with a chat-based terminal interface. Components live in apps/web/src/app/app/components/ and hooks in apps/web/src/app/app/hooks/.

Component Architecture

AppLayout
  |-- Header
  |-- LeftSidebar
  |     |-- SessionTabs
  |     |-- ActivityPanel
  |     |-- AutomationsPanel
  |-- ChatPanel (center)
  |-- RightSidebar
        |-- WalletPanel
        |-- PositionsPanel
        |-- MarketPanel
        |-- NftsPanel
        |-- PredictionsPanel
        |-- StakingPanel
        |-- LaunchpadPanel

Layout Components

ComponentFileDescription
LeftSidebarleft-sidebar.tsxSession management and activity feed
RightSidebarright-sidebar.tsxWallet, positions, and market data
MobileNavmobile-nav.tsxResponsive navigation for small screens
CollapsibleSectioncollapsible-section.tsxExpandable/collapsible container

Core Components

ComponentFileDescription
ChatPanelchat-panel.tsxMain chat interface with message history and input
SessionTabssession-tabs.tsxTab manager for multiple conversation sessions
ActivityPanelactivity-panel.tsxRecent agent job feed with status indicators
ComponentFileDescription
WalletPanelwallet-panel.tsxETH and ERC-20 token balances
PositionsPanelpositions-panel.tsxAave V3 and GMX V2 position summaries
MarketPanelmarket-panel.tsxToken prices and trending pools
NftsPanelnfts-panel.tsxNFT gallery for connected wallet
PredictionsPanelpredictions-panel.tsxPolymarket prediction markets
StakingPanelstaking-panel.tsxStaking positions overview
LaunchpadPanellaunchpad-panel.tsxToken launch tracking
AutomationsPanelautomations-panel.tsxScheduled automation management
SwapPanelswap-panel.tsxQuick swap interface
ComponentFileDescription
SendModalsend-modal.tsxToken transfer dialog
DepositModaldeposit-modal.tsxDeposit flow dialog
BridgeModalbridge-modal.tsxCross-chain bridge dialog
CreateTokenModalcreate-token-modal.tsxToken launch wizard
NftDetailModalnft-detail-modal.tsxNFT detail view
NftTransferModalnft-transfer-modal.tsxNFT transfer dialog
WrongNetworkModalwrong-network-modal.tsxChain switching prompt
FeatureInfoModalfeature-info-modal.tsxFeature description overlay

Custom Hooks

useChat

File: hooks/use-chat.ts Manages the chat interface state including message history, job polling, and thread persistence via sessionStorage.
function useChat(apiKey: string | null): {
  messages: Message[];
  isLoading: boolean;
  sendMessage: (content: string) => Promise<void>;
  clearMessages: () => void;
  sessionId: string;
}
Return ValueTypeDescription
messagesMessage[]Chat message history (user + agent)
isLoadingbooleanWhether a job is pending or running
sendMessage(content: string) => Promise<void>Submit a prompt to the agent
clearMessages() => voidClear message history
sessionIdstringCurrent session identifier
The hook polls /agent/job/:id every 2 seconds while a job is running. Thread IDs are persisted to sessionStorage under thread:{sessionId} for cross-refresh recovery.

useWalletBalances

File: hooks/use-wallet-balances.ts Fetches ERC-20 token balances for the connected wallet using wagmi’s useReadContracts.
function useWalletBalances(): {
  balances: TokenBalance[];
  isLoading: boolean;
  refetch: () => void;
}
Return ValueTypeDescription
balancesTokenBalance[]Array of token balances with formatted amounts
isLoadingbooleanLoading state
refetch() => voidManually trigger a refresh
Each TokenBalance includes: symbol, address, balance (bigint), decimals, and formatted (human-readable string).

useTokenPrices

File: hooks/use-token-prices.ts Fetches current token prices from the /market/prices API endpoint.
function useTokenPrices(apiKey: string | null): {
  prices: Record<string, { price: number; change24h: number }>;
  isLoading: boolean;
}

useActivity

File: hooks/use-activity.ts Fetches recent agent jobs from /portfolio/jobs and transforms them into activity feed items.
function useActivity(apiKey: string | null): {
  activities: Activity[];
  isLoading: boolean;
  refetch: () => void;
}
Each Activity includes: id, type (inferred from tool calls), description, status, timestamp, and optional toolCalls.

usePositions

File: hooks/use-positions.ts Fetches aggregated DeFi positions from /portfolio/positions.
function usePositions(apiKey: string | null): {
  positions: PositionsData | null;
  isLoading: boolean;
  refetch: () => void;
}
PositionsData contains aave (Aave V3 account data with health factor, collateral, and debt) and gmx (array of perpetual positions with PnL and liquidation prices).

useMarketData

File: hooks/use-market-data.ts Fetches trending pools from /market/trending.
function useMarketData(apiKey: string | null): {
  trending: TrendingPool[];
  isLoading: boolean;
}

useNfts

File: hooks/use-nfts.ts Fetches NFTs for the connected wallet from /nfts/:address.
function useNfts(address: string | undefined, apiKey: string | null): {
  nfts: NftItem[];
  isLoading: boolean;
  refetch: () => void;
}

useAutomations

File: hooks/use-automations.ts Manages automation CRUD operations against /automations.
function useAutomations(
  walletAddress: string | undefined,
  apiKey: string | null
): {
  automations: Automation[];
  isLoading: boolean;
  create: (params: CreateAutomationParams) => Promise<void>;
  updateStatus: (id: string, status: string) => Promise<void>;
  remove: (id: string) => Promise<void>;
  refetch: () => void;
}

Styling

The web terminal uses a vibrant dark theme with Arbitrum brand colors:
TokenValueUsage
Primary#12AAFFInteractive elements, links
Light accent#00D4FFHover states, highlights
Dark accent#0088CCBorders, secondary elements
BackgroundDark gradientPage background