Overview

Relevant source files

• AGENTS.md
• README.md
• apps/api/README.md
• apps/web/app/api/farcaster/[fid]/keys/route.ts
• apps/web/app/api/farcaster/[fid]/signers/route.ts
• apps/web/app/api/farcaster/user/route.ts

Purpose and Scope

This page provides a high-level introduction to Casterscan, its architecture, and core design principles. It is intended as an entry point for understanding the system before diving into specific components.

For detailed information about specific subsystems:

• Monorepo organization and build tooling: see Monorepo Structure
• Request flow and architectural patterns: see System Architecture
• Backend implementation: see apps/api - Express Backend
• Frontend implementation: see apps/web - Next.js Frontend
• API contracts and endpoints: see API Endpoint Reference
• Deployment procedures: see Deployment

---

What is Casterscan?

Casterscan is a block explorer for Farcaster, deployed at casterscan.com. It provides URL-based access to Farcaster protocol data including casts, user profiles, signers, keys, and real-time Snapchain events.

Core design goals:

1. Easy access to Farcaster data — Aggregates data from Neynar API, Snapchain node (snap.farcaster.xyz:3383), Farcaster API, and Optimism RPC into a unified REST API at api.casterscan.com
2. Unique URLs for atomic data units — Every cast, user (FID), signer key, and Snapchain event has a shareable URL path (e.g., /fids/3, /casts/0xabc..., /snapchain/events/123)

Capabilities:

• Real-time cast firehose via GET /v1/snapchain/events/:eventId
• Cast inspection with provider-specific formats (neynar-hub, farcaster-hub, farcaster-api)
• User profile pages showing signers and keys via GET /v1/fids/:fid/stats and GET /v1/fids/:fid/keys
• Signer-level statistics via GET /v1/fids/:fid/signers/:signerKey/stats
• Snapchain event streaming and inspection

Sources: README.md1-20

---

High-Level System Architecture

Casterscan is built as a Turborepo monorepo containing two primary applications that work together:

High-Level System Architecture

