# hikariming/ghfind architecture

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

- Interactive diagram: https://gitdiagram.com/hikariming/ghfind
- Repository: https://github.com/hikariming/ghfind

## Overview

ghfind is a GitHub developer scoring and discovery platform, with a web app, public API/MCP/SDK surfaces, personalized feed, and a GitHub App that labels incoming issues and pull requests. The main user path is a browser request to scan a GitHub profile, fetch public GitHub data, compute a score, and display discovery/profile results; roast generation is a separate LLM-assisted path. The README documents these capabilities, while source excerpts show selected route wiring. Several runtime and data-layer connections are therefore omitted rather than inferred.

Main entry points: [`src/app/api/scan/route.ts`](https://github.com/hikariming/ghfind/blob/main/src/app/api/scan/route.ts) (Profile scan API), [`src/app/mcp/route.ts`](https://github.com/hikariming/ghfind/blob/main/src/app/mcp/route.ts) (MCP tools), [`src/app/api/score/[username]/route.ts`](https://github.com/hikariming/ghfind/blob/main/src/app/api/score/%5Busername%5D/route.ts) (Score endpoint), [`src/lib/github.ts`](https://github.com/hikariming/ghfind/blob/main/src/lib/github.ts) (GitHub data collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scoring["Scoring and assessment"]
  node_scan_api["Profile scan API<br/>[route.ts]"]
  node_github_data["GitHub data collection<br/>[github.ts]"]
  node_scoring_engine["Deterministic scoring"]
  node_roast_api["Roast generation<br/>[route.ts]"]
  node_llm_client["LLM integration<br/>[llm.ts]"]
  node_persistence[("Profile and score storage<br/>[db.ts]")]
end

subgraph group_discovery["Discovery and profiles"]
  node_discovery_api["Developer discovery<br/>[route.ts]"]
  node_leaderboard_api["Leaderboard<br/>[route.ts]"]
  node_profile_view["Developer profiles<br/>[page.tsx]"]
  node_share_cards["Profile cards and badges<br/>[route.tsx]"]
end

subgraph group_interfaces["Web and developer interfaces"]
  node_web["Web experience<br/>[page.tsx]"]
  node_score_api["Score endpoint<br/>[route.ts]"]
  node_mcp_api["MCP tools<br/>[route.ts]"]
  node_sdk_js["JavaScript SDK<br/>[client.ts]"]
  node_sdk_py["Python SDK<br/>[client.py]"]
end

subgraph group_feed["Personalized feed"]
  node_feed_api["Feed API<br/>[main.go]"]
  node_feed_runtime["Feed runtime<br/>[router.ts]"]
  node_feed_storage[("Feed data store<br/>[store.ts]")]
end

subgraph group_review["GitHub issue review"]
  node_github_app["GitHub Review App<br/>[review.ts]"]
end

node_visitor(("Developer"))
node_github_service["GitHub"]
node_llm_service["LLM provider"]

node_visitor -->|"uses"| node_web
node_web -->|"requests scan"| node_scan_api
node_scan_api -->|"fetches profile"| node_github_data
node_github_data -->|"reads public data"| node_github_service
node_scan_api -->|"scores metrics"| node_scoring_engine
node_scan_api -->|"caches result"| node_persistence
node_visitor -->|"requests roast"| node_roast_api
node_roast_api -->|"generates report"| node_llm_client
node_llm_client -->|"calls provider"| node_llm_service
node_visitor -->|"requests score"| node_score_api
node_visitor -->|"finds developers"| node_discovery_api
node_visitor -->|"browses rankings"| node_leaderboard_api
node_visitor -->|"views profile"| node_profile_view
node_profile_view -->|"shares identity"| node_share_cards
node_visitor -->|"uses agent tools"| node_mcp_api
node_mcp_api -->|"searches developers"| node_discovery_api
node_mcp_api -->|"gets leaderboard"| node_leaderboard_api
node_sdk_js -->|"calls API"| node_score_api
node_sdk_py -->|"calls API"| node_score_api
node_feed_api -->|"configures feed"| node_feed_runtime
node_feed_runtime -.->|"uses storage"| node_feed_storage
node_github_app -->|"labels issues"| node_github_service

click node_web "https://github.com/hikariming/ghfind/blob/main/src/app/%5Blocale%5D/page.tsx"
click node_scan_api "https://github.com/hikariming/ghfind/blob/main/src/app/api/scan/route.ts"
click node_github_data "https://github.com/hikariming/ghfind/blob/main/src/lib/github.ts"
click node_scoring_engine "https://github.com/hikariming/ghfind/tree/main/src/lib"
click node_roast_api "https://github.com/hikariming/ghfind/blob/main/src/app/api/roast/route.ts"
click node_llm_client "https://github.com/hikariming/ghfind/blob/main/src/lib/llm.ts"
click node_score_api "https://github.com/hikariming/ghfind/blob/main/src/app/api/score/%5Busername%5D/route.ts"
click node_discovery_api "https://github.com/hikariming/ghfind/blob/main/src/app/api/developers/route.ts"
click node_leaderboard_api "https://github.com/hikariming/ghfind/blob/main/src/app/api/leaderboard/route.ts"
click node_profile_view "https://github.com/hikariming/ghfind/blob/main/src/app/%5Blocale%5D/u/%5Busername%5D/page.tsx"
click node_share_cards "https://github.com/hikariming/ghfind/blob/main/src/app/api/card/%5Busername%5D/route.tsx"
click node_persistence "https://github.com/hikariming/ghfind/blob/main/src/lib/db.ts"
click node_mcp_api "https://github.com/hikariming/ghfind/blob/main/src/app/mcp/route.ts"
click node_sdk_js "https://github.com/hikariming/ghfind/blob/main/packages/ghfind-js/src/client.ts"
click node_sdk_py "https://github.com/hikariming/ghfind/blob/main/packages/ghfind-py/ghfind/client.py"
click node_feed_api "https://github.com/hikariming/ghfind/blob/main/cmd/ghfind-api/main.go"
click node_feed_runtime "https://github.com/hikariming/ghfind/blob/main/platform/runtime/src/router.ts"
click node_feed_storage "https://github.com/hikariming/ghfind/blob/main/platform/feed/src/store.ts"
click node_github_app "https://github.com/hikariming/ghfind/blob/main/platform/github-app/src/review.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_scan_api,node_github_data,node_scoring_engine,node_roast_api,node_llm_client,node_persistence toneBlue
class node_discovery_api,node_leaderboard_api,node_profile_view,node_share_cards toneAmber
class node_web,node_score_api,node_mcp_api,node_sdk_js,node_sdk_py toneMint
class node_feed_api,node_feed_runtime,node_feed_storage toneRose
class node_github_app,node_visitor,node_github_service,node_llm_service toneIndigo
```

## Components

### Scoring and assessment

- [Profile scan API](https://github.com/hikariming/ghfind/blob/main/src/app/api/scan/route.ts): `src/app/api/scan/route.ts`
- [GitHub data collection](https://github.com/hikariming/ghfind/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Deterministic scoring](https://github.com/hikariming/ghfind/tree/main/src/lib): `src/lib`
- [Roast generation](https://github.com/hikariming/ghfind/blob/main/src/app/api/roast/route.ts): `src/app/api/roast/route.ts`
- [LLM integration](https://github.com/hikariming/ghfind/blob/main/src/lib/llm.ts): `src/lib/llm.ts`
- [Profile and score storage](https://github.com/hikariming/ghfind/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Discovery and profiles

- [Developer discovery](https://github.com/hikariming/ghfind/blob/main/src/app/api/developers/route.ts): `src/app/api/developers/route.ts`
- [Leaderboard](https://github.com/hikariming/ghfind/blob/main/src/app/api/leaderboard/route.ts): `src/app/api/leaderboard/route.ts`
- [Developer profiles](https://github.com/hikariming/ghfind/blob/main/src/app/%5Blocale%5D/u/%5Busername%5D/page.tsx): `src/app/[locale]/u/[username]/page.tsx`
- [Profile cards and badges](https://github.com/hikariming/ghfind/blob/main/src/app/api/card/%5Busername%5D/route.tsx): `src/app/api/card/[username]/route.tsx`

### Web and developer interfaces

- [Web experience](https://github.com/hikariming/ghfind/blob/main/src/app/%5Blocale%5D/page.tsx): `src/app/[locale]/page.tsx`
- [Score endpoint](https://github.com/hikariming/ghfind/blob/main/src/app/api/score/%5Busername%5D/route.ts): `src/app/api/score/[username]/route.ts`
- [MCP tools](https://github.com/hikariming/ghfind/blob/main/src/app/mcp/route.ts): `src/app/mcp/route.ts`
- [JavaScript SDK](https://github.com/hikariming/ghfind/blob/main/packages/ghfind-js/src/client.ts): `packages/ghfind-js/src/client.ts`
- [Python SDK](https://github.com/hikariming/ghfind/blob/main/packages/ghfind-py/ghfind/client.py): `packages/ghfind-py/ghfind/client.py`

### Personalized feed

- [Feed API](https://github.com/hikariming/ghfind/blob/main/cmd/ghfind-api/main.go): `cmd/ghfind-api/main.go`
- [Feed runtime](https://github.com/hikariming/ghfind/blob/main/platform/runtime/src/router.ts): `platform/runtime/src/router.ts`
- [Feed data store](https://github.com/hikariming/ghfind/blob/main/platform/feed/src/store.ts): `platform/feed/src/store.ts`

### GitHub issue review

- [GitHub Review App](https://github.com/hikariming/ghfind/blob/main/platform/github-app/src/review.ts): `platform/github-app/src/review.ts`

### Other components

- **Developer**
- **GitHub**
- **LLM provider**

## Connections

- Developer → Web experience: uses (evidence: `README.md`)
- Web experience → Profile scan API: requests scan (evidence: `README.md`)
- Profile scan API → GitHub data collection: fetches profile (evidence: `README.md`)
- GitHub data collection → GitHub: reads public data (evidence: `README.md`)
- Profile scan API → Deterministic scoring: scores metrics (evidence: `README.md`)
- Profile scan API → Profile and score storage: caches result (evidence: `README.md`)
- Developer → Roast generation: requests roast (evidence: `README.md`)
- Roast generation → LLM integration: generates report (evidence: `src/app/api/roast/route.ts`)
- LLM integration → LLM provider: calls provider (evidence: `README.md`)
- Developer → Score endpoint: requests score (evidence: `README.md`)
- Developer → Developer discovery: finds developers (evidence: `README.md`)
- Developer → Leaderboard: browses rankings (evidence: `README.md`)
- Developer → Developer profiles: views profile (evidence: `README.md`)
- Developer profiles → Profile cards and badges: shares identity (evidence: `README.md`)
- Developer → MCP tools: uses agent tools (evidence: `README.md`)
- MCP tools → Developer discovery: searches developers (evidence: `src/app/mcp/route.ts`)
- MCP tools → Leaderboard: gets leaderboard (evidence: `src/app/mcp/route.ts`)
- JavaScript SDK → Score endpoint: calls API (evidence: `README.md`)
- Python SDK → Score endpoint: calls API (evidence: `README.md`)
- Feed API → Feed runtime: configures feed (evidence: `cmd/ghfind-api/main.go`)
- Feed runtime → Feed data store: uses storage
- GitHub Review App → GitHub: labels issues (evidence: `README.md`)
