# quemsah/awesome-claude-plugins architecture

> Architecture diagram of the GitHub repository quemsah/awesome-claude-plugins, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quemsah/awesome-claude-plugins
- Repository: https://github.com/quemsah/awesome-claude-plugins

## Overview

This repository indexes GitHub repositories that contain Claude Code plugins, publishes validated catalog snapshots, and serves them through a searchable web catalog. The main flow is crawler discovery, GitHub enrichment, durable run tracking, snapshot validation/publication, then UI browsing and repository detail/Markdown delivery. The README excerpt identifies the product and catalog scale; source evidence is partial, so uncertain implementation links—especially crawler-to-UI data handoff and unsampled UI routes—are omitted.

Main entry points: [`crawler/src/service/execute.ts`](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/service/execute.ts) (Run orchestration), [`crawler/src/publish/publishRun.ts`](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/publish/publishRun.ts) (Publication coordinator), [`crawler/src/crawl/enrich.ts`](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/enrich.ts) (Repository enrichment), [`crawler/src/github/client.ts`](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/client.ts) (GitHub API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crawl["Crawler pipeline"]
  node_cli["Crawler CLI<br/>[cli.ts]"]
  node_execution["Run orchestration<br/>[execute.ts]"]
  node_discovery["Repository discovery<br/>[discover.ts]"]
  node_enrichment["Repository enrichment<br/>[enrich.ts]"]
  node_crawlrun["Crawl coordinator<br/>[runCrawl.ts]"]
end

subgraph group_github["GitHub access"]
  node_githubclient["GitHub API client<br/>[client.ts]"]
  node_ratebudget["Rate budgeting<br/>[rateBudget.ts]"]
  node_marketplace["Marketplace parsing<br/>[marketplace.ts]"]
end

subgraph group_state["Crawler state"]
  node_repos[("Repository records<br/>[repositories.ts]")]
  node_runs[("Run records<br/>[runs.ts]")]
  node_database[("SQLite database<br/>[db.ts]")]
end

subgraph group_publish["Catalog publishing"]
  node_publisher["Publication coordinator<br/>[publishRun.ts]"]
  node_snapshot["Snapshot rendering<br/>[catalogSnapshot.ts]"]
  node_readme["README rendering<br/>[readme.ts]"]
  node_validation["Snapshot validation<br/>[validate.ts]"]
  node_gitpublish["Git publication<br/>[githubGit.ts]"]
  node_telegram["Telegram reporting<br/>[telegram.ts]"]
end

subgraph group_web["Catalog web app"]
  node_searchui["Catalog browsing<br/>[SearchPage.tsx]"]
  node_catalogapi["Catalog API<br/>[route.ts]"]
  node_cataloglib["Catalog search logic<br/>[catalog.ts]"]
  node_repodetail["Repository detail<br/>[RepoPageClient.tsx]"]
  node_markdownroutes["Markdown endpoints<br/>[markdown.ts]"]
  node_liveresource["Live repository lookup"]
end

node_operator(("Operator"))
node_visitor(("Catalog visitor"))
node_githubservice["GitHub"]

node_operator -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_execution
node_execution -->|"starts crawl"| node_crawlrun
node_crawlrun -->|"runs discovery"| node_discovery
node_crawlrun -->|"runs enrichment"| node_enrichment
node_enrichment -->|"fetches metadata"| node_githubclient
node_enrichment -->|"parses manifests"| node_marketplace
node_githubclient -->|"uses budget"| node_ratebudget
node_githubclient -.->|"requests data"| node_githubservice
node_discovery -.->|"searches GitHub"| node_githubclient
node_discovery -.->|"records candidates"| node_repos
node_enrichment -->|"updates records"| node_repos
node_execution -->|"tracks run"| node_runs
node_repos -.->|"persists in"| node_database
node_runs -.->|"persists in"| node_database
node_execution -->|"publishes run"| node_publisher
node_publisher -->|"renders files"| node_snapshot
node_publisher -->|"renders README"| node_readme
node_publisher -->|"validates snapshot"| node_validation
node_publisher -.->|"commits catalog"| node_gitpublish
node_execution -.->|"reports run"| node_telegram
node_visitor -.->|"browses"| node_searchui
node_searchui -.->|"requests results"| node_catalogapi
node_catalogapi -->|"searches catalog"| node_cataloglib
node_repodetail -.->|"loads live data"| node_liveresource
node_liveresource -->|"fetches repository"| node_githubservice
node_markdownroutes -->|"reads catalog"| node_cataloglib

click node_cli "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/cli.ts"
click node_execution "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/service/execute.ts"
click node_discovery "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/discover.ts"
click node_enrichment "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/enrich.ts"
click node_crawlrun "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/runCrawl.ts"
click node_githubclient "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/client.ts"
click node_ratebudget "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/rateBudget.ts"
click node_marketplace "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/marketplace.ts"
click node_repos "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/repositories.ts"
click node_runs "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/runs.ts"
click node_database "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/db.ts"
click node_publisher "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/publish/publishRun.ts"
click node_snapshot "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/catalogSnapshot.ts"
click node_readme "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/readme.ts"
click node_validation "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/validate.ts"
click node_gitpublish "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/publish/githubGit.ts"
click node_telegram "https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/notify/telegram.ts"
click node_searchui "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/components/search/SearchPage.tsx"
click node_catalogapi "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/app/api/catalog/route.ts"
click node_cataloglib "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/lib/catalog.ts"
click node_repodetail "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/components/repo/RepoPageClient.tsx"
click node_markdownroutes "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/lib/markdown.ts"
click node_liveresource "https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/hooks/useLiveRepository.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_cli,node_execution,node_discovery,node_enrichment,node_crawlrun toneBlue
class node_githubclient,node_ratebudget,node_marketplace toneAmber
class node_repos,node_runs,node_database toneMint
class node_publisher,node_snapshot,node_readme,node_validation,node_gitpublish,node_telegram toneRose
class node_searchui,node_catalogapi,node_cataloglib,node_repodetail,node_markdownroutes,node_liveresource,node_operator,node_visitor,node_githubservice toneIndigo
```

## Components

### Crawler pipeline

- [Crawler CLI](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/cli.ts): `crawler/src/cli.ts`
- [Run orchestration](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/service/execute.ts): `crawler/src/service/execute.ts`
- [Repository discovery](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/discover.ts): `crawler/src/crawl/discover.ts`
- [Repository enrichment](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/enrich.ts): `crawler/src/crawl/enrich.ts`
- [Crawl coordinator](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/crawl/runCrawl.ts): `crawler/src/crawl/runCrawl.ts`

### GitHub access

- [GitHub API client](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/client.ts): `crawler/src/github/client.ts`
- [Rate budgeting](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/rateBudget.ts): `crawler/src/github/rateBudget.ts`
- [Marketplace parsing](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/github/marketplace.ts): `crawler/src/github/marketplace.ts`

### Crawler state

- [Repository records](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/repositories.ts): `crawler/src/storage/repositories.ts`
- [Run records](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/runs.ts): `crawler/src/storage/runs.ts`
- [SQLite database](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/storage/db.ts): `crawler/src/storage/db.ts`

### Catalog publishing

- [Publication coordinator](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/publish/publishRun.ts): `crawler/src/publish/publishRun.ts`
- [Snapshot rendering](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/catalogSnapshot.ts): `crawler/src/output/catalogSnapshot.ts`
- [README rendering](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/readme.ts): `crawler/src/output/readme.ts`
- [Snapshot validation](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/output/validate.ts): `crawler/src/output/validate.ts`
- [Git publication](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/publish/githubGit.ts): `crawler/src/publish/githubGit.ts`
- [Telegram reporting](https://github.com/quemsah/awesome-claude-plugins/blob/main/crawler/src/notify/telegram.ts): `crawler/src/notify/telegram.ts`

### Catalog web app

- [Catalog browsing](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/components/search/SearchPage.tsx): `ui/src/components/search/SearchPage.tsx`
- [Catalog API](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/app/api/catalog/route.ts): `ui/src/app/api/catalog/route.ts`
- [Catalog search logic](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/lib/catalog.ts): `ui/src/lib/catalog.ts`
- [Repository detail](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/components/repo/RepoPageClient.tsx): `ui/src/components/repo/RepoPageClient.tsx`
- [Markdown endpoints](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/lib/markdown.ts): `ui/src/lib/markdown.ts`
- [Live repository lookup](https://github.com/quemsah/awesome-claude-plugins/blob/main/ui/src/hooks/useLiveRepository.ts): `ui/src/hooks/useLiveRepository.ts`

### Other components

- **Operator**
- **Catalog visitor**
- **GitHub**

## Connections

- Operator → Crawler CLI: invokes (evidence: `crawler/src/cli.ts`)
- Crawler CLI → Run orchestration: dispatches (evidence: `crawler/src/cli.ts`)
- Run orchestration → Crawl coordinator: starts crawl (evidence: `crawler/src/service/execute.ts`)
- Crawl coordinator → Repository discovery: runs discovery (evidence: `crawler/src/crawl/runCrawl.ts`)
- Crawl coordinator → Repository enrichment: runs enrichment (evidence: `crawler/src/crawl/runCrawl.ts`)
- Repository enrichment → GitHub API client: fetches metadata (evidence: `crawler/src/crawl/enrich.ts`)
- Repository enrichment → Marketplace parsing: parses manifests (evidence: `crawler/src/crawl/enrich.ts`)
- GitHub API client → Rate budgeting: uses budget (evidence: `crawler/src/github/client.ts`)
- GitHub API client → GitHub: requests data
- Repository discovery → GitHub API client: searches GitHub
- Repository discovery → Repository records: records candidates
- Repository enrichment → Repository records: updates records (evidence: `crawler/src/crawl/enrich.ts`)
- Run orchestration → Run records: tracks run (evidence: `crawler/src/service/execute.ts`)
- Repository records → SQLite database: persists in
- Run records → SQLite database: persists in
- Run orchestration → Publication coordinator: publishes run (evidence: `crawler/src/service/execute.ts`)
- Publication coordinator → Snapshot rendering: renders files (evidence: `crawler/src/publish/publishRun.ts`)
- Publication coordinator → README rendering: renders README (evidence: `crawler/src/publish/publishRun.ts`)
- Publication coordinator → Snapshot validation: validates snapshot (evidence: `crawler/src/publish/publishRun.ts`)
- Publication coordinator → Git publication: commits catalog (evidence: `crawler/src/publish/publishRun.ts`)
- Run orchestration → Telegram reporting: reports run (evidence: `crawler/src/service/execute.ts`)
- Catalog visitor → Catalog browsing: browses
- Catalog browsing → Catalog API: requests results
- Catalog API → Catalog search logic: searches catalog (evidence: `ui/src/app/api/catalog/route.ts`)
- Repository detail → Live repository lookup: loads live data
- Live repository lookup → GitHub: fetches repository (evidence: `ui/src/hooks/useLiveRepository.ts`)
- Markdown endpoints → Catalog search logic: reads catalog (evidence: `ui/src/lib/markdown.ts`)