# ponder-sh/ponder architecture

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

- Interactive diagram: https://gitdiagram.com/ponder-sh/ponder
- Repository: https://github.com/ponder-sh/ponder

## Overview

Ponder is a TypeScript framework for indexing EVM data. A developer creates or configures an application, starts the runtime, and selects contracts, chains, and event filters. Historical and realtime synchronizers fetch blockchain data through RPC, dispatch matching events to user indexing callbacks, and persist results through the database layer. HTTP consumers query generated GraphQL or SQL APIs, with client and React packages providing application-facing access. The graph preserves documented multichain, Postgres, development-server, and project-generation capabilities; several internal connections use directory-level evidence because their implementations were not sampled.

Main entry points: [`packages/core/src/database/index.ts`](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/database/index.ts) (Database layer), [`packages/core/src/runtime/index.ts`](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/index.ts) (Indexing runtime), [`packages/core/src/server/index.ts`](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/server/index.ts) (HTTP server), [`packages/core/src/indexing/client.ts`](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/indexing/client.ts) (Indexing RPC client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project setup"]
  node_create_ponder["Project generator<br/>[index.ts]"]
  node_project_template["Project template"]
  node_ponder_cli["Ponder CLI<br/>[ponder.ts]"]
  node_config["Chain configuration<br/>[index.ts]"]
end

subgraph group_indexing["Indexing pipeline"]
  node_runtime["Indexing runtime<br/>[index.ts]"]
  node_multichain["Multichain runtime<br/>[multichain.ts]"]
  node_historical_sync["Historical sync<br/>[index.ts]"]
  node_realtime_sync["Realtime sync<br/>[index.ts]"]
  node_filter_fragments["Event filters<br/>[fragments.ts]"]
  node_rpc_client["Indexing RPC client<br/>[client.ts]"]
  node_index_callbacks["Index callbacks<br/>[events.ts]"]
end

subgraph group_storage["Storage and schema"]
  node_schema["Onchain schema<br/>[index.ts]"]
  node_indexing_store["Indexing store<br/>[index.ts]"]
  node_database[("Database layer<br/>[index.ts]")]
  node_query_builder["SQL query builder<br/>[queryBuilder.ts]"]
end

subgraph group_api["Query interfaces"]
  node_graphql["GraphQL API<br/>[index.ts]"]
  node_server["HTTP server<br/>[index.ts]"]
  node_client["Typed client<br/>[index.ts]"]
  node_react["React bindings<br/>[context.ts]"]
end

subgraph group_operations["Runtime operations"]
  node_dev_ui["Development UI<br/>[index.ts]"]
  node_metrics["Runtime metrics<br/>[metrics.ts]"]
end

node_developer(("Developer"))
node_api_consumer(("API consumer"))
node_evm_rpc{{"EVM RPC"}}
node_postgres[("Postgres")]

node_developer -->|"creates project"| node_create_ponder
node_create_ponder -->|"uses template"| node_project_template
node_developer -->|"starts runtime"| node_ponder_cli
node_config -->|"defines filters"| node_filter_fragments
node_ponder_cli -->|"starts indexing"| node_runtime
node_runtime -->|"coordinates chains"| node_multichain
node_multichain -->|"runs backfill"| node_historical_sync
node_multichain -->|"runs realtime"| node_realtime_sync
node_historical_sync -->|"fetches history"| node_rpc_client
node_realtime_sync -->|"fetches blocks"| node_rpc_client
node_filter_fragments -->|"narrows requests"| node_rpc_client
node_rpc_client -->|"requests chain data"| node_evm_rpc
node_runtime -->|"dispatches events"| node_index_callbacks
node_index_callbacks -->|"writes indexed data"| node_database
node_schema -->|"defines tables"| node_database
node_indexing_store -->|"stages index state"| node_database
node_database -->|"persists data"| node_postgres
node_server -->|"routes GraphQL"| node_graphql
node_server -->|"routes SQL"| node_query_builder
node_graphql -->|"reads indexed data"| node_database
node_query_builder -->|"executes queries"| node_database
node_api_consumer -->|"sends queries"| node_server
node_client -->|"requests data"| node_server
node_react -->|"provides client"| node_client
node_runtime -->|"reports progress"| node_metrics
node_dev_ui -->|"reads progress"| node_metrics

click node_create_ponder "https://github.com/ponder-sh/ponder/blob/main/packages/create-ponder/src/index.ts"
click node_project_template "https://github.com/ponder-sh/ponder/tree/main/packages/create-ponder/templates/empty"
click node_ponder_cli "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/bin/ponder.ts"
click node_config "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/config/index.ts"
click node_runtime "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/index.ts"
click node_multichain "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/multichain.ts"
click node_historical_sync "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/sync-historical/index.ts"
click node_realtime_sync "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/sync-realtime/index.ts"
click node_filter_fragments "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/fragments.ts"
click node_rpc_client "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/indexing/client.ts"
click node_index_callbacks "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/events.ts"
click node_schema "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/drizzle/index.ts"
click node_indexing_store "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/indexing-store/index.ts"
click node_database "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/database/index.ts"
click node_query_builder "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/database/queryBuilder.ts"
click node_graphql "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/graphql/index.ts"
click node_server "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/server/index.ts"
click node_client "https://github.com/ponder-sh/ponder/blob/main/packages/client/src/index.ts"
click node_react "https://github.com/ponder-sh/ponder/blob/main/packages/react/src/context.ts"
click node_dev_ui "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/ui/index.ts"
click node_metrics "https://github.com/ponder-sh/ponder/blob/main/packages/core/src/internal/metrics.ts"

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_create_ponder,node_project_template,node_ponder_cli,node_config toneBlue
class node_runtime,node_multichain,node_historical_sync,node_realtime_sync,node_filter_fragments,node_rpc_client,node_index_callbacks,node_postgres toneAmber
class node_schema,node_indexing_store,node_database,node_query_builder,node_api_consumer toneMint
class node_graphql,node_server,node_client,node_react toneRose
class node_dev_ui,node_metrics,node_developer,node_evm_rpc toneIndigo
```

## Components

### Project setup

- [Project generator](https://github.com/ponder-sh/ponder/blob/main/packages/create-ponder/src/index.ts): `packages/create-ponder/src/index.ts`
- [Project template](https://github.com/ponder-sh/ponder/tree/main/packages/create-ponder/templates/empty): `packages/create-ponder/templates/empty`
- [Ponder CLI](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/bin/ponder.ts): `packages/core/src/bin/ponder.ts`
- [Chain configuration](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/config/index.ts): `packages/core/src/config/index.ts`

### Indexing pipeline

- [Indexing runtime](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/index.ts): `packages/core/src/runtime/index.ts`
- [Multichain runtime](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/multichain.ts): `packages/core/src/runtime/multichain.ts`
- [Historical sync](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/sync-historical/index.ts): `packages/core/src/sync-historical/index.ts`
- [Realtime sync](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/sync-realtime/index.ts): `packages/core/src/sync-realtime/index.ts`
- [Event filters](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/fragments.ts): `packages/core/src/runtime/fragments.ts`
- [Indexing RPC client](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/indexing/client.ts): `packages/core/src/indexing/client.ts`
- [Index callbacks](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/runtime/events.ts): `packages/core/src/runtime/events.ts`

### Storage and schema

- [Onchain schema](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/drizzle/index.ts): `packages/core/src/drizzle/index.ts`
- [Indexing store](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/indexing-store/index.ts): `packages/core/src/indexing-store/index.ts`
- [Database layer](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/database/index.ts): `packages/core/src/database/index.ts`
- [SQL query builder](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/database/queryBuilder.ts): `packages/core/src/database/queryBuilder.ts`

### Query interfaces

- [GraphQL API](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/graphql/index.ts): `packages/core/src/graphql/index.ts`
- [HTTP server](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/server/index.ts): `packages/core/src/server/index.ts`
- [Typed client](https://github.com/ponder-sh/ponder/blob/main/packages/client/src/index.ts): `packages/client/src/index.ts`
- [React bindings](https://github.com/ponder-sh/ponder/blob/main/packages/react/src/context.ts): `packages/react/src/context.ts`

### Runtime operations

- [Development UI](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/ui/index.ts): `packages/core/src/ui/index.ts`
- [Runtime metrics](https://github.com/ponder-sh/ponder/blob/main/packages/core/src/internal/metrics.ts): `packages/core/src/internal/metrics.ts`

### Other components

- **Developer**
- **API consumer**
- **EVM RPC**
- **Postgres**

## Connections

- Developer → Project generator: creates project
- Project generator → Project template: uses template
- Developer → Ponder CLI: starts runtime
- Chain configuration → Event filters: defines filters
- Ponder CLI → Indexing runtime: starts indexing
- Indexing runtime → Multichain runtime: coordinates chains
- Multichain runtime → Historical sync: runs backfill
- Multichain runtime → Realtime sync: runs realtime
- Historical sync → Indexing RPC client: fetches history
- Realtime sync → Indexing RPC client: fetches blocks
- Event filters → Indexing RPC client: narrows requests
- Indexing RPC client → EVM RPC: requests chain data
- Indexing runtime → Index callbacks: dispatches events
- Index callbacks → Database layer: writes indexed data
- Onchain schema → Database layer: defines tables
- Indexing store → Database layer: stages index state
- Database layer → Postgres: persists data
- HTTP server → GraphQL API: routes GraphQL
- HTTP server → SQL query builder: routes SQL
- GraphQL API → Database layer: reads indexed data
- SQL query builder → Database layer: executes queries
- API consumer → HTTP server: sends queries
- Typed client → HTTP server: requests data
- React bindings → Typed client: provides client
- Indexing runtime → Runtime metrics: reports progress
- Development UI → Runtime metrics: reads progress
