# stuyvesant-cs/ghtools architecture

> Architecture diagram of the GitHub repository stuyvesant-cs/ghtools, 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/stuyvesant-cs/ghtools
- Repository: https://github.com/stuyvesant-cs/ghtools

## Overview

ghtools is a command-line toolkit for replacing selected GitHub Classroom workflows: creating student assignment repositories, cloning those repositories locally, and managing organization users and team membership/access. The installed CLI and legacy scripts are parallel entry points to overlapping operations. Assignment creation and repository cloning are distinct workflows; organization and team administration are separate capability branches. Source excerpts establish several internal calls, while dispatch from the CLIs to command handlers is not shown in full, so those links are marked unverified.

Main entry points: [`ghtool.py`](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool.py) (Legacy CLI), [`ghtool_project/src/ghtool/cli.py`](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/cli.py) (Installed CLI), [`manage_repos.py`](https://github.com/stuyvesant-cs/ghtools/blob/master/manage_repos.py) (Repository cloning), [`ghtool_project/src/ghtool/manage_repos.py`](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_repos.py) (Repository cloning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry points"]
  node_legacy_cli["Legacy CLI<br/>[ghtool.py]"]
  node_package_cli["Installed CLI<br/>[cli.py]"]
end

subgraph group_assignment["Assignment workflows"]
  node_legacy_assignment["Assignment creation"]
  node_package_assignment["Assignment creation"]
end

subgraph group_admin["Organization and teams"]
  node_legacy_org["Organization users<br/>[manage_org.py]"]
  node_package_org["Organization users<br/>[manage_org.py]"]
  node_legacy_teams["Team administration<br/>[manage_teams.py]"]
  node_package_teams["Team administration<br/>[manage_teams.py]"]
end

subgraph group_repo["Repository cloning"]
  node_legacy_repo["Repository cloning<br/>[manage_repos.py]"]
  node_package_repo["Repository cloning<br/>[manage_repos.py]"]
end

node_operator(("Operator"))
node_github["GitHub API"]
node_local_git["Local Git"]

node_operator -->|"runs"| node_legacy_cli
node_operator -->|"runs"| node_package_cli
node_legacy_cli -.->|"dispatches"| node_legacy_assignment
node_legacy_cli -.->|"dispatches"| node_legacy_org
node_legacy_cli -.->|"dispatches"| node_legacy_teams
node_legacy_cli -.->|"dispatches"| node_legacy_repo
node_package_cli -.->|"dispatches"| node_package_assignment
node_package_cli -.->|"dispatches"| node_package_org
node_package_cli -.->|"dispatches"| node_package_teams
node_package_cli -.->|"dispatches"| node_package_repo
node_legacy_assignment -->|"creates and invites"| node_github
node_package_assignment -->|"creates and invites"| node_github
node_legacy_org -->|"invites users"| node_github
node_package_org -->|"invites users"| node_github
node_legacy_teams -->|"manages teams"| node_github
node_package_teams -->|"manages teams"| node_github
node_legacy_repo -->|"lists repositories"| node_github
node_package_repo -->|"lists repositories"| node_github
node_legacy_repo -->|"clones repositories"| node_local_git
node_package_repo -->|"clones repositories"| node_local_git

click node_legacy_cli "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool.py"
click node_package_cli "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/cli.py"
click node_legacy_assignment "https://github.com/stuyvesant-cs/ghtools/blob/master/create_assignment.py"
click node_package_assignment "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/create_assignment.py"
click node_legacy_org "https://github.com/stuyvesant-cs/ghtools/blob/master/manage_org.py"
click node_package_org "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_org.py"
click node_legacy_teams "https://github.com/stuyvesant-cs/ghtools/blob/master/manage_teams.py"
click node_package_teams "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_teams.py"
click node_legacy_repo "https://github.com/stuyvesant-cs/ghtools/blob/master/manage_repos.py"
click node_package_repo "https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_repos.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_legacy_cli,node_package_cli toneBlue
class node_legacy_assignment,node_package_assignment toneAmber
class node_legacy_org,node_package_org,node_legacy_teams,node_package_teams,node_github toneMint
class node_legacy_repo,node_package_repo toneRose
class node_operator,node_local_git toneIndigo
```

## Components

### CLI entry points

- [Legacy CLI](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool.py): `ghtool.py`
- [Installed CLI](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/cli.py): `ghtool_project/src/ghtool/cli.py`

### Assignment workflows

- [Assignment creation](https://github.com/stuyvesant-cs/ghtools/blob/master/create_assignment.py): `create_assignment.py`
- [Assignment creation](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/create_assignment.py): `ghtool_project/src/ghtool/create_assignment.py`

### Organization and teams

- [Organization users](https://github.com/stuyvesant-cs/ghtools/blob/master/manage_org.py): `manage_org.py`
- [Organization users](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_org.py): `ghtool_project/src/ghtool/manage_org.py`
- [Team administration](https://github.com/stuyvesant-cs/ghtools/blob/master/manage_teams.py): `manage_teams.py`
- [Team administration](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_teams.py): `ghtool_project/src/ghtool/manage_teams.py`

### Repository cloning

- [Repository cloning](https://github.com/stuyvesant-cs/ghtools/blob/master/manage_repos.py): `manage_repos.py`
- [Repository cloning](https://github.com/stuyvesant-cs/ghtools/blob/master/ghtool_project/src/ghtool/manage_repos.py): `ghtool_project/src/ghtool/manage_repos.py`

### Other components

- **Operator**
- **GitHub API**
- **Local Git**

## Connections

- Operator → Legacy CLI: runs (evidence: `README.md`)
- Operator → Installed CLI: runs (evidence: `README.md`)
- Legacy CLI → Assignment creation: dispatches (evidence: `ghtool.py`)
- Legacy CLI → Organization users: dispatches (evidence: `ghtool.py`)
- Legacy CLI → Team administration: dispatches (evidence: `ghtool.py`)
- Legacy CLI → Repository cloning: dispatches (evidence: `ghtool.py`)
- Installed CLI → Assignment creation: dispatches (evidence: `ghtool_project/src/ghtool/cli.py`)
- Installed CLI → Organization users: dispatches (evidence: `ghtool_project/src/ghtool/cli.py`)
- Installed CLI → Team administration: dispatches (evidence: `ghtool_project/src/ghtool/cli.py`)
- Installed CLI → Repository cloning: dispatches (evidence: `ghtool_project/src/ghtool/cli.py`)
- Assignment creation → GitHub API: creates and invites (evidence: `create_assignment.py`)
- Assignment creation → GitHub API: creates and invites (evidence: `ghtool_project/src/ghtool/create_assignment.py`)
- Organization users → GitHub API: invites users (evidence: `manage_org.py`)
- Organization users → GitHub API: invites users (evidence: `ghtool_project/src/ghtool/manage_org.py`)
- Team administration → GitHub API: manages teams (evidence: `manage_teams.py`)
- Team administration → GitHub API: manages teams (evidence: `ghtool_project/src/ghtool/manage_teams.py`)
- Repository cloning → GitHub API: lists repositories (evidence: `manage_repos.py`)
- Repository cloning → GitHub API: lists repositories (evidence: `ghtool_project/src/ghtool/manage_repos.py`)
- Repository cloning → Local Git: clones repositories (evidence: `manage_repos.py`)
- Repository cloning → Local Git: clones repositories (evidence: `ghtool_project/src/ghtool/manage_repos.py`)
