# johnedwardabearneza/bpm_court_scanner architecture

> Architecture diagram of the GitHub repository johnedwardabearneza/bpm_court_scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnedwardabearneza/bpm_court_scanner
- Repository: https://github.com/johnedwardabearneza/bpm_court_scanner

## Overview

BPM Court Scanner is a local desktop application for finding, classifying, and downloading appellate briefs from New York and Kentucky court systems, with Excel tracking and reports. The main user path starts in the desktop interface, proceeds through jurisdiction-specific scanning and classification, then presents hits and saved reports. The graph also includes NY scan orchestration and shared runtime configuration. Some modules are represented from the SOURCE INDEX or README rather than inspected source; uncertain links are omitted or marked unverified.

Main entry points: [`gui.py`](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui.py) (Desktop GUI), [`main.py`](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/main.py) (NY scan orchestration), [`gui_ky.py`](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_ky.py) (KY interface), [`gui_worker.py`](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_worker.py) (NY scan worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop interface"]
  node_gui["Desktop GUI<br/>[gui.py]"]
  node_ny_hits["NY hit list<br/>[gui_hits.py]"]
  node_ky_gui["KY interface<br/>[gui_ky.py]"]
end

subgraph group_ny["New York scanning"]
  node_worker["NY scan worker<br/>[gui_worker.py]"]
  node_ny_orchestrator["NY scan orchestration<br/>[main.py]"]
  node_browser["NYSCEF browser<br/>[nyscef_browser.py]"]
  node_pdf_parser["Motion PDF parser<br/>[pdf_parser.py]"]
end

subgraph group_ky["Kentucky scanning"]
  node_ky_scanner["KY docket scanner<br/>[ky_scanner.py]"]
  node_ky_xlsx["KY Excel tracker<br/>[ky_xlsx.py]"]
end

subgraph group_results["Results and records"]
  node_classifier["Brief classifier<br/>[classifier.py]"]
  node_reports["Hit reports<br/>[report_builder.py]"]
  node_monthly["Monthly reports<br/>[monthly_report.py]"]
  node_dashboard["Dashboard server"]
end

subgraph group_runtime["Shared runtime"]
  node_clear["Data reset<br/>[clear_manager.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_remote_guard["Remote access guard<br/>[remote_guard.py]"]
  node_updater["Update checker<br/>[updater.py]"]
end

node_user(("Legal researcher"))
node_ny_portal["NY court portals"]
node_ky_portal["Kentucky court systems"]

node_user -->|"uses"| node_gui
node_gui -->|"starts scans"| node_worker
node_gui -->|"opens hits"| node_ny_hits
node_gui -->|"opens Kentucky"| node_ky_gui
node_gui -->|"resets data"| node_clear
node_gui -->|"checks updates"| node_updater
node_gui -->|"checks access"| node_remote_guard
node_worker -->|"runs scans"| node_ny_orchestrator
node_worker -->|"opens session"| node_browser
node_ny_orchestrator -->|"checks cases"| node_browser
node_browser -->|"browses and downloads"| node_ny_portal
node_ny_orchestrator -.->|"parses motion lists"| node_pdf_parser
node_ny_orchestrator -->|"classifies filings"| node_classifier
node_ny_orchestrator -->|"saves checkpoints"| node_reports
node_ny_hits -->|"displays hit data"| node_reports
node_gui -->|"shows monthly results"| node_monthly
node_ky_gui -->|"synchronizes dockets"| node_ky_scanner
node_ky_scanner -->|"fetches docket data"| node_ky_portal
node_ky_gui -->|"updates tracker"| node_ky_xlsx
node_user -.->|"views reports"| node_dashboard
node_dashboard -.->|"uses scanner"| node_ky_scanner
node_dashboard -.->|"uses report data"| node_reports
node_gui -->|"uses settings"| node_config
node_worker -->|"uses scan settings"| node_config
node_ky_gui -->|"uses settings"| node_config
node_clear -->|"uses data paths"| node_config

click node_gui "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui.py"
click node_ny_hits "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_hits.py"
click node_ky_gui "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_ky.py"
click node_worker "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_worker.py"
click node_ny_orchestrator "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/main.py"
click node_browser "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/nyscef_browser.py"
click node_pdf_parser "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/pdf_parser.py"
click node_classifier "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/classifier.py"
click node_reports "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/report_builder.py"
click node_monthly "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/monthly_report.py"
click node_ky_scanner "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/ky_scanner.py"
click node_ky_xlsx "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/ky_xlsx.py"
click node_dashboard "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/dashboard_server.py"
click node_clear "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/clear_manager.py"
click node_config "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/config.py"
click node_remote_guard "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/remote_guard.py"
click node_updater "https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/updater.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_ny_hits,node_ky_gui toneBlue
class node_worker,node_ny_orchestrator,node_browser,node_pdf_parser toneAmber
class node_ky_scanner,node_ky_xlsx toneMint
class node_classifier,node_reports,node_monthly,node_dashboard toneRose
class node_clear,node_config,node_remote_guard,node_updater,node_user,node_ny_portal,node_ky_portal toneIndigo
```

## Components

### Desktop interface

- [Desktop GUI](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui.py): `gui.py`
- [NY hit list](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_hits.py): `gui_hits.py`
- [KY interface](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_ky.py): `gui_ky.py`

### New York scanning

- [NY scan worker](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/gui_worker.py): `gui_worker.py`
- [NY scan orchestration](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/main.py): `main.py`
- [NYSCEF browser](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/nyscef_browser.py): `nyscef_browser.py`
- [Motion PDF parser](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/pdf_parser.py): `pdf_parser.py`

### Kentucky scanning

- [KY docket scanner](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/ky_scanner.py): `ky_scanner.py`
- [KY Excel tracker](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/ky_xlsx.py): `ky_xlsx.py`

### Results and records

- [Brief classifier](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/classifier.py): `classifier.py`
- [Hit reports](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/report_builder.py): `report_builder.py`
- [Monthly reports](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/monthly_report.py): `monthly_report.py`
- [Dashboard server](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/dashboard_server.py): `dashboard_server.py`

### Shared runtime

- [Data reset](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/clear_manager.py): `clear_manager.py`
- [Runtime configuration](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/config.py): `config.py`
- [Remote access guard](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/remote_guard.py): `remote_guard.py`
- [Update checker](https://github.com/johnedwardabearneza/bpm_court_scanner/blob/main/updater.py): `updater.py`

### Other components

- **Legal researcher**
- **NY court portals**
- **Kentucky court systems**

## Connections

- Legal researcher → Desktop GUI: uses (evidence: `README.md`)
- Desktop GUI → NY scan worker: starts scans (evidence: `gui.py`)
- Desktop GUI → NY hit list: opens hits (evidence: `gui.py`)
- Desktop GUI → KY interface: opens Kentucky (evidence: `gui.py`)
- Desktop GUI → Data reset: resets data (evidence: `gui.py`)
- Desktop GUI → Update checker: checks updates (evidence: `gui.py`)
- Desktop GUI → Remote access guard: checks access (evidence: `gui.py`)
- NY scan worker → NY scan orchestration: runs scans (evidence: `gui_worker.py`)
- NY scan worker → NYSCEF browser: opens session (evidence: `gui_worker.py`)
- NY scan orchestration → NYSCEF browser: checks cases (evidence: `main.py`)
- NYSCEF browser → NY court portals: browses and downloads (evidence: `README.md`)
- NY scan orchestration → Motion PDF parser: parses motion lists (evidence: `main.py`)
- NY scan orchestration → Brief classifier: classifies filings (evidence: `main.py`)
- NY scan orchestration → Hit reports: saves checkpoints (evidence: `main.py`)
- NY hit list → Hit reports: displays hit data (evidence: `gui_hits.py`)
- Desktop GUI → Monthly reports: shows monthly results (evidence: `gui.py`)
- KY interface → KY docket scanner: synchronizes dockets (evidence: `gui_ky.py`)
- KY docket scanner → Kentucky court systems: fetches docket data (evidence: `README.md`)
- KY interface → KY Excel tracker: updates tracker (evidence: `gui_ky.py`)
- Legal researcher → Dashboard server: views reports
- Dashboard server → KY docket scanner: uses scanner (evidence: `dashboard_server.py`)
- Dashboard server → Hit reports: uses report data (evidence: `dashboard_server.py`)
- Desktop GUI → Runtime configuration: uses settings (evidence: `gui.py`)
- NY scan worker → Runtime configuration: uses scan settings (evidence: `gui_worker.py`)
- KY interface → Runtime configuration: uses settings (evidence: `gui_ky.py`)
- Data reset → Runtime configuration: uses data paths (evidence: `clear_manager.py`)
