# acl-org/aclpubcheck architecture

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

## Overview

ACL pubcheck is a Python tool for checking ACL paper PDFs and reporting formatting and citation issues. The main workflow is a user invoking the CLI with a paper and paper type; the formatter checks page margins, numbering, fonts, and references, then writes a JSON report and margin-annotated page images. Citation name checking is an integrated branch that uses external bibliography services. The repository also includes publication-chair utilities for validating PDF metadata against submission spreadsheets and optionally posting problems to Google Sheets, plus a utility for producing copyright-signature summaries. Some subsystem links are based on README documentation because their source was not sampled.

Main entry points: [`aclpubcheck/formatchecker.py`](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py) (PDF formatter), [`aclpubcheck/name_check.py`](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/name_check.py) (Citation name check), [`aclpubcheck/metadatachecker.py`](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/metadatachecker.py) (Metadata checker), [`aclpubcheck/copyright_signatures.py`](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/copyright_signatures.py) (Signature summary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_paper_check["Paper checking"]
  node_cli["CLI entry<br/>[__main__.py]"]
  node_formatter["PDF formatter<br/>[formatchecker.py]"]
  node_margin_check["Margin check<br/>[formatchecker.py]"]
  node_page_check["Page and font checks<br/>[formatchecker.py]"]
  node_reference_check["Reference checks<br/>[formatchecker.py]"]
end

subgraph group_citation_check["Citation checking"]
  node_name_check["Citation name check<br/>[name_check.py]"]
  node_scholarcy{{"Scholarcy API"}}
  node_rebiber{{"rebiber"}}
  node_anthology{{"ACL Anthology, DBLP, arXiv"}}
end

subgraph group_chair_tools["Publication-chair tools"]
  node_metadata_checker["Metadata checker<br/>[metadatachecker.py]"]
  node_submission_data["Submission data"]
  node_google_tools["Google Sheets client<br/>[googletools.py]"]
  node_google_sheets[("Google Sheets")]
  node_signature_writer["Signature summary"]
end

subgraph group_outputs["Reports and outputs"]
  node_json_report["JSON report"]
  node_margin_images["Annotated page images"]
  node_signature_file["Signature text file"]
end

node_author(("Paper author"))
node_chair_operator(("Publication chair"))

node_author -->|"runs check"| node_cli
node_cli -->|"invokes"| node_formatter
node_formatter -->|"checks margins"| node_margin_check
node_formatter -->|"checks pages and fonts"| node_page_check
node_formatter -->|"checks references"| node_reference_check
node_formatter -->|"runs name check"| node_name_check
node_name_check -->|"extracts bibliography"| node_scholarcy
node_name_check -->|"updates bibliography"| node_rebiber
node_rebiber -.->|"looks up records"| node_anthology
node_formatter -->|"writes report"| node_json_report
node_formatter -->|"writes annotations"| node_margin_images
node_chair_operator -->|"runs validation"| node_metadata_checker
node_submission_data -->|"provides spreadsheet and PDFs"| node_metadata_checker
node_metadata_checker -->|"requests Sheets client"| node_google_tools
node_google_tools -->|"builds API client"| node_google_sheets
node_chair_operator -->|"runs export"| node_signature_writer
node_submission_data -->|"provides submissions"| node_signature_writer
node_signature_writer -->|"writes summary"| node_signature_file

click node_cli "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/__main__.py"
click node_formatter "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py"
click node_margin_check "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py"
click node_page_check "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py"
click node_reference_check "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py"
click node_name_check "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/name_check.py"
click node_metadata_checker "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/metadatachecker.py"
click node_google_tools "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/googletools.py"
click node_signature_writer "https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/copyright_signatures.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_cli,node_formatter,node_margin_check,node_page_check,node_reference_check toneBlue
class node_name_check,node_scholarcy,node_rebiber,node_anthology toneAmber
class node_metadata_checker,node_submission_data,node_google_tools,node_google_sheets,node_signature_writer toneMint
class node_json_report,node_margin_images,node_signature_file toneRose
class node_author,node_chair_operator toneIndigo
```

## Components

### Paper checking

- [CLI entry](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/__main__.py): `aclpubcheck/__main__.py`
- [PDF formatter](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py): `aclpubcheck/formatchecker.py`
- [Margin check](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py): `aclpubcheck/formatchecker.py`
- [Page and font checks](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py): `aclpubcheck/formatchecker.py`
- [Reference checks](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/formatchecker.py): `aclpubcheck/formatchecker.py`

### Citation checking

- [Citation name check](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/name_check.py): `aclpubcheck/name_check.py`
- **Scholarcy API**
- **rebiber**
- **ACL Anthology, DBLP, arXiv**

### Publication-chair tools

- [Metadata checker](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/metadatachecker.py): `aclpubcheck/metadatachecker.py`
- **Submission data**
- [Google Sheets client](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/googletools.py): `aclpubcheck/googletools.py`
- **Google Sheets**
- [Signature summary](https://github.com/acl-org/aclpubcheck/blob/main/aclpubcheck/copyright_signatures.py): `aclpubcheck/copyright_signatures.py`

### Reports and outputs

- **JSON report**
- **Annotated page images**
- **Signature text file**

### Other components

- **Paper author**
- **Publication chair**

## Connections

- Paper author → CLI entry: runs check (evidence: `README.md`)
- CLI entry → PDF formatter: invokes (evidence: `aclpubcheck/__main__.py`)
- PDF formatter → Margin check: checks margins (evidence: `aclpubcheck/formatchecker.py`)
- PDF formatter → Page and font checks: checks pages and fonts (evidence: `aclpubcheck/formatchecker.py`)
- PDF formatter → Reference checks: checks references (evidence: `aclpubcheck/formatchecker.py`)
- PDF formatter → Citation name check: runs name check (evidence: `aclpubcheck/formatchecker.py`)
- Citation name check → Scholarcy API: extracts bibliography (evidence: `aclpubcheck/name_check.py`)
- Citation name check → rebiber: updates bibliography (evidence: `aclpubcheck/name_check.py`)
- rebiber → ACL Anthology, DBLP, arXiv: looks up records
- PDF formatter → JSON report: writes report (evidence: `README.md`)
- PDF formatter → Annotated page images: writes annotations (evidence: `README.md`)
- Publication chair → Metadata checker: runs validation (evidence: `aclpubcheck/metadatachecker.py`)
- Submission data → Metadata checker: provides spreadsheet and PDFs (evidence: `aclpubcheck/metadatachecker.py`)
- Metadata checker → Google Sheets client: requests Sheets client (evidence: `aclpubcheck/metadatachecker.py`)
- Google Sheets client → Google Sheets: builds API client (evidence: `aclpubcheck/googletools.py`)
- Publication chair → Signature summary: runs export (evidence: `aclpubcheck/copyright_signatures.py`)
- Submission data → Signature summary: provides submissions (evidence: `aclpubcheck/copyright_signatures.py`)
- Signature summary → Signature text file: writes summary (evidence: `aclpubcheck/copyright_signatures.py`)
