# shrivishalcr-wq/github-contribution-repo-finder architecture

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

- Interactive diagram: https://gitdiagram.com/shrivishalcr-wq/github-contribution-repo-finder
- Repository: https://github.com/shrivishalcr-wq/github-contribution-repo-finder

## Overview

This terminal agent turns a developer’s skills and preferences into ranked GitHub contribution recommendations. Its main workflow clarifies and extracts a profile, searches for repositories, inspects repository details and issues, then deterministically ranks candidates and presents results with an optional AI summary. Session memory preserves preferences across turns; GitHub response caching and centralized configuration support the runtime. The README and excerpts establish the orchestration and major capabilities; unsampled implementation details are represented only where documented, and edges are limited to shown calls or documented relationships.

Main entry points: [`agent.py`](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/agent.py) (Turn orchestrator), [`llm_client.py`](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py) (OpenRouter client), [`tools.py`](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tools.py) (Tool specifications), [`github_client.py`](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py) (Repository search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["Terminal CLI<br/>[main.py]"]
  node_presentation["Recommendations<br/>[tool_executor.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_agent["Turn orchestrator<br/>[agent.py]"]
  node_clarify["Profile clarification<br/>[llm_client.py]"]
  node_extract["Preference extraction<br/>[llm_client.py]"]
  node_candidates["Candidate assembly<br/>[tool_executor.py]"]
  node_ranking["Deterministic ranking<br/>[ranking.py]"]
end

subgraph group_discovery["Repository discovery"]
  node_tool_specs["Tool specifications<br/>[tools.py]"]
  node_executor["Tool dispatch and state<br/>[tool_executor.py]"]
  node_search["Repository search<br/>[github_client.py]"]
  node_details["Repository inspection<br/>[github_client.py]"]
  node_issues["Issue discovery<br/>[github_client.py]"]
end

subgraph group_support["Runtime support"]
  node_memory["Session memory<br/>[memory.py]"]
  node_llm["OpenRouter client<br/>[llm_client.py]"]
  node_cache[("API response cache<br/>[github_client.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_developer(("Developer"))
node_openrouter{{"OpenRouter API"}}
node_github_api{{"GitHub REST API"}}

node_developer -->|"enters request"| node_cli
node_cli -->|"delegates turn"| node_agent
node_cli -->|"initializes session"| node_memory
node_agent -->|"checks profile"| node_clarify
node_agent -->|"extracts preferences"| node_extract
node_agent -->|"reads and updates"| node_memory
node_agent -->|"requests completions"| node_llm
node_clarify -->|"uses chat requests"| node_llm
node_extract -->|"uses chat requests"| node_llm
node_llm -->|"sends requests"| node_openrouter
node_agent -->|"provides tool specs"| node_tool_specs
node_agent -->|"executes tool calls"| node_executor
node_executor -->|"dispatches allow-listed"| node_tool_specs
node_tool_specs -->|"dispatches search"| node_search
node_tool_specs -->|"dispatches inspection"| node_details
node_tool_specs -->|"dispatches issue lookup"| node_issues
node_search -->|"queries repositories"| node_github_api
node_details -->|"fetches metadata"| node_github_api
node_issues -->|"fetches open issues"| node_github_api
node_search -->|"uses response cache"| node_cache
node_details -->|"uses response cache"| node_cache
node_issues -->|"uses response cache"| node_cache
node_agent -->|"builds candidates"| node_candidates
node_agent -->|"ranks candidates"| node_ranking
node_agent -->|"prints results"| node_presentation
node_agent -->|"generates summary"| node_llm
node_llm -->|"reads API settings"| node_config
node_search -->|"reads API settings"| node_config

click node_cli "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/main.py"
click node_agent "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/agent.py"
click node_clarify "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py"
click node_extract "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py"
click node_memory "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/memory.py"
click node_llm "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py"
click node_tool_specs "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tools.py"
click node_executor "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py"
click node_search "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py"
click node_details "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py"
click node_issues "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py"
click node_cache "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py"
click node_candidates "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py"
click node_ranking "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/ranking.py"
click node_presentation "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py"
click node_config "https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/config.py"

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_presentation toneBlue
class node_agent,node_clarify,node_extract,node_candidates,node_ranking toneAmber
class node_tool_specs,node_executor,node_search,node_details,node_issues,node_openrouter,node_github_api toneMint
class node_memory,node_llm,node_cache,node_config toneRose
class node_developer toneIndigo
```

## Components

### User interaction

- [Terminal CLI](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/main.py): `main.py`
- [Recommendations](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py): `tool_executor.py`

### Agent orchestration

- [Turn orchestrator](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/agent.py): `agent.py`
- [Profile clarification](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py): `llm_client.py`
- [Preference extraction](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py): `llm_client.py`
- [Candidate assembly](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py): `tool_executor.py`
- [Deterministic ranking](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/ranking.py): `ranking.py`

### Repository discovery

- [Tool specifications](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tools.py): `tools.py`
- [Tool dispatch and state](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/tool_executor.py): `tool_executor.py`
- [Repository search](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py): `github_client.py`
- [Repository inspection](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py): `github_client.py`
- [Issue discovery](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py): `github_client.py`

### Runtime support

- [Session memory](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/memory.py): `memory.py`
- [OpenRouter client](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/llm_client.py): `llm_client.py`
- [API response cache](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/github_client.py): `github_client.py`
- [Runtime configuration](https://github.com/shrivishalcr-wq/github-contribution-repo-finder/blob/main/config.py): `config.py`

### Other components

- **Developer**
- **OpenRouter API**
- **GitHub REST API**

## Connections

- Developer → Terminal CLI: enters request (evidence: `README.md`)
- Terminal CLI → Turn orchestrator: delegates turn (evidence: `main.py`)
- Terminal CLI → Session memory: initializes session (evidence: `main.py`)
- Turn orchestrator → Profile clarification: checks profile (evidence: `agent.py`)
- Turn orchestrator → Preference extraction: extracts preferences (evidence: `agent.py`)
- Turn orchestrator → Session memory: reads and updates (evidence: `agent.py`)
- Turn orchestrator → OpenRouter client: requests completions (evidence: `agent.py`)
- Profile clarification → OpenRouter client: uses chat requests (evidence: `llm_client.py`)
- Preference extraction → OpenRouter client: uses chat requests (evidence: `llm_client.py`)
- OpenRouter client → OpenRouter API: sends requests (evidence: `llm_client.py`)
- Turn orchestrator → Tool specifications: provides tool specs (evidence: `agent.py`)
- Turn orchestrator → Tool dispatch and state: executes tool calls (evidence: `agent.py`)
- Tool dispatch and state → Tool specifications: dispatches allow-listed (evidence: `tool_executor.py`)
- Tool specifications → Repository search: dispatches search (evidence: `tools.py`)
- Tool specifications → Repository inspection: dispatches inspection (evidence: `tools.py`)
- Tool specifications → Issue discovery: dispatches issue lookup (evidence: `tools.py`)
- Repository search → GitHub REST API: queries repositories (evidence: `github_client.py`)
- Repository inspection → GitHub REST API: fetches metadata (evidence: `github_client.py`)
- Issue discovery → GitHub REST API: fetches open issues (evidence: `github_client.py`)
- Repository search → API response cache: uses response cache (evidence: `github_client.py`)
- Repository inspection → API response cache: uses response cache (evidence: `github_client.py`)
- Issue discovery → API response cache: uses response cache (evidence: `github_client.py`)
- Turn orchestrator → Candidate assembly: builds candidates (evidence: `agent.py`)
- Turn orchestrator → Deterministic ranking: ranks candidates (evidence: `agent.py`)
- Turn orchestrator → Recommendations: prints results (evidence: `agent.py`)
- Turn orchestrator → OpenRouter client: generates summary (evidence: `agent.py`)
- OpenRouter client → Runtime configuration: reads API settings (evidence: `llm_client.py`)
- Repository search → Runtime configuration: reads API settings (evidence: `github_client.py`)
