# ashfak99/contribpilot architecture

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

- Interactive diagram: https://gitdiagram.com/ashfak99/contribpilot
- Repository: https://github.com/ashfak99/contribpilot

## Overview

ContribPilot helps contributors find suitable GitHub issues, investigate an issue with repository-grounded AI context, and request progressive hints. The main flow runs from the React matchmaker through the API client and FastAPI issue routes into the AI service; issue discovery and breakdown use GitHub data, while ranking, breakdown, and hints use Groq. BYOK credentials and match/hint progress are handled in browser storage. The graph preserves the documented capabilities; several backend internals and auxiliary pages were not sampled, so their runtime connections are omitted.

Main entry points: [`backend/app/services/ai_service.py`](https://github.com/ashfak99/contribpilot/blob/main/backend/app/services/ai_service.py) (AI orchestration), [`frontend/src/services/api.js`](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/services/api.js) (API client), [`backend/app/ai/llm_client.py`](https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/llm_client.py) (Groq client), [`backend/app/main.py`](https://github.com/ashfak99/contribpilot/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Contributor app"]
  node_app["App routing<br/>[App.jsx]"]
  node_matchmaker["Issue matchmaker<br/>[Matchmaker.jsx]"]
  node_issue_details["Issue details<br/>[IssueDetails.jsx]"]
  node_hint_card["Progressive hints<br/>[HintCard.jsx]"]
  node_configuration["Key configuration<br/>[Config.jsx]"]
  node_browser_state["Browser state<br/>[sessions.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_issue_routes["Issue routes<br/>[issues.py]"]
  node_hint_routes["Hint route<br/>[contributions.py]"]
  node_ai_service["AI orchestration<br/>[ai_service.py]"]
  node_request_models["Request models<br/>[request.py]"]
  node_ai_models["AI response models<br/>[ai.py]"]
end

subgraph group_github["Repository context"]
  node_github_service["GitHub data access<br/>[github_service.py]"]
end

subgraph group_ai["AI guidance"]
  node_ranking["Issue ranking<br/>[ranking.py]"]
  node_breakdown["Issue breakdown<br/>[breakdown.py]"]
  node_hints["Hint generation<br/>[hints.py]"]
  node_llm_client["Groq client<br/>[llm_client.py]"]
end

node_contributor(("Contributor"))
node_github["GitHub REST API"]
node_groq["Groq API"]

node_contributor -.->|"sets profile"| node_matchmaker
node_contributor -.->|"supplies keys"| node_configuration
node_app -->|"routes to"| node_matchmaker
node_app -->|"routes to"| node_issue_details
node_matchmaker -->|"requests matches"| node_api_client
node_issue_details -->|"requests breakdown"| node_api_client
node_hint_card -->|"requests hint"| node_api_client
node_configuration -->|"stores credentials"| node_browser_state
node_api_client -->|"reads credentials"| node_browser_state
node_browser_state -->|"adds request headers"| node_api_client
node_api_client -->|"posts requests"| node_fastapi
node_fastapi -->|"registers routes"| node_issue_routes
node_fastapi -->|"registers routes"| node_hint_routes
node_issue_routes -->|"delegates"| node_ai_service
node_hint_routes -->|"delegates"| node_ai_service
node_issue_routes -->|"uses request types"| node_request_models
node_ai_service -->|"fetches issue context"| node_github_service
node_github_service -->|"requests repository data"| node_github
node_ai_service -->|"ranks issues"| node_ranking
node_ai_service -->|"builds breakdown"| node_breakdown
node_ai_service -->|"generates hints"| node_hints
node_ranking -->|"requests completion"| node_llm_client
node_breakdown -->|"requests completion"| node_llm_client
node_hints -->|"requests completion"| node_llm_client
node_llm_client -->|"calls completions"| node_groq
node_ai_service -->|"returns typed results"| node_ai_models
node_hint_routes -->|"declares response"| node_ai_models

click node_app "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/App.jsx"
click node_matchmaker "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/Matchmaker.jsx"
click node_issue_details "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/IssueDetails.jsx"
click node_hint_card "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/components/HintCard.jsx"
click node_configuration "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/Config.jsx"
click node_browser_state "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/utils/sessions.js"
click node_api_client "https://github.com/ashfak99/contribpilot/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/ashfak99/contribpilot/blob/main/backend/app/main.py"
click node_issue_routes "https://github.com/ashfak99/contribpilot/blob/main/backend/app/api/issues.py"
click node_hint_routes "https://github.com/ashfak99/contribpilot/blob/main/backend/app/api/contributions.py"
click node_ai_service "https://github.com/ashfak99/contribpilot/blob/main/backend/app/services/ai_service.py"
click node_request_models "https://github.com/ashfak99/contribpilot/blob/main/backend/app/schemas/request.py"
click node_ai_models "https://github.com/ashfak99/contribpilot/blob/main/backend/app/schemas/ai.py"
click node_github_service "https://github.com/ashfak99/contribpilot/blob/main/backend/app/services/github_service.py"
click node_ranking "https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/ranking.py"
click node_breakdown "https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/breakdown.py"
click node_hints "https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/hints.py"
click node_llm_client "https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/llm_client.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_app,node_matchmaker,node_issue_details,node_hint_card,node_configuration,node_browser_state,node_api_client toneBlue
class node_fastapi,node_issue_routes,node_hint_routes,node_ai_service,node_request_models,node_ai_models toneAmber
class node_github_service,node_github,node_groq toneMint
class node_ranking,node_breakdown,node_hints,node_llm_client toneRose
class node_contributor toneIndigo
```

## Components

### Contributor app

- [App routing](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Issue matchmaker](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/Matchmaker.jsx): `frontend/src/pages/Matchmaker.jsx`
- [Issue details](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/IssueDetails.jsx): `frontend/src/pages/IssueDetails.jsx`
- [Progressive hints](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/components/HintCard.jsx): `frontend/src/components/HintCard.jsx`
- [Key configuration](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/pages/Config.jsx): `frontend/src/pages/Config.jsx`
- [Browser state](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/utils/sessions.js): `frontend/src/utils/sessions.js`
- [API client](https://github.com/ashfak99/contribpilot/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and orchestration

- [FastAPI app](https://github.com/ashfak99/contribpilot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Issue routes](https://github.com/ashfak99/contribpilot/blob/main/backend/app/api/issues.py): `backend/app/api/issues.py`
- [Hint route](https://github.com/ashfak99/contribpilot/blob/main/backend/app/api/contributions.py): `backend/app/api/contributions.py`
- [AI orchestration](https://github.com/ashfak99/contribpilot/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Request models](https://github.com/ashfak99/contribpilot/blob/main/backend/app/schemas/request.py): `backend/app/schemas/request.py`
- [AI response models](https://github.com/ashfak99/contribpilot/blob/main/backend/app/schemas/ai.py): `backend/app/schemas/ai.py`

### Repository context

- [GitHub data access](https://github.com/ashfak99/contribpilot/blob/main/backend/app/services/github_service.py): `backend/app/services/github_service.py`

### AI guidance

- [Issue ranking](https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/ranking.py): `backend/app/ai/ranking.py`
- [Issue breakdown](https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/breakdown.py): `backend/app/ai/breakdown.py`
- [Hint generation](https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/hints.py): `backend/app/ai/hints.py`
- [Groq client](https://github.com/ashfak99/contribpilot/blob/main/backend/app/ai/llm_client.py): `backend/app/ai/llm_client.py`

### Other components

- **Contributor**
- **GitHub REST API**
- **Groq API**

## Connections

- Contributor → Issue matchmaker: sets profile
- Contributor → Key configuration: supplies keys (evidence: `README.md`)
- App routing → Issue matchmaker: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Issue details: routes to (evidence: `frontend/src/App.jsx`)
- Issue matchmaker → API client: requests matches (evidence: `frontend/src/pages/Matchmaker.jsx`)
- Issue details → API client: requests breakdown (evidence: `frontend/src/pages/IssueDetails.jsx`)
- Progressive hints → API client: requests hint (evidence: `frontend/src/components/HintCard.jsx`)
- Key configuration → Browser state: stores credentials (evidence: `frontend/src/pages/Config.jsx`)
- API client → Browser state: reads credentials (evidence: `frontend/src/services/api.js`)
- Browser state → API client: adds request headers (evidence: `frontend/src/services/api.js`)
- API client → FastAPI app: posts requests (evidence: `frontend/src/services/api.js`)
- FastAPI app → Issue routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Hint route: registers routes (evidence: `backend/app/main.py`)
- Issue routes → AI orchestration: delegates (evidence: `backend/app/api/issues.py`)
- Hint route → AI orchestration: delegates (evidence: `backend/app/api/contributions.py`)
- Issue routes → Request models: uses request types (evidence: `backend/app/api/issues.py`)
- AI orchestration → GitHub data access: fetches issue context (evidence: `backend/app/services/ai_service.py`)
- GitHub data access → GitHub REST API: requests repository data (evidence: `README.md`)
- AI orchestration → Issue ranking: ranks issues (evidence: `backend/app/services/ai_service.py`)
- AI orchestration → Issue breakdown: builds breakdown (evidence: `backend/app/services/ai_service.py`)
- AI orchestration → Hint generation: generates hints (evidence: `backend/app/services/ai_service.py`)
- Issue ranking → Groq client: requests completion (evidence: `backend/app/ai/ranking.py`)
- Issue breakdown → Groq client: requests completion (evidence: `backend/app/ai/breakdown.py`)
- Hint generation → Groq client: requests completion (evidence: `backend/app/ai/hints.py`)
- Groq client → Groq API: calls completions (evidence: `backend/app/ai/llm_client.py`)
- AI orchestration → AI response models: returns typed results (evidence: `backend/app/services/ai_service.py`)
- Hint route → AI response models: declares response (evidence: `backend/app/api/contributions.py`)
