Architecture

System Overview

The Leaderboard system follows a build-time data aggregation pattern with static site generation.

Components

1. Plugin Runner (`@leaderboard/plugin-runner`)

Purpose: Orchestrate data collection and management

Responsibilities:

Load configuration from config.yaml
Fetch and validate plugins from URLs
Import existing data from data-repo
Execute plugin setup, scrape, and aggregate methods
Run standard aggregation and badge evaluation
Export updated data back to data-repo

CLI Commands:

plugin-runner --data-dir=/path/to/data

2. API Layer (`@ohcnetwork/leaderboard-api`)

Purpose: Unified database utilities and plugin type definitions

Technology: LibSQL (SQLite-compatible)

Schema:

contributor - User profiles and metadata
activity_definition - Activity types defined by plugins
activity - Individual activity records

Storage:

Default location: ${DATA_DIR}/.leaderboard.db
Persists activity_definition table across runs
Temporary storage for contributor and activity tables

Provides:

Database abstraction layer
Query builders and helpers
TypeScript type definitions
Plugin interface specification
Context object structure

Example Plugin:

import type { Plugin } from "@ohcnetwork/leaderboard-api";

export default {
  name: "my-plugin",
  version: "1.0.0",
  async setup(ctx) {
    // Define activity types
  },
  async scrape(ctx) {
    // Fetch and store activities
  },
  async aggregate(ctx) {
    // Optional: Compute plugin-specific aggregates
  },
} satisfies Plugin;

4. Next.js Application (`apps/leaderboard-web`)

Purpose: Generate static website

Features:

Server-Side Generation (SSG) at build time
Reads data directly from LibSQL database
Markdown documentation via Fumadocs
Customizable themes via CSS

Pages:

/ - Home page with overview
/leaderboard - Rankings and leaderboards
/people - All contributors
/[username] - Individual contributor profiles
/badges - Badge definitions and achievements
/data - Data Explorer (browser-based SQL REPL)
/docs - Documentation

Data Flow

Build Process

Import Phase

data-repo/contributors/*.md → LibSQL
data-repo/activities/*.jsonl → LibSQL

Setup Phase

For each plugin:
  Execute plugin.setup(ctx)
  → Populate activity_definition table

Scrape Phase

For each plugin:
  Execute plugin.scrape(ctx)
  → Fetch data from API
  → Insert activities into database

Aggregation Phase

Calculate standard global aggregates
Calculate standard contributor aggregates

Plugin Aggregation Phase

For each plugin (with aggregate method):
  Execute plugin.aggregate(ctx)
  → Compute plugin-specific aggregates

Export Phase

LibSQL → data-repo/contributors/*.md
LibSQL → data-repo/activities/*.jsonl

Build Phase

Next.js reads LibSQL
→ Generate static pages
→ Copy .leaderboard.db to public/data.db
→ Output static site

In addition to the pre-rendered static pages, the database file is shipped as a static asset (public/data.db). The Data Explorer page loads this database in the browser via sql.js-httpvfs (SQLite compiled to WebAssembly). A Web Worker makes HTTP range requests to fetch only the database pages needed for each query, enabling ad-hoc SQL queries without any backend.