# github/forgoodfirstissue architecture

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

- Interactive diagram: https://gitdiagram.com/github/forgoodfirstissue
- Repository: https://github.com/github/forgoodfirstissue

## Overview

For Good First Issue is a Next.js site that helps contributors discover social-impact and civic-tech repositories and their tagged issues, with a separate teams directory. The main path is curated repository data, loaded into app state, searched and filtered, then shown with expandable issue lists. The README documents a GitHub API generation step; the organization-list implementation is represented from the tree and indexed references, but its data source is not established by the excerpts. Edges are limited to documented or indexed relationships.

Main entry points: [`components/RepositoryList.tsx`](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryList.tsx) (Repository search and filters), [`components/RepositoryItem.tsx`](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryItem.tsx) (Repository card), [`components/OrganizationList.tsx`](https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationList.tsx) (Organization directory), [`generate.ts`](https://github.com/github/forgoodfirstissue/blob/main/generate.ts) (Issue data generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_curated["Curated projects<br/>[happycommits.json]"]
  node_generator["Issue data generator<br/>[generate.ts]"]
  node_generated["Generated data<br/>[generated.json]"]
  node_org_generator["Organization generator"]
end

subgraph group_app["Application state"]
  node_app_state["App data context<br/>[AppDataContext.tsx]"]
  node_data_hook["App data hook<br/>[useAppData.tsx]"]
end

subgraph group_discovery["Project discovery"]
  node_home["Individual discovery page<br/>[index.tsx]"]
  node_repo_list["Repository search and filters<br/>[RepositoryList.tsx]"]
  node_language_filter["Language filter<br/>[LanguageFilter.tsx]"]
  node_sdg_filter["SDG filter<br/>[SDGFilter.tsx]"]
  node_repo_item["Repository card<br/>[RepositoryItem.tsx]"]
  node_repo_top["Repository heading"]
  node_repo_meta["Repository metadata"]
  node_issue_list["Issue list<br/>[IssueList.tsx]"]
  node_issue_item["Issue entry<br/>[IssueItem.tsx]"]
end

subgraph group_teams["Teams directory"]
  node_teams_page["Teams page<br/>[teams.tsx]"]
  node_org_list["Organization directory"]
  node_org_item["Organization card"]
  node_org_filter["Organization filters<br/>[GeneralFilter.tsx]"]
  node_org_language["Language filter<br/>[LanguageFilter.tsx]"]
  node_org_meta["Organization metadata"]
end

node_visitor(("Contributor"))
node_maintainer(("Project maintainer"))
node_github{{"GitHub API"}}

node_maintainer -->|"curates"| node_curated
node_curated -->|"lists repositories"| node_generator
node_generator -->|"fetches issues"| node_github
node_generator -->|"generates data"| node_generated
node_generated -->|"loads"| node_app_state
node_app_state -->|"provides context"| node_data_hook
node_visitor -.->|"browses"| node_home
node_home -->|"reads repositories"| node_data_hook
node_home -->|"renders"| node_repo_list
node_repo_list -->|"renders"| node_language_filter
node_repo_list -->|"renders"| node_sdg_filter
node_repo_list -->|"renders"| node_repo_item
node_repo_item -->|"renders"| node_repo_top
node_repo_item -->|"renders"| node_repo_meta
node_repo_item -->|"renders"| node_issue_list
node_issue_list -->|"renders"| node_issue_item
node_visitor -.->|"browses"| node_teams_page
node_teams_page -->|"renders"| node_org_list
node_org_list -->|"renders"| node_org_filter
node_org_list -->|"renders"| node_org_language
node_org_list -->|"renders"| node_org_item
node_org_item -->|"renders"| node_org_meta

click node_curated "https://github.com/github/forgoodfirstissue/blob/main/happycommits.json"
click node_generator "https://github.com/github/forgoodfirstissue/blob/main/generate.ts"
click node_generated "https://github.com/github/forgoodfirstissue/blob/main/generated.json"
click node_org_generator "https://github.com/github/forgoodfirstissue/blob/main/generate-organizations.ts"
click node_app_state "https://github.com/github/forgoodfirstissue/blob/main/context/AppDataContext.tsx"
click node_data_hook "https://github.com/github/forgoodfirstissue/blob/main/hooks/useAppData.tsx"
click node_home "https://github.com/github/forgoodfirstissue/blob/main/pages/index.tsx"
click node_repo_list "https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryList.tsx"
click node_language_filter "https://github.com/github/forgoodfirstissue/blob/main/components/LanguageFilter.tsx"
click node_sdg_filter "https://github.com/github/forgoodfirstissue/blob/main/components/SDGFilter.tsx"
click node_repo_item "https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryItem.tsx"
click node_repo_top "https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryItemTopBar.tsx"
click node_repo_meta "https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryMetadata.tsx"
click node_issue_list "https://github.com/github/forgoodfirstissue/blob/main/components/IssueList.tsx"
click node_issue_item "https://github.com/github/forgoodfirstissue/blob/main/components/IssueItem.tsx"
click node_teams_page "https://github.com/github/forgoodfirstissue/blob/main/pages/teams.tsx"
click node_org_list "https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationList.tsx"
click node_org_item "https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationItem.tsx"
click node_org_filter "https://github.com/github/forgoodfirstissue/blob/main/components/GeneralFilter.tsx"
click node_org_language "https://github.com/github/forgoodfirstissue/blob/main/components/LanguageFilter.tsx"
click node_org_meta "https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationMetadata.tsx"

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_curated,node_generator,node_generated,node_org_generator toneBlue
class node_app_state,node_data_hook toneAmber
class node_home,node_repo_list,node_language_filter,node_sdg_filter,node_repo_item,node_repo_top,node_repo_meta,node_issue_list,node_issue_item,node_github toneMint
class node_teams_page,node_org_list,node_org_item,node_org_filter,node_org_language,node_org_meta toneRose
class node_visitor,node_maintainer toneIndigo
```

## Components

### Data preparation

- [Curated projects](https://github.com/github/forgoodfirstissue/blob/main/happycommits.json): `happycommits.json`
- [Issue data generator](https://github.com/github/forgoodfirstissue/blob/main/generate.ts): `generate.ts`
- [Generated data](https://github.com/github/forgoodfirstissue/blob/main/generated.json): `generated.json`
- [Organization generator](https://github.com/github/forgoodfirstissue/blob/main/generate-organizations.ts): `generate-organizations.ts`

### Application state

- [App data context](https://github.com/github/forgoodfirstissue/blob/main/context/AppDataContext.tsx): `context/AppDataContext.tsx`
- [App data hook](https://github.com/github/forgoodfirstissue/blob/main/hooks/useAppData.tsx): `hooks/useAppData.tsx`

### Project discovery

- [Individual discovery page](https://github.com/github/forgoodfirstissue/blob/main/pages/index.tsx): `pages/index.tsx`
- [Repository search and filters](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryList.tsx): `components/RepositoryList.tsx`
- [Language filter](https://github.com/github/forgoodfirstissue/blob/main/components/LanguageFilter.tsx): `components/LanguageFilter.tsx`
- [SDG filter](https://github.com/github/forgoodfirstissue/blob/main/components/SDGFilter.tsx): `components/SDGFilter.tsx`
- [Repository card](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryItem.tsx): `components/RepositoryItem.tsx`
- [Repository heading](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryItemTopBar.tsx): `components/RepositoryItemTopBar.tsx`
- [Repository metadata](https://github.com/github/forgoodfirstissue/blob/main/components/RepositoryMetadata.tsx): `components/RepositoryMetadata.tsx`
- [Issue list](https://github.com/github/forgoodfirstissue/blob/main/components/IssueList.tsx): `components/IssueList.tsx`
- [Issue entry](https://github.com/github/forgoodfirstissue/blob/main/components/IssueItem.tsx): `components/IssueItem.tsx`

### Teams directory

- [Teams page](https://github.com/github/forgoodfirstissue/blob/main/pages/teams.tsx): `pages/teams.tsx`
- [Organization directory](https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationList.tsx): `components/OrganizationList.tsx`
- [Organization card](https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationItem.tsx): `components/OrganizationItem.tsx`
- [Organization filters](https://github.com/github/forgoodfirstissue/blob/main/components/GeneralFilter.tsx): `components/GeneralFilter.tsx`
- [Language filter](https://github.com/github/forgoodfirstissue/blob/main/components/LanguageFilter.tsx): `components/LanguageFilter.tsx`
- [Organization metadata](https://github.com/github/forgoodfirstissue/blob/main/components/OrganizationMetadata.tsx): `components/OrganizationMetadata.tsx`

### Other components

- **Contributor**
- **Project maintainer**
- **GitHub API**

## Connections

- Project maintainer → Curated projects: curates (evidence: `README.md`)
- Curated projects → Issue data generator: lists repositories (evidence: `README.md`)
- Issue data generator → GitHub API: fetches issues (evidence: `README.md`)
- Issue data generator → Generated data: generates data (evidence: `README.md`)
- Generated data → App data context: loads (evidence: `context/AppDataContext.tsx`)
- App data context → App data hook: provides context (evidence: `hooks/useAppData.tsx`)
- Contributor → Individual discovery page: browses
- Individual discovery page → App data hook: reads repositories (evidence: `pages/index.tsx`)
- Individual discovery page → Repository search and filters: renders (evidence: `pages/index.tsx`)
- Repository search and filters → Language filter: renders (evidence: `components/RepositoryList.tsx`)
- Repository search and filters → SDG filter: renders (evidence: `components/RepositoryList.tsx`)
- Repository search and filters → Repository card: renders (evidence: `components/RepositoryList.tsx`)
- Repository card → Repository heading: renders (evidence: `components/RepositoryItem.tsx`)
- Repository card → Repository metadata: renders (evidence: `components/RepositoryItem.tsx`)
- Repository card → Issue list: renders (evidence: `components/RepositoryItem.tsx`)
- Issue list → Issue entry: renders (evidence: `components/IssueList.tsx`)
- Contributor → Teams page: browses
- Teams page → Organization directory: renders (evidence: `pages/teams.tsx`)
- Organization directory → Organization filters: renders (evidence: `components/OrganizationList.tsx`)
- Organization directory → Language filter: renders (evidence: `components/OrganizationList.tsx`)
- Organization directory → Organization card: renders (evidence: `components/OrganizationList.tsx`)
- Organization card → Organization metadata: renders (evidence: `components/OrganizationItem.tsx`)
