Document ENSIndexer startup sequence

[lightwalker-eth]

Goal: When someone who is unfamiliar with Ponder opens up the code for ENSIndexer for the first time, ideally we could have documentation available for what files are executed in which order. This will help people new to the ENSIndexer codebase orient themselves.

[tk-o]

Feel free to go through this Slack thread as it describes the ENSIndexer startup sequence in details.

[tk-o]

Caution

This is an AI generated summary from an initial part of the Slack thread I linked to above. It aims to visualise the starting sequence overview.

ENSIndexer: Architecture and Execution Flow

This document provides a high-level orientation for developers new to the ENSIndexer codebase. It outlines the specific order of file execution and the external dependencies required for a successful boot sequence.

---

1. High-Level Execution Flow

When the ENSIndexer process starts, it follows a deterministic path defined by Ponder to initialize the environment before it begins processing blockchain events.

Step-by-Step Sequence

1. Schema Retrieval (ponder.schema.ts): Ponder first reads this file to define the "concrete" ENSIndexer Schema. This acts as the blueprint for the entire data structure used while indexing onchain data.
2. Configuration Loading (ponder.config.ts): Ponder reads this file to understand database connection details, contract addresses, and RPC endpoints, etc..
3. Database Provisioning (ENSDb): Using the schema from Step 1, the Ponder creates the actual tables and enums inside the ENSDb instance.
4. Concurrent Runtime: Once the database is ready, the indexer triggers two processes simultaneously:
   • Omnichain Indexing: Event handlers begin processing onchain data.
   • HTTP Server: An API server starts to serve the indexed data.

graph TD
    A[Start ENSIndexer] --> B[Read ponder.schema.ts]
    B --> C[Read ponder.config.ts]
    C --> D[Provision Tables/Enums for the _concrete_ ENSIndexer Schema in ENSDb]
    D --> E{Concurrent Runtime}
    E --> F[Omnichain Indexing / Event Handlers]
    E --> G[HTTP Server]
    G --> H[Execute database migrations for the ENSNode Schema in ENSDb]
    H --> I[Populate data into the ENSNode Schema in ENSDb]

Loading

[lightwalker-eth]

@tk-o The goals for this issue are highly related to the work you're doing currently. Suggest we work on this goal at the same time while all of this info is fresh and at the top of your mind 👍

[tk-o]

Sharing the current view of the architecture diagram:

[tk-o]

Sharing refined version of the diagram

[tk-o]

Solved with #2012