# awesome-dsh-plugin/dsh-find-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/awesome-dsh-plugin/dsh-find-plugin
- Repository: https://github.com/awesome-dsh-plugin/dsh-find-plugin

## Overview

This is a DSH agent plugin for discovering third-party DSH plugins. A user asks the agent for a capability; the registered tool searches GitHub, ranks live results by stars, enriches matching entries with curated bilingual descriptions, and returns install commands. If GitHub search fails, it searches the curated registry instead. The registry refreshes from the curated-list service and can use disk or bundled data offline. The excerpts show the tool orchestration and cache fallback; some registry and presentation details are documented rather than fully excerpted.

Main entry points: [`src/index.ts`](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/index.ts) (Find Tool), [`src/registry.ts`](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/registry.ts) (Registry Loader), [`src/github.ts`](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/github.ts) (GitHub Search), [`data/registry-snapshot.json`](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/data/registry-snapshot.json) (Bundled Snapshot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery"]
  node_tool["Find Tool<br/>[index.ts]"]
  node_github_search["GitHub Search<br/>[github.ts]"]
end

subgraph group_catalog["Curated Catalog"]
  node_registry_loader["Registry Loader<br/>[registry.ts]"]
  node_disk_cache[("Registry Cache<br/>[registry.ts]")]
  node_snapshot["Bundled Snapshot"]
end

subgraph group_integrations["External Services"]
  node_credential["Credential Service"]
  node_github_api["GitHub API"]
  node_curated_service["Curated Registry"]
end

node_user(("User"))
node_dsh["DSH Agent"]

node_user -->|"asks discovery"| node_dsh
node_dsh -->|"calls tool"| node_tool
node_tool -->|"returns results"| node_dsh
node_tool -->|"resolves token"| node_credential
node_tool -->|"searches query"| node_github_search
node_github_search -->|"requests repositories"| node_github_api
node_tool -->|"loads descriptions or fallback"| node_registry_loader
node_registry_loader -.->|"fetches and revalidates"| node_curated_service
node_registry_loader -->|"reads and writes"| node_disk_cache
node_registry_loader -->|"falls back to"| node_snapshot

click node_tool "https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/index.ts"
click node_github_search "https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/github.ts"
click node_registry_loader "https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/registry.ts"
click node_disk_cache "https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/registry.ts"
click node_snapshot "https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/data/registry-snapshot.json"

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_tool,node_github_search,node_user toneBlue
class node_registry_loader,node_disk_cache,node_snapshot toneAmber
class node_credential,node_github_api,node_curated_service toneMint
class node_dsh toneIndigo
```

## Components

### Discovery

- [Find Tool](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/index.ts): `src/index.ts`
- [GitHub Search](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/github.ts): `src/github.ts`

### Curated Catalog

- [Registry Loader](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/registry.ts): `src/registry.ts`
- [Registry Cache](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/src/registry.ts): `src/registry.ts`
- [Bundled Snapshot](https://github.com/awesome-dsh-plugin/dsh-find-plugin/blob/main/data/registry-snapshot.json): `data/registry-snapshot.json`

### External Services

- **Credential Service**
- **GitHub API**
- **Curated Registry**

### Other components

- **User**
- **DSH Agent**

## Connections

- User → DSH Agent: asks discovery (evidence: `README.md`)
- DSH Agent → Find Tool: calls tool (evidence: `README.md`)
- Find Tool → DSH Agent: returns results (evidence: `README.md`)
- Find Tool → Credential Service: resolves token (evidence: `src/index.ts`)
- Find Tool → GitHub Search: searches query (evidence: `src/index.ts`)
- GitHub Search → GitHub API: requests repositories (evidence: `src/github.ts`)
- Find Tool → Registry Loader: loads descriptions or fallback (evidence: `src/index.ts`)
- Registry Loader → Curated Registry: fetches and revalidates (evidence: `README.md`)
- Registry Loader → Registry Cache: reads and writes (evidence: `src/registry.ts`)
- Registry Loader → Bundled Snapshot: falls back to (evidence: `src/registry.ts`)