# chainapsis/keplr-app-registry architecture

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

- Interactive diagram: https://gitdiagram.com/chainapsis/keplr-app-registry
- Repository: https://github.com/chainapsis/keplr-app-registry

## Overview

This repository is **not** a runtime service; it’s a **content + validation + build pipeline** for the **Keplr Dashboard “Explore” app registry**.

Primary purpose inferred from README + tree:
- Repo provides **TypeScript CLI/scripts** to:
- validate each app’s metadata (`app.json`)
- enforce ordering rules via `sort-config.json`
- **generate** the canonical output artifact: **`app-list.json`**
- CI (GitHub Actions) runs these checks on push/PR.

So your “system” is mainly a **repository-driven data pipeline**: **Inputs (PR files) → validation → generation → published artifact → consumed by Keplr Dashboard**.

##### “Registry data” (source of truth)
- `apps/**/app.json` — per-app metadata
- `sort-config.json` — pinned ordering configuration (managed by Keplr team)
- `app-list.json` — generated output (explicitly “DON’T UPDATE directly”)

##### “Build/validation toolchain” (execution logic)
- `src/make-app-list.ts` — reads apps + sort config, outputs `app-list.json`
- `src/validate-app.ts` — validates app metadata constraints (category enum, URLs, required fields, etc.)
- `src/validate-sort-config.ts` — validates pinning config format/contents

##### “Automation / CI”
- `.github/workflows/pull-request.yml`
- `.github/workflows/push.yml`

##### “Runtime environment / packaging”
- `package.json` — scripts, dependencies, entry points
- `tsconfig.json` — TypeScript build/runtime settings
- Yarn Berry / PnP:
- `.yarnrc.yml`, `.pnp.cjs`, `.pnp.loader.mjs`, `.yarn/**`

##### What the README adds (important relationships & rules to show)
- Schema rules for `app.json`:
- `appCategory` must be one of a fixed list (case-sensitive)
- `externalUrls` requires at least one of twitter/github/discord
- optional `appWebsiteUrlsByChainId`
- `app-list.json` ordering algorithm:
1) pinned apps first (from `sort-config.json`)
2) all others alphabetically by `appName`
- `app-list.json` is generated, not manually edited
- Downstream consumer: **Keplr Dashboard Explore page**

##### For each `apps/<app>/`
- read `app.json` → validate schema/fields
##### Aggregate apps → apply ordering logic → write `app-list.json`

Make the per-app loop explicit (e.g., a “For each app folder” annotation), because that’s a core architectural behavior.

##### Repository data components
- `apps/<app>/app.json` (metadata)
- `sort-config.json` (pin list)
- `app-list.json` (generated registry output)

##### Tooling components (Node/TS)
- Node.js runtime
- Yarn 3 (Berry) with Plug’n’Play (PnP) resolver

##### Pipeline components
- GitHub Actions workflow: PR validation (`pull-request.yml`)
- GitHub Actions workflow: push/build (`push.yml`)

##### Downstream consumer
- Keplr Dashboard Explore page feature/module: “App directory renderer”

- “Adds/updates app submission” (Submitter → Repo)
- “Triggers CI” (PR/push → GitHub Actions)
- “Validates JSON schema & required fields” (CI → `validate-app.ts`)
- “Validates pinning config” (CI → `validate-sort-config.ts`)
- “Generates ordered list (pinned + alpha)” (CI → `make-app-list.ts`)
- “Produces artifact: app-list.json” (Toolchain → Repo output)
- “Consumes registry to render Explore page” (Keplr Dashboard → app-list.json)

##### Architectural patterns/design principles present (call these out
These are worth labeling because they explain “why it’s shaped this way”:
- **Repository-as-database**: Git stores the canonical registry entries.
- **Build-time generation**: `app-list.json` is a derived artifact to simplify downstream consumption.
- **CI as gatekeeper**: PR checks prevent invalid entries from merging.

##### GitHub Repo (main branch)
- contains: `apps/`, `sort-config.json`, generated `app-list.json`
##### Consumer: Keplr Dashboard Explore

And show:
- `apps/**` feeding both validation steps and generation
- `sort-config.json` feeding sort validation + generation
- `app-list.json` feeding Keplr Dashboard

