# jth6-rice/award-set-up-helper architecture

> Architecture diagram of the GitHub repository jth6-rice/award-set-up-helper, 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/jth6-rice/award-set-up-helper
- Repository: https://github.com/jth6-rice/award-set-up-helper

## Overview

This repository supports award-document extraction and review through a Streamlit dashboard: users stage PDFs, the batch pipeline groups related documents, AI extracts structured award data, and results are written to Google Sheets for review. It also contains a separate Apps Script pre-submission reconciliation workflow and a standalone extraction prototype. The excerpts establish the main Python pipeline and the Apps Script flow; the README is empty, and the tracker’s relationship to the active pipeline is not shown.

Main entry points: [`batch_processor.py`](https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py) (Batch orchestration), [`ai_engine.py`](https://github.com/jth6-rice/award-set-up-helper/blob/main/ai_engine.py) (AI extraction), [`app.py`](https://github.com/jth6-rice/award-set-up-helper/blob/main/app.py) (Review dashboard), [`Award_Set_Up_Amendment_Helper.js`](https://github.com/jth6-rice/award-set-up-helper/blob/main/Award_Set_Up_Amendment_Helper.js) (Pre-submit sweep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Review dashboard"]
  node_dashboard["Review dashboard<br/>[app.py]"]
  node_sheets[("Award records")]
end

subgraph group_pipeline["Award ingestion"]
  node_batch["Batch orchestration<br/>[batch_processor.py]"]
  node_packet["PDF grouping<br/>[batch_processor.py]"]
  node_identifiers["ID reconciliation<br/>[batch_processor.py]"]
  node_engine["AI extraction<br/>[ai_engine.py]"]
end

subgraph group_reference["Extraction rules"]
  node_parser["Registry parsing<br/>[core_parser.py]"]
  node_protocol["Extraction protocol<br/>[1.71.md]"]
end

subgraph group_alternate["Other workflows"]
  node_script["Pre-submit sweep"]
  node_prototype["Extraction prototype"]
  node_tracker[("Pipeline tracker<br/>[tracker.py]")]
end

node_reviewer(("Reviewer"))
node_submitter(("PDF submitter"))
node_gemini{{"Gemini API"}}
node_drive[("Google Drive")]

node_reviewer -->|"reviews records"| node_dashboard
node_submitter -->|"stages PDFs"| node_dashboard
node_dashboard -->|"starts processing"| node_batch
node_dashboard -->|"loads records"| node_sheets
node_batch -->|"groups PDFs"| node_packet
node_batch -->|"requests extraction"| node_engine
node_engine -->|"loads registries"| node_parser
node_engine -->|"loads rules"| node_protocol
node_engine -->|"uploads and queries"| node_gemini
node_batch -->|"resolves identifiers"| node_identifiers
node_batch -->|"writes extracted data"| node_sheets
node_script -->|"reads PDFs and references"| node_drive
node_script -->|"requests reconciliation"| node_gemini
node_script -->|"appends results"| node_sheets
node_prototype -->|"extracts award data"| node_gemini

click node_dashboard "https://github.com/jth6-rice/award-set-up-helper/blob/main/app.py"
click node_sheets "https://github.com/jth6-rice/award-set-up-helper/blob/main/sheets_interface.py"
click node_batch "https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py"
click node_packet "https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py"
click node_identifiers "https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py"
click node_engine "https://github.com/jth6-rice/award-set-up-helper/blob/main/ai_engine.py"
click node_parser "https://github.com/jth6-rice/award-set-up-helper/blob/main/core_parser.py"
click node_protocol "https://github.com/jth6-rice/award-set-up-helper/blob/main/1.71.md"
click node_script "https://github.com/jth6-rice/award-set-up-helper/blob/main/Award_Set_Up_Amendment_Helper.js"
click node_prototype "https://github.com/jth6-rice/award-set-up-helper/blob/main/google-generativeai.py"
click node_tracker "https://github.com/jth6-rice/award-set-up-helper/blob/main/tracker.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_dashboard,node_sheets,node_reviewer toneBlue
class node_batch,node_packet,node_identifiers,node_engine,node_drive toneAmber
class node_parser,node_protocol,node_gemini toneMint
class node_script,node_prototype,node_tracker toneRose
class node_submitter toneIndigo
```

## Components

### Review dashboard

- [Review dashboard](https://github.com/jth6-rice/award-set-up-helper/blob/main/app.py): `app.py`
- [Award records](https://github.com/jth6-rice/award-set-up-helper/blob/main/sheets_interface.py): `sheets_interface.py`

### Award ingestion

- [Batch orchestration](https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py): `batch_processor.py`
- [PDF grouping](https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py): `batch_processor.py`
- [ID reconciliation](https://github.com/jth6-rice/award-set-up-helper/blob/main/batch_processor.py): `batch_processor.py`
- [AI extraction](https://github.com/jth6-rice/award-set-up-helper/blob/main/ai_engine.py): `ai_engine.py`

### Extraction rules

- [Registry parsing](https://github.com/jth6-rice/award-set-up-helper/blob/main/core_parser.py): `core_parser.py`
- [Extraction protocol](https://github.com/jth6-rice/award-set-up-helper/blob/main/1.71.md): `1.71.md`

### Other workflows

- [Pre-submit sweep](https://github.com/jth6-rice/award-set-up-helper/blob/main/Award_Set_Up_Amendment_Helper.js): `Award_Set_Up_Amendment_Helper.js`
- [Extraction prototype](https://github.com/jth6-rice/award-set-up-helper/blob/main/google-generativeai.py): `google-generativeai.py`
- [Pipeline tracker](https://github.com/jth6-rice/award-set-up-helper/blob/main/tracker.py): `tracker.py`

### Other components

- **Reviewer**
- **PDF submitter**
- **Gemini API**
- **Google Drive**

## Connections

- Reviewer → Review dashboard: reviews records (evidence: `app.py`)
- PDF submitter → Review dashboard: stages PDFs (evidence: `app.py`)
- Review dashboard → Batch orchestration: starts processing (evidence: `app.py`)
- Review dashboard → Award records: loads records (evidence: `app.py`)
- Batch orchestration → PDF grouping: groups PDFs (evidence: `batch_processor.py`)
- Batch orchestration → AI extraction: requests extraction (evidence: `batch_processor.py`)
- AI extraction → Registry parsing: loads registries (evidence: `ai_engine.py`)
- AI extraction → Extraction protocol: loads rules (evidence: `ai_engine.py`)
- AI extraction → Gemini API: uploads and queries (evidence: `ai_engine.py`)
- Batch orchestration → ID reconciliation: resolves identifiers (evidence: `batch_processor.py`)
- Batch orchestration → Award records: writes extracted data (evidence: `batch_processor.py`)
- Pre-submit sweep → Google Drive: reads PDFs and references (evidence: `Award_Set_Up_Amendment_Helper.js`)
- Pre-submit sweep → Gemini API: requests reconciliation (evidence: `Award_Set_Up_Amendment_Helper.js`)
- Pre-submit sweep → Award records: appends results (evidence: `Award_Set_Up_Amendment_Helper.js`)
- Extraction prototype → Gemini API: extracts award data (evidence: `google-generativeai.py`)