# checkpoint-labs/checkpoint architecture

> Architecture diagram of the GitHub repository checkpoint-labs/checkpoint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/checkpoint-labs/checkpoint
- Repository: https://github.com/checkpoint-labs/checkpoint

## Overview

##### Main Components
- Providers: This is the layer responsible for interacting with blockchain networks. Notice there are subdirectories for EVM and StarkNet. Each of these includes provider logic, indexers, and utility functions, so these become distinct components.
- GraphQL API Layer: Located under src/graphql, this includes the controller, resolvers, and index that likely form the gateway through which indexed contract data is queried.
- Data Storage and ORM: The files under src/orm and the Knex configuration (src/knex.ts) indicate the project leverages a relational database abstraction. The pg.ts file also hints at managing Postgres connections or queries.
- Core Library and Utilities: The main entry points and supporting utilities, including src/index.ts, src/checkpoint.ts, and src/codegen.ts, which help tie the components together.
- Dependency Injection & Container: The container.ts file suggests that dependency injection is used to manage module lifecycles.
- Stores & Caching: The src/stores directory (e.g., checkpoints.ts) represents any in-memory or temporary storage mechanisms that may cache or manage indexed data.

##### Relationships and Interactions
- The Providers (EVM & StarkNet) act as data sources that index blockchain events or state changes. They interact with the data storage and ORM layers to persist data.
- The GraphQL layer consumes the stored data and exposes a read-only API to consumers. The resolvers encapsulate the business logic needed to fetch and transform data from the ORM.
- The Container/Dependency Injection layer ties together providers, GraphQL controllers, and storage components, ensuring that each module’s lifecycle and dependencies are managed coherently.
- Utility modules provide supporting functions, logging, and error-handling that are used across these layers.
- Codegen and Checkpoint configuration files likely facilitate automated type generation or schema derivation from defined entities within the ORM.

##### Architectural Patterns & Principles
- Modular Architecture: Each major functionality (data providers, GraphQL API, Data Storage) is isolated in its own directory. This modular approach improves clarity and reusability.
- Separation of Concerns: The design separates data ingestion (providers/indexers) from data exposure (GraphQL) and persistence (ORM/database).
- Dependency Injection: The container pattern helps manage dependencies across the various modules.
- Event-driven/Indexing Workflow: The architecture likely follows a publish-subscribe or event-based pattern where providers detect blockchain events, index data, and update the datastore in near real-time.

##### Relevant Technologies & Frameworks
- GraphQL: Indicated by files under src/graphql, handling queries, controllers, and resolvers.
- Knex and PostgreSQL: For ORM and database interactions.
- TypeScript: Evident from tsconfig.json and the file types (e.g., .ts files in src).
- Testing Frameworks: Jest is configured for unit tests.
- Dependency injection container, which may be internally developed or integrated through a library.

##### Specific Elements
- Clear labels for each component:
- “StarkNet Provider” and “EVM Provider” under a “Blockchain Data Providers” section.
- “GraphQL API” subdivided into “Controller”, “Resolvers”, and “Schema”.
- “Database & ORM” to include Knex, Postgres (pg.ts), and Model definitions.
- “Core Library/Logic” featuring Checkpoint, Codegen, and Container.
- From blockchain providers to the indexing workflow.
- From database/ORM to GraphQL components.
- From the dependency injection container to individual subsystems.

##### Final Assembly
- Data Ingestion (Providers, Indexers)
- Data Persistence (ORM, Database)
- API Exposure (GraphQL Interface)
- Supporting elements such as the dependency injection container and utility modules feeding into these layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion"
        SP["StarkNet Provider"]:::providers
        EV["EVM Provider"]:::providers
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        ORM["Database & ORM"]:::orm
        KEX["Knex Configuration"]:::ormConfig
        PG["Postgres Handler"]:::ormConfig
        STORES["Stores & Caching"]:::stores
        KEX --> ORM
        PG --> ORM
        ORM --> STORES
    end

    %% API Exposure Layer
    subgraph "API Exposure"
        GQL["GraphQL API"]:::api
    end

    %% Core Library & Utilities
    subgraph "Core & Utilities"
        CORE["Core Library"]:::core
        UTILS["Utility Functions"]:::core
    end

    %% Dependency Injection Container (Centralized)
    DI["Dependency Injection Container"]:::container

    %% Relationships: Providers feed into Persistence
    SP -->|"indexes"| ORM
    EV -->|"indexes"| ORM

    %% Persistence feeds data into API
    ORM -->|"servesData"| GQL

    %% Core Library & Utilities support Persistence and API
    CORE --> ORM
    CORE --> GQL
    UTILS --> ORM
    UTILS --> GQL

    %% Dependency Injection manages all critical modules
    DI --> SP
    DI --> EV
    DI --> ORM
    DI --> GQL
    DI --> CORE
    DI --> UTILS

    %% Styles definitions (with colors)
    classDef providers fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef orm fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef ormConfig fill:#87cefa,stroke:#333,stroke-width:2px;
    classDef api fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef core fill:#f4a460,stroke:#333,stroke-width:2px;
    classDef container fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef stores fill:#ffdead,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click SP "https://github.com/checkpoint-labs/checkpoint/tree/master/src/providers/starknet"
    click EV "https://github.com/checkpoint-labs/checkpoint/tree/master/src/providers/evm"
    click GQL "https://github.com/checkpoint-labs/checkpoint/tree/master/src/graphql"
    click ORM "https://github.com/checkpoint-labs/checkpoint/tree/master/src/orm"
    click KEX "https://github.com/checkpoint-labs/checkpoint/blob/master/src/knex.ts"
    click PG "https://github.com/checkpoint-labs/checkpoint/blob/master/src/pg.ts"
    click CORE "https://github.com/checkpoint-labs/checkpoint/blob/master/src/index.ts"
    click UTILS "https://github.com/checkpoint-labs/checkpoint/tree/master/src/utils"
    click DI "https://github.com/checkpoint-labs/checkpoint/blob/master/src/container.ts"
    click STORES "https://github.com/checkpoint-labs/checkpoint/tree/master/src/stores"
```
