olas-website: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Olas Network marketing website — a Next.js 15 (Pages Router) application that showcases autonomous AI agents, staking programs, and the Olas protocol. The site uses Strapi as a headless CMS for editorial content, queries multi-chain GraphQL subgraphs for on-chain metrics, and persists those metrics as JSON snapshots in Vercel Blob storage that are refreshed by Vercel cron jobs.

Stack at a glance: Next.js 15 + React 19, Node 22, TypeScript-first (.ts/.tsx) with allowJs for legacy .js/.jsx, Tailwind CSS + shadcn/ui (Radix primitives), graphql-request, swr, @vercel/blob, viem, dayjs.

Development Commands

Use yarn for all commands (preferred in this repo):

yarn dev            # Start dev server at http://localhost:3000
yarn build          # Production build (postbuild runs next-sitemap)
yarn start          # Start production server
yarn lint           # ESLint
yarn lint:fix       # ESLint with auto-fix
yarn lint:lockfile  # Validate yarn.lock integrity (lockfile-lint)

Architecture

Directory Structure

• pages/ — Next.js Pages Router routes
  • pages/api/refresh-metrics/*.ts — cron-driven endpoints that fetch from subgraphs and write Vercel Blob snapshots
  • pages/api/og/[[...slug]].tsx — dynamic Open Graph image generation (@vercel/og)
  • pages/api/olas/[endpoint].ts — thin proxy to OLAS_API_URL (api.olas.autonolas.tech)
  • pages/data/index.tsx — "Data Verification" page; documents the provenance/methodology behind published metrics (e.g. DailyActiveAgentsInfo, BabydegenMetricsInfo, MechGlobalsInfo)
  • pages/card/index.tsx — shareable agent/card page
  • Dynamic routes use bracket notation: [slug].tsx, [id].tsx, [[...slug]].tsx
• components/ — React components organized by page (e.g., BuildPage/, AgentEconomies/, HomepageSection/, StakingPage/, PredictionAgentsTable/)
  • components/ui/ — Reusable UI primitives (shadcn/ui patterns over Radix)
  • components/Layout/ — Header, Footer, Menu, MenuMobile, PageWrapper, SectionWrapper, banners
• common-util/ — Shared utilities and business logic
  • common-util/api/ — Subgraph aggregation logic per category (main-metrics.ts, predict/, agent-economies/, other-metrics/) plus index.ts for Strapi calls (blogs, education articles)
  • common-util/graphql/ — client.ts (GraphQL clients per chain), queries.ts, types.ts (MetricWithStatus, WithMeta, SubgraphMeta), metric-utils.ts (lag detection / stale status helpers)
  • common-util/snapshot-storage.ts — Vercel Blob save/get with mergeWithFallback semantics
  • Other helpers: numberFormatter.ts, time.ts, web3.ts, charts.ts, og/, useFetchApi.ts, olasApr.ts, calculate7DayAverage.ts, indexers.ts (every subgraph/squid URL map, chain scope sentences, getSubgraphExplorerUrl)
• data/ — Static JSON: agents.json, chains.json, tokens.json, kits.json, useCases.json, resources.json, ABIs in data/ABIs/, etc.
• hooks/ — usePersistentSWR, useWindowWidth, useHash
• lib/ — utils.ts (only the cn() helper today)
• styles/ — Global CSS and Tailwind layers
• public/ — Static assets (fonts, images, OG images, documents)
• middleware.ts — Edge middleware (geo-blocking)
• vercel.json — Function limits + cron schedules
• next-sitemap.config.js — Adds /agents/<slug> paths from data/agents.json