Critical architectural pattern: The browser never directly calls the Express API. All requests flow through Next.js API proxy routes in app/api/*, which forward to the Express backend. This provides server-side caching, CORS simplification, and security (the backend URL is hidden from clients).

Sources: README.md39-42 AGENTS.md14-21 package.json1-23

---

Monorepo Organization

The repository follows a workspace-based monorepo structure managed by Turborepo:

Workspace	Path	Purpose	Port
Web	apps/web	Next.js frontend with SSR, API proxy routes, and UI components	3000
API	apps/api	Express REST API with Redis caching and upstream integrations	4000
Packages	packages/*	Shared code, UI components, utilities, and schemas	N/A

The root package.json defines unified scripts using Turbo's --filter and --parallel flags:

Script	Command	Effect
bun run dev	turbo run dev --filter=web --filter=api --parallel	Starts both apps/web and apps/api concurrently
bun run dev:web	turbo run dev --filter=web	Starts apps/web only (:3000)
bun run dev:api	turbo run dev --filter=api	Starts apps/api only (:4000)
bun run build	turbo run build	Builds all workspaces
bun run start	turbo run start --filter=web	Starts production web server
bun run lint	turbo run lint	Runs linters across all workspaces

Package manager: [email protected] serves as both the package manager and runtime, providing fast dependency resolution and native TypeScript support.

For detailed workspace configuration and build system mechanics, see Monorepo Structure.

Sources: package.json1-23 README.md39-42

---

Technology Stack

Layer	Technology	Purpose
Runtime	Bun 1.3.4	Package management, TypeScript execution, bundling
Build System	Turbo 2.3.0	Monorepo orchestration, caching, parallel execution
Frontend Framework	Next.js 15 + React 19	Server-side rendering, routing, API proxy layer
UI Components	Shadcn/ui + Tailwind CSS	Component library and utility-first styling
Backend Framework	Express.js	REST API routing and middleware
Validation	Zod	Runtime type validation and schema enforcement
Caching	ioredis	Redis client for multi-layered caching strategy
Blockchain Client	viem	Ethereum/Optimism RPC interactions

Sources: package.json19-22 apps/api/README.md1-3 AGENTS.md33-34

---

Data Flow and Request Lifecycle

Request Lifecycle: Browser to Upstream Services

Key architectural principles:

1. Proxy Pattern: The browser never calls apps/api directly. All requests flow through apps/web/app/api/* routes, which use apiFetch() from apps/web/app/lib/api.ts1-15 to proxy to API_URL.

2. Multi-Layered Caching:

   • Browser cache (Cache-Control headers in Next.js responses)
   • Next.js server cache (SSR data caching)
   • Redis cache via getCachedOrFetch() in apps/api/src/cache/cache.ts1-100
   • Request coalescing via coalescedFetch() in apps/api/src/cache/cache.ts1-100

3. Environment Configuration: API_URL env var controls backend location:

   • Development: http://localhost:4000 (default)
   • Production: https://api.casterscan.com

For detailed request flow analysis, see Request Flow.

Sources: AGENTS.md14-21 apps/web/app/api/farcaster/user/route.ts1-17 apps/web/app/api/farcaster/[fid]/signers/route.ts:1-29

---

API Route Mapping

The Next.js frontend defines proxy routes in app/api/* that map to Express API endpoints:

Next.js Proxy Route	Express API Endpoint	Purpose
/api/snapchain/info	GET /v1/snapchain/info	Snapchain node information
/api/snapchain/event	GET /v1/snapchain/events/:eventId	Individual Snapchain event
/api/fid/[fid]/stats	GET /v1/fids/:fid/stats	Cast/reaction/link counts for FID
/api/signers/enriched	GET /v1/fids/:fid/signers/enriched	Signers with app profile enrichment
/api/farcaster/[fid]/signers	GET /v1/fids/:fid/signers	Raw signer list for FID
/api/farcaster/[fid]/keys	GET /v1/fids/:fid/keys	Auth addresses and signer keys
/api/farcaster/[fid]/casts	GET /v1/fids/:fid/messages	Messages/casts by FID
/api/farcaster/user	GET /v1/users/:fid	User profile by FID
/api/farcaster/cast	GET /v1/casts/:hash	Cast details by hash

Example proxy route implementation:

The pattern in apps/web/app/api/farcaster/user/route.ts5-16 shows how Next.js routes proxy to the Express API:

1. Extract query parameter (fid)
2. Call apiFetch('/v1/users/${fid}') which prepends API_URL
3. Return response with Cache-Control header using constants from CACHE_TTLS in apps/web/app/lib/utils.ts1-50

This ensures the browser never sees or calls api.casterscan.com directly.

For complete API endpoint documentation, see API Endpoint Reference.

Sources: AGENTS.md48-65 apps/web/app/api/farcaster/user/route.ts1-17 apps/web/app/api/farcaster/[fid]/keys/route.ts:1-27

---

Deployment Architecture

Casterscan uses a dual-deployment model with separate Vercel deployments for frontend and backend:

Critical deployment order: The API must be deployed first to obtain its URL, which is then configured as the API_URL environment variable in the Web app deployment.

Environment variables:

Variable	App	Required	Description
NEYNAR_API_KEY	API	Yes	Neynar API key for user/cast lookups
API_URL	Web	No	Backend URL (default: localhost:4000 dev, api.casterscan.com prod)
REDIS_URL	API	No	Redis connection string (cache disabled if unset)
ALLOWED_ORIGINS	API	No	CORS allowed origins

For complete deployment procedures, see Deployment.

Sources: README.md31-37 apps/api/README.md6-9 AGENTS.md119-125

---

Key Design Principles

1. URL-First Design

Every atomic unit of Farcaster/Snapchain data has a unique URL route in [apps/web/app/]:

• Casts: app/casts/[hash]/page.tsx → /casts/0xabc...
• Users: app/fids/[fid]/page.tsx → /fids/3
• Signers: app/fids/[fid]/signers/[signer]/page.tsx → /fids/3/signers/0x123...
• Events: app/snapchain/events/[eventId]/page.tsx → /snapchain/events/12345

2. Proxy Pattern

The browser never calls apps/api directly. All API requests flow through apps/web/app/api/* routes:

• apiFetch() in apps/web/app/lib/api.ts1-15 prepends API_URL to all paths
• Next.js API routes return Cache-Control headers for browser caching
• Backend URL (api.casterscan.com) remains invisible to browser clients
• CORS simplified (same-origin requests)

3. Multi-Layered Caching

Four cache layers optimize performance:

1. Browser cache — Cache-Control headers in Next.js responses
2. Next.js server cache — SSR data caching
3. Redis cache — getCachedOrFetch() in apps/api/src/cache/cache.ts1-100
4. Request coalescing — coalescedFetch() prevents duplicate concurrent requests

4. Type Safety & Validation

Runtime validation using Zod schemas:

• validateParams(fidSchema) in apps/api/src/lib/validate.ts1-50
• validateQuery(querySchema) for query string validation
• validateBody(bodySchema) for POST request bodies
• asyncHandler() wrapper catches async errors and passes to error middleware

5. Modular Service Architecture

Clear separation in [apps/api/src/]:

• routes/ — HTTP routing, Zod validation (fidsRouter.ts, castsRouter.ts, etc.)
• services/ — Business logic (fid.ts, cast.ts, signer.ts)
• cache/ — Redis client and coalescing (cache.ts)
• upstream/ — External API clients (neynar.ts, snapchain.ts, etc.)

Sources: README.md17-19 AGENTS.md14-21 apps/api/README.md1-3

---

Getting Started

For Developers

Local development setup:

The bun run dev command uses turbo run dev --filter=web --filter=api --parallel from package.json11-17 to start both applications concurrently.

See Development Guide for coding conventions and feature development workflows.

For Understanding the System

Navigate to specific sections based on your interest:

• Architecture: System Architecture for request flow and data aggregation
• Backend: apps/api - Express Backend for API implementation
• Frontend: apps/web - Next.js Frontend for UI and proxy layer
• API Contracts: API Endpoint Reference for endpoint specifications

Sources: README.md22-29 AGENTS.md140-148