This captures the essential architecture with maximal fidelity to the repository structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ================
  %% System Context
  %% ================
  subgraph "System Context"
    direction TB
    Submitter["App Submitter / Partner Project"]:::external
    Repo["GitHub Repository: Keplr Dashboard App Registry"]:::repo
    GHA["GitHub Actions CI"]:::ci
    Keplr["Keplr Dashboard (Explore Page)"]:::external
  end

  Submitter -->|"PullRequest:addOrUpdate apps/&lt;app&gt;/app.json + icon.png"| Repo
  Repo -.->|"pushOrPR triggers"| GHA
  GHA -.->|"statusChecks:passFail"| Repo
  Repo -->|"ConsumedBy:importAtBuildOrFetchAtRuntime"| Keplr

  %% ==========================
  %% Repo-as-Database (Data)
  %% ==========================
  subgraph "Repository Content Store (Repository-as-Database)"
    direction TB
    AppsDir[("apps/ (folders per app)")]:::data
    AppJson[("apps/**/app.json (metadata)")]:::data
    IconPng[("apps/**/icon.png (icon asset)")]:::data
    SortCfg[("sort-config.json (pinned ordering)")]:::data
    AppList[("app-list.json (generated; DO NOT EDIT)")]:::generated
  end

  Repo -->|"stores"| AppsDir
  AppsDir -->|"contains"| AppJson
  AppsDir -->|"contains"| IconPng
  Repo -->|"stores"| SortCfg
  Repo -->|"stores"| AppList

  %% ==========================
  %% Toolchain & Execution Env
  %% ==========================
  subgraph "Toolchain (Policy-as-Code + Build-time Generation)"
    direction TB

    subgraph "Packaging / Runtime"
      direction TB
      NodeRT["Node.js Runtime"]:::runtime
      TSRT["TypeScript Execution (ts-node or compiled JS)"]:::runtime
      Yarn["Yarn 3 (Berry) + Plug'n'Play"]:::runtime
      Package["package.json (scripts/deps)"]:::runtime
      TSConfig["tsconfig.json (TS config)"]:::runtime
      YarnRC[".yarnrc.yml (Yarn config)"]:::runtime
      PnpCjs[".pnp.cjs (PnP runtime map)"]:::runtime
      PnpLoader[".pnp.loader.mjs (PnP loader)"]:::runtime
      YarnDir[".yarn/ (Yarn toolchain)"]:::runtime
    end

    subgraph "Validation + Generation Steps (CLI scripts)"
      direction TB
      StepSort["validate-sort-config (src/validate-sort-config.ts)"]:::process
      Loop["ForEach:apps/&lt;app&gt;/"]:::note
      StepApp["validate-app (src/validate-app.ts)"]:::process
      StepIcon["validate-icon (src/validate-icon.ts)"]:::process
      StepMake["make-app-list (src/make-app-list.ts)"]:::process
    end
  end

  %% ==========================
  %% CI Workflows (Gatekeeper)
  %% ==========================
  subgraph "CI Orchestration (CI as Gatekeeper)"
    direction TB
    WFPR["Workflow: Pull Request (.github/workflows/pull-request.yml)"]:::ci
    WFPush["Workflow: Push (.github/workflows/push.yml)"]:::ci
  end

  %% Orchestration links
  GHA -->|"runs"| WFPR
  GHA -->|"runs"| WFPush

  %% Runtime/toolchain links
  WFPR -->|"uses"| Yarn
  WFPush -->|"uses"| Yarn
  Yarn -->|"resolvesDepsViaPnP"| PnpCjs
  Yarn -->|"loader"| PnpLoader
  Yarn -->|"configuredBy"| YarnRC
  Yarn -->|"toolchainFiles"| YarnDir
  WFPR -->|"invokesScriptsFrom"| Package
  WFPush -->|"invokesScriptsFrom"| Package
  Package -->|"tsConfig"| TSConfig
  WFPR -->|"executesOn"| NodeRT
  WFPush -->|"executesOn"| NodeRT
  NodeRT -->|"runs"| TSRT

  %% Data flow: validation
  WFPR -->|"step:validatePins"| StepSort
  WFPush -->|"step:validatePins"| StepSort
  SortCfg -->|"read"| StepSort

  StepSort -->|"then:validateEachApp"| Loop
  Loop -->|"perApp:validateMetadata"| StepApp
  Loop -->|"perApp:validateIcon"| StepIcon
  AppJson -->|"read"| StepApp
  IconPng -->|"read"| StepIcon

  %% Data flow: generation
  WFPR -->|"step:generateList"| StepMake
  WFPush -->|"step:generateList"| StepMake
  StepMake -->|"reads"| SortCfg
  StepMake -->|"reads"| AppJson
  StepMake -->|"appliesOrdering:pinnedThenAlpha(appName)"| StepMake
  StepMake -->|"writes"| AppList

  %% Downstream consumption
  Keplr -->|"readsRegistryArtifact"| AppList

  %% ==========================
  %% Click Events (component_mapping)
  %% ==========================
  click AppJson "https://github.com/chainapsis/keplr-app-registry/blob/main/apps/**/app.json"
  click IconPng "https://github.com/chainapsis/keplr-app-registry/blob/main/apps/**/icon.png"
  click SortCfg "https://github.com/chainapsis/keplr-app-registry/blob/main/sort-config.json"
  click AppList "https://github.com/chainapsis/keplr-app-registry/blob/main/app-list.json"
  click StepMake "https://github.com/chainapsis/keplr-app-registry/blob/main/src/make-app-list.ts"
  click StepApp "https://github.com/chainapsis/keplr-app-registry/blob/main/src/validate-app.ts"
  click StepIcon "https://github.com/chainapsis/keplr-app-registry/blob/main/src/validate-icon.ts"
  click StepSort "https://github.com/chainapsis/keplr-app-registry/blob/main/src/validate-sort-config.ts"
  click WFPR "https://github.com/chainapsis/keplr-app-registry/blob/main/.github/workflows/pull-request.yml"
  click WFPush "https://github.com/chainapsis/keplr-app-registry/blob/main/.github/workflows/push.yml"
  click Package "https://github.com/chainapsis/keplr-app-registry/blob/main/package.json"
  click TSConfig "https://github.com/chainapsis/keplr-app-registry/blob/main/tsconfig.json"
  click YarnRC "https://github.com/chainapsis/keplr-app-registry/blob/main/.yarnrc.yml"
  click PnpCjs "https://github.com/chainapsis/keplr-app-registry/blob/main/.pnp.cjs"
  click PnpLoader "https://github.com/chainapsis/keplr-app-registry/blob/main/.pnp.loader.mjs"
  click YarnDir "https://github.com/chainapsis/keplr-app-registry/tree/main/.yarn/"

  %% ==========================
  %% Styles
  %% ==========================
  classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef repo fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
  classDef ci fill:#FFEDD5,stroke:#C2410C,stroke-width:1px,color:#3B1A09
  classDef data fill:#E0F2FE,stroke:#0284C7,stroke-width:1px,color:#082F49
  classDef generated fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#052E16
  classDef process fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#451A03
  classDef runtime fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#1F1147
  classDef note fill:#FFFFFF,stroke:#9CA3AF,stroke-width:1px,color:#111827,stroke-dasharray: 4 3
```
