# gigasandwich/giga-roadmap architecture

> Architecture diagram of the GitHub repository gigasandwich/giga-roadmap, 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/gigasandwich/giga-roadmap
- Repository: https://github.com/gigasandwich/giga-roadmap

## Overview

This is a student-facing academic-pathway roadmap: users choose a country, explore degree-to-career graph paths, and can edit and submit graph contributions. The graph includes country data loading, interactive exploration, graph editing and change summaries, authenticated contribution submission, and GitHub PR plus Google Sheets tracking. The README also documents a public, contributor-modifiable dataset and filtered detail views; the tree shows graph exploration and editing, though filter implementation details were not sampled. Edges are limited to calls or data flow shown in excerpts, SOURCE INDEX references, or README claims; unsampled subsystems are represented only where their role and path are supported.

Main entry points: [`web/app/country/[country]/contribute/ContributionGraph.tsx`](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/contribute/ContributionGraph.tsx) (Graph editor), [`web/app/api/contributions/route.ts`](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/api/contributions/route.ts) (Contribution API), [`web/lib/github/contribution.ts`](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/github/contribution.ts) (PR creation), [`web/lib/graph/data.ts`](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/data.ts) (Country and graph data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Roadmap experience"]
  node_country_page["Country roadmap page<br/>[page.tsx]"]
  node_country_data[("Country and graph data<br/>[data.ts]")]
  node_exploration["Graph exploration view"]
  node_country_list[("Country registry<br/>[countries.ts]")]
end

subgraph group_graph["Graph capabilities"]
  node_explore_view["Exploration controls"]
  node_explore_sidebar["Exploration sidebar"]
  node_graph_nodes["Graph node model<br/>[nodes.ts]"]
  node_graph_diff["Change summaries<br/>[diff.ts]"]
end

subgraph group_contribution["Contribution workflow"]
  node_contribute_page["Contribution page<br/>[page.tsx]"]
  node_contribute_graph["Graph editor"]
  node_edit_hooks["Editing state and persistence"]
  node_review_dialog["Change review"]
  node_contribution_api["Contribution API<br/>[route.ts]"]
end

subgraph group_integrations["External integrations"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_github_contribution["PR creation<br/>[contribution.ts]"]
  node_github_service["GitHub"]
  node_sheet_append["Contribution tracking<br/>[append.ts]"]
  node_sheet_read["Contributor PR lookup<br/>[read.ts]"]
  node_google_sheets[("Google Sheets")]
end

node_student(("Student / contributor"))

node_student -->|"chooses country"| node_country_page
node_country_page -->|"loads graph"| node_country_data
node_country_data -->|"validates country"| node_country_list
node_country_page -->|"renders"| node_exploration
node_exploration -->|"uses controls"| node_explore_view
node_exploration -->|"renders"| node_explore_sidebar
node_explore_view -.-> node_graph_nodes
node_student -->|"opens editor"| node_contribute_page
node_contribute_page -->|"renders"| node_contribute_graph
node_contribute_graph -.-> node_edit_hooks
node_contribute_graph -.-> node_review_dialog
node_contribute_graph -.-> node_graph_diff
node_contribute_graph -.->|"submits changes"| node_contribution_api
node_contribution_api -->|"checks session"| node_auth
node_contribution_api -->|"creates PR"| node_github_contribution
node_github_contribution -->|"writes branch and PR"| node_github_service
node_contribution_api -->|"logs submission"| node_sheet_append
node_sheet_append -->|"appends row"| node_google_sheets
node_contribution_api -->|"looks up PRs"| node_sheet_read
node_sheet_read -.-> node_google_sheets
node_github_contribution -->|"resolves country name"| node_country_list
node_github_contribution -->|"resolves data folder"| node_country_data
node_country_data -->|"sanitizes nodes"| node_graph_nodes
node_graph_diff -->|"formats node names"| node_graph_nodes

click node_country_page "https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/page.tsx"
click node_country_data "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/data.ts"
click node_exploration "https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/ExplorationGraph.tsx"
click node_explore_view "https://github.com/gigasandwich/giga-roadmap/blob/main/web/hooks/graph/exploration/useExplorationView.ts"
click node_explore_sidebar "https://github.com/gigasandwich/giga-roadmap/blob/main/web/components/graph/sidebar/ExplorationSidebar.tsx"
click node_graph_nodes "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/nodes.ts"
click node_graph_diff "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/diff.ts"
click node_country_list "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/countries.ts"
click node_contribute_page "https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/contribute/page.tsx"
click node_contribute_graph "https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/contribute/ContributionGraph.tsx"
click node_edit_hooks "https://github.com/gigasandwich/giga-roadmap/tree/main/web/hooks/graph/contribution"
click node_review_dialog "https://github.com/gigasandwich/giga-roadmap/blob/main/web/components/graph/ReviewChangeDialog.tsx"
click node_contribution_api "https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/api/contributions/route.ts"
click node_auth "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/auth.ts"
click node_github_contribution "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/github/contribution.ts"
click node_sheet_append "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/google/sheet/append.ts"
click node_sheet_read "https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/google/sheet/read.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_country_page,node_country_data,node_exploration,node_country_list toneBlue
class node_explore_view,node_explore_sidebar,node_graph_nodes,node_graph_diff toneAmber
class node_contribute_page,node_contribute_graph,node_edit_hooks,node_review_dialog,node_contribution_api toneMint
class node_auth,node_github_contribution,node_github_service,node_sheet_append,node_sheet_read,node_google_sheets toneRose
class node_student toneIndigo
```

## Components

### Roadmap experience

- [Country roadmap page](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/page.tsx): `web/app/country/[country]/page.tsx`
- [Country and graph data](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/data.ts): `web/lib/graph/data.ts`
- [Graph exploration view](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/ExplorationGraph.tsx): `web/app/country/[country]/ExplorationGraph.tsx`
- [Country registry](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/countries.ts): `web/lib/countries.ts`

### Graph capabilities

- [Exploration controls](https://github.com/gigasandwich/giga-roadmap/blob/main/web/hooks/graph/exploration/useExplorationView.ts): `web/hooks/graph/exploration/useExplorationView.ts`
- [Exploration sidebar](https://github.com/gigasandwich/giga-roadmap/blob/main/web/components/graph/sidebar/ExplorationSidebar.tsx): `web/components/graph/sidebar/ExplorationSidebar.tsx`
- [Graph node model](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/nodes.ts): `web/lib/graph/nodes.ts`
- [Change summaries](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/graph/diff.ts): `web/lib/graph/diff.ts`

### Contribution workflow

- [Contribution page](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/contribute/page.tsx): `web/app/country/[country]/contribute/page.tsx`
- [Graph editor](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/country/%5Bcountry%5D/contribute/ContributionGraph.tsx): `web/app/country/[country]/contribute/ContributionGraph.tsx`
- [Editing state and persistence](https://github.com/gigasandwich/giga-roadmap/tree/main/web/hooks/graph/contribution): `web/hooks/graph/contribution`
- [Change review](https://github.com/gigasandwich/giga-roadmap/blob/main/web/components/graph/ReviewChangeDialog.tsx): `web/components/graph/ReviewChangeDialog.tsx`
- [Contribution API](https://github.com/gigasandwich/giga-roadmap/blob/main/web/app/api/contributions/route.ts): `web/app/api/contributions/route.ts`

### External integrations

- [Authentication](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/auth.ts): `web/lib/auth.ts`
- [PR creation](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/github/contribution.ts): `web/lib/github/contribution.ts`
- **GitHub**
- [Contribution tracking](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/google/sheet/append.ts): `web/lib/google/sheet/append.ts`
- [Contributor PR lookup](https://github.com/gigasandwich/giga-roadmap/blob/main/web/lib/google/sheet/read.ts): `web/lib/google/sheet/read.ts`
- **Google Sheets**

### Other components

- **Student / contributor**

## Connections

- Student / contributor → Country roadmap page: chooses country
- Country roadmap page → Country and graph data: loads graph (evidence: `web/app/country/[country]/page.tsx`)
- Country and graph data → Country registry: validates country (evidence: `web/lib/graph/data.ts`)
- Country roadmap page → Graph exploration view: renders (evidence: `web/app/country/[country]/page.tsx`)
- Graph exploration view → Exploration controls: uses controls (evidence: `web/app/country/[country]/ExplorationGraph.tsx`)
- Graph exploration view → Exploration sidebar: renders (evidence: `web/app/country/[country]/ExplorationGraph.tsx`)
- Exploration controls → Graph node model
- Student / contributor → Contribution page: opens editor
- Contribution page → Graph editor: renders (evidence: `web/app/country/[country]/contribute/page.tsx`)
- Graph editor → Editing state and persistence
- Graph editor → Change review
- Graph editor → Change summaries
- Graph editor → Contribution API: submits changes
- Contribution API → Authentication: checks session (evidence: `web/app/api/contributions/route.ts`)
- Contribution API → PR creation: creates PR (evidence: `web/app/api/contributions/route.ts`)
- PR creation → GitHub: writes branch and PR (evidence: `web/lib/github/contribution.ts`)
- Contribution API → Contribution tracking: logs submission (evidence: `web/app/api/contributions/route.ts`)
- Contribution tracking → Google Sheets: appends row (evidence: `web/lib/google/sheet/append.ts`)
- Contribution API → Contributor PR lookup: looks up PRs (evidence: `web/app/api/contributions/route.ts`)
- Contributor PR lookup → Google Sheets
- PR creation → Country registry: resolves country name (evidence: `web/lib/github/contribution.ts`)
- PR creation → Country and graph data: resolves data folder (evidence: `web/lib/github/contribution.ts`)
- Country and graph data → Graph node model: sanitizes nodes (evidence: `web/lib/graph/data.ts`)
- Change summaries → Graph node model: formats node names (evidence: `web/lib/graph/diff.ts`)