# joshuakosakowsky/highered_automation architecture

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

## Overview

HigherEd Automation is a desktop and command-line toolkit for Mines Bursar processes. Staff select authorized GUI workflows or run existing command-line workflows; workflow runners collect inputs, invoke data-processing pipelines, and produce review or Banner-ready files. The README also documents Insights connections, access administration, browser sessions, a cashier report watcher, and several workflows beyond those sampled. GUI wiring and the three sampled processing pipelines are visible; some adapter and integration internals are not, so their links are omitted or marked unverified.

Main entry points: [`app/gui/main.py`](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/main.py) (Automation GUI), [`app/gui/workflow_registry.py`](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/workflow_registry.py) (Workflow registry), [`app/gui/services`](https://github.com/joshuakosakowsky/highered_automation/tree/main/app/gui/services) (GUI workflow adapters), [`data_processing/population_testing/pipeline.py`](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/population_testing/pipeline.py) (Population testing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_gui["Automation GUI<br/>[main.py]"]
  node_models["Workflow contracts<br/>[models.py]"]
  node_registry["Workflow registry"]
  node_access["Access management"]
  node_connections["Insights connections<br/>[connections.py]"]
  node_gui_access["GUI workflow adapters"]
end

subgraph group_workflow["Workflow entry points"]
  node_population_cli["Population CLI"]
  node_refunds_cli["Refunds CLI<br/>[run_refunds.py]"]
  node_trends_cli["Trends CLI<br/>[run_trends.py]"]
  node_textbook_cli["Textbook Brokers CLI"]
end

subgraph group_processing["Data processing"]
  node_population["Population testing<br/>[pipeline.py]"]
  node_refunds["Refund review<br/>[pipeline.py]"]
  node_trends["Historical trends<br/>[pipeline.py]"]
  node_textbook["Textbook TSPLOAD<br/>[pipeline.py]"]
  node_jpmlb["JPMLB conversion<br/>[transform.py]"]
  node_ebill["eBill transformation"]
end

subgraph group_shared["Shared services"]
  node_watcher["Cashier report watcher<br/>[report_watcher.py]"]
  node_insights["Insights API and sessions"]
  node_browser["Persistent browser profiles<br/>[browser_profile.py]"]
  node_banner["Banner automation<br/>[navigation.py]"]
  node_paths["Mines shared paths<br/>[mines_paths.py]"]
end

node_staff(("Bursar staff"))

node_staff -->|"opens"| node_gui
node_gui -->|"loads workflows"| node_registry
node_gui -->|"opens"| node_access
node_gui -->|"opens"| node_connections
node_gui -->|"uses contracts"| node_models
node_gui -->|"resolves policy path"| node_paths
node_registry -->|"defines workflows"| node_models
node_registry -->|"registers runners"| node_gui_access
node_registry -->|"registers watcher"| node_watcher
node_population_cli -->|"runs pipeline"| node_population
node_refunds_cli -->|"runs pipeline"| node_refunds
node_trends_cli -->|"runs pipeline"| node_trends
node_textbook_cli -->|"runs pipeline"| node_textbook
node_gui_access -.->|"invokes"| node_population
node_gui_access -.->|"invokes"| node_refunds
node_gui_access -.->|"invokes"| node_textbook
node_connections -.->|"connects"| node_insights
node_banner -->|"uses profile"| node_browser
node_population -->|"exports assignments"| node_staff
node_refunds -->|"exports review workbook"| node_staff
node_trends -->|"exports trends workbook"| node_staff
node_textbook -->|"creates TSPLOAD CSV"| node_staff

click node_gui "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/main.py"
click node_models "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/models.py"
click node_registry "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/workflow_registry.py"
click node_access "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/pages/access_management.py"
click node_connections "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/pages/connections.py"
click node_gui_access "https://github.com/joshuakosakowsky/highered_automation/tree/main/app/gui/services"
click node_population_cli "https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/population_testing/run_population_testing.py"
click node_refunds_cli "https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/refunds/run_refunds.py"
click node_trends_cli "https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/trends/run_trends.py"
click node_textbook_cli "https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/textbook_brokers/run_textbook_brokers.py"
click node_population "https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/population_testing/pipeline.py"
click node_refunds "https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/refunds/pipeline.py"
click node_trends "https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/trends/pipeline.py"
click node_textbook "https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/textbook_brokers/pipeline.py"
click node_jpmlb "https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/jpmlb/transform.py"
click node_ebill "https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/transact_ebill/transact_ebill_transform.py"
click node_watcher "https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/services/report_watcher.py"
click node_insights "https://github.com/joshuakosakowsky/highered_automation/tree/main/shared/insights"
click node_browser "https://github.com/joshuakosakowsky/highered_automation/blob/main/shared/browser_profile.py"
click node_banner "https://github.com/joshuakosakowsky/highered_automation/blob/main/banner/navigation.py"
click node_paths "https://github.com/joshuakosakowsky/highered_automation/blob/main/shared/mines_paths.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_gui,node_models,node_registry,node_access,node_connections,node_gui_access toneBlue
class node_population_cli,node_refunds_cli,node_trends_cli,node_textbook_cli toneAmber
class node_population,node_refunds,node_trends,node_textbook,node_jpmlb,node_ebill toneMint
class node_watcher,node_insights,node_browser,node_banner,node_paths toneRose
class node_staff toneIndigo
```

## Components

### Desktop app

- [Automation GUI](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/main.py): `app/gui/main.py`
- [Workflow contracts](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/models.py): `app/gui/models.py`
- [Workflow registry](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/workflow_registry.py): `app/gui/workflow_registry.py`
- [Access management](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/pages/access_management.py): `app/gui/pages/access_management.py`
- [Insights connections](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/pages/connections.py): `app/gui/pages/connections.py`
- [GUI workflow adapters](https://github.com/joshuakosakowsky/highered_automation/tree/main/app/gui/services): `app/gui/services`

### Workflow entry points

- [Population CLI](https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/population_testing/run_population_testing.py): `workflows/population_testing/run_population_testing.py`
- [Refunds CLI](https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/refunds/run_refunds.py): `workflows/refunds/run_refunds.py`
- [Trends CLI](https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/trends/run_trends.py): `workflows/trends/run_trends.py`
- [Textbook Brokers CLI](https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/textbook_brokers/run_textbook_brokers.py): `workflows/textbook_brokers/run_textbook_brokers.py`

### Data processing

- [Population testing](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/population_testing/pipeline.py): `data_processing/population_testing/pipeline.py`
- [Refund review](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/refunds/pipeline.py): `data_processing/refunds/pipeline.py`
- [Historical trends](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/trends/pipeline.py): `data_processing/trends/pipeline.py`
- [Textbook TSPLOAD](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/textbook_brokers/pipeline.py): `data_processing/textbook_brokers/pipeline.py`
- [JPMLB conversion](https://github.com/joshuakosakowsky/highered_automation/blob/main/data_processing/jpmlb/transform.py): `data_processing/jpmlb/transform.py`
- [eBill transformation](https://github.com/joshuakosakowsky/highered_automation/blob/main/workflows/transact_ebill/transact_ebill_transform.py): `workflows/transact_ebill/transact_ebill_transform.py`

### Shared services

- [Cashier report watcher](https://github.com/joshuakosakowsky/highered_automation/blob/main/app/gui/services/report_watcher.py): `app/gui/services/report_watcher.py`
- [Insights API and sessions](https://github.com/joshuakosakowsky/highered_automation/tree/main/shared/insights): `shared/insights`
- [Persistent browser profiles](https://github.com/joshuakosakowsky/highered_automation/blob/main/shared/browser_profile.py): `shared/browser_profile.py`
- [Banner automation](https://github.com/joshuakosakowsky/highered_automation/blob/main/banner/navigation.py): `banner/navigation.py`
- [Mines shared paths](https://github.com/joshuakosakowsky/highered_automation/blob/main/shared/mines_paths.py): `shared/mines_paths.py`

### Other components

- **Bursar staff**

## Connections

- Bursar staff → Automation GUI: opens
- Automation GUI → Workflow registry: loads workflows (evidence: `app/gui/main.py`)
- Automation GUI → Access management: opens (evidence: `app/gui/main.py`)
- Automation GUI → Insights connections: opens (evidence: `app/gui/main.py`)
- Automation GUI → Workflow contracts: uses contracts (evidence: `app/gui/main.py`)
- Automation GUI → Mines shared paths: resolves policy path (evidence: `app/gui/main.py`)
- Workflow registry → Workflow contracts: defines workflows (evidence: `app/gui/workflow_registry.py`)
- Workflow registry → GUI workflow adapters: registers runners (evidence: `app/gui/workflow_registry.py`)
- Workflow registry → Cashier report watcher: registers watcher (evidence: `app/gui/workflow_registry.py`)
- Population CLI → Population testing: runs pipeline (evidence: `workflows/population_testing/run_population_testing.py`)
- Refunds CLI → Refund review: runs pipeline (evidence: `workflows/refunds/run_refunds.py`)
- Trends CLI → Historical trends: runs pipeline (evidence: `workflows/trends/run_trends.py`)
- Textbook Brokers CLI → Textbook TSPLOAD: runs pipeline (evidence: `workflows/textbook_brokers/run_textbook_brokers.py`)
- GUI workflow adapters → Population testing: invokes
- GUI workflow adapters → Refund review: invokes
- GUI workflow adapters → Textbook TSPLOAD: invokes
- Insights connections → Insights API and sessions: connects
- Banner automation → Persistent browser profiles: uses profile
- Population testing → Bursar staff: exports assignments (evidence: `data_processing/population_testing/pipeline.py`)
- Refund review → Bursar staff: exports review workbook (evidence: `data_processing/refunds/pipeline.py`)
- Historical trends → Bursar staff: exports trends workbook (evidence: `data_processing/trends/pipeline.py`)
- Textbook TSPLOAD → Bursar staff: creates TSPLOAD CSV (evidence: `data_processing/textbook_brokers/pipeline.py`)