# gipson-dev/py232-scale architecture

> Architecture diagram of the GitHub repository gipson-dev/py232-scale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gipson-dev/py232-scale
- Repository: https://github.com/gipson-dev/py232-scale

## Overview

1. **Overall shape**
   - PY 232 Scale is a **Windows-only desktop application** with a single-user GUI.
   - The app sits between a **serial-connected scale** and an **Excel workbook output** used as a printable QC checklist.

2. **Entry point and app composition**
   - `main.py` is the startup entry point and likely wires together the GUI and core logic.
   - The core runtime is split into two main modules:
     - `scale_logger/gui.py` for the desktop interface
     - `scale_logger/core.py` for scale parsing and workbook/log processing

3. **User interface layer**
   - The GUI is built with **PySide6**.
   - It manages:
     - project/item entry
     - live scale display
     - captured weight tables
     - settings dialogs/menus
     - log open/save/print actions
     - theme switching and console visibility
   - The UI is the main orchestration layer that reacts to user actions and incoming scale data.

4. **Serial input boundary**
   - The app communicates with the scale over a **Windows COM port** using **pyserial**.
   - The serial boundary is configurable by:
     - port
     - baudrate
     - DTR
     - RTS
   - A receive loop reads raw lines from the device, and the app can also run COM-port and receive tests for troubleshooting.

5. **Scale parsing and normalization**
   - `scale_logger/core.py` contains the logic that interprets raw scale output.
   - It supports both numeric weight lines and ticket-style text lines such as `Net: 0.177kg`.
   - Parsed readings are normalized into values the GUI and workbook logic can use.

6. **Logging/workbook subsystem**
   - Workbook generation and updates use **openpyxl**.
   - Each log is an `.xlsx` file with two main sheets:
     - `QC Form` for the printable checklist
     - `Raw Data` for timestamped captured readings and raw serial lines
   - The workbook appears to be created from or aligned with `weight_qc_checklist_template.xlsx`.

7. **Capture and item workflow**
   - The app records up to **three weights per item**.
   - For each completed item, the logic:
     - sorts the three readings
     - marks the lowest as `Low`
     - marks the highest as `High`
     - updates summary totals for all low/high readings
   - This means the app has a stateful “current log / current item / current captures” flow rather than a stateless import/export model.

8. **Editing and continuation flow**
   - Existing logs can be reopened and edited.
   - The app supports correcting:
     - item names/descriptions
     - individual captured weights
     - continuing an item with new captures
   - When edits happen, the workbook logic rebuilds low/high markings and summary totals, so the spreadsheet is treated as the source of truth after reopening.

9. **Persistence and filesystem boundary**
   - Logs are automatically saved into a `Logs` folder.
   - The folder location depends on deployment mode:
     - beside the executable for packaged builds
     - in the project directory for source runs
   - File naming is sequential, like `Weight_QC_Form 1.xlsx`, `Weight_QC_Form 2.xlsx`, etc.

10. **Printing boundary**
    - Printing is handled directly from the application, without requiring Excel.
    - The app sends the printable `QC Form` worksheet to a selected **Windows printer**.
    - This is a separate external boundary from the workbook file itself: save first, then print the worksheet.

11. **Debugging and operator support tools**
    - `com_port_test.py` and `recieve_test.py` are standalone helper scripts for serial testing.
    - The GUI also exposes these capabilities through menus, which suggests the serial layer is a common operational risk and intentionally surfaced for support.

12. **Packaging and deployment**
    - The project is packaged with **PyInstaller** using:
      - `py232_scale.spec` for a folder-based distribution
      - `py232_scale_onefile.spec` for a single-file executable
    - Build scripts (`build_exe.bat`, `setup.bat`, `run.bat`) are supporting tooling, not runtime subsystems.
    - This is a desktop-distribution architecture, not a service or web deployment.

13. **Key architectural boundaries for a diagram**
    - **Operator/UI boundary:** user enters items, captures weights, edits logs, prints reports
    - **Serial device boundary:** COM port stream from the scale into the app
    - **Workbook boundary:** in-memory log state written to `.xlsx`
    - **Filesystem boundary:** `Logs` folder for persisted files
    - **Printer boundary:** direct Windows print output from `QC Form`

14. **Primary data flow**
    - User defines a job in the GUI → app opens/configures serial port → live scale readings stream in → user captures up to three readings per item → core logic classifies/sorts readings and updates workbook → workbook is saved to `Logs` → user may reopen/edit/print the same file later.

Main entry points: [`scale_logger/gui.py`](https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/gui.py) (GUI), [`scale_logger/core.py`](https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/core.py) (Core), [`main.py`](https://github.com/gipson-dev/py232-scale/blob/main/main.py) (Startup), [`build_exe.bat`](https://github.com/gipson-dev/py232-scale/blob/main/build_exe.bat) (Build script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main_py(("Startup<br/>entrypoint<br/>[main.py]"))
  node_gui["GUI<br/>pyside6 desktop<br/>[gui.py]"]
  node_core["Core<br/>scale/workbook logic<br/>[core.py]"]
end

subgraph group_boundaries["External boundaries"]
  node_serial_port(("Scale<br/>serial device"))
  node_printer(("Printer<br/>windows print"))
  node_logs_folder[("Logs folder<br/>filesystem store")]
  node_workbook["Workbook<br/>xlsx log"]
  node_template["Template<br/>xlsx base"]
end

subgraph group_tooling["Packaging and support"]
  node_com_test(("COM test<br/>serial helper<br/>[com_port_test.py]"))
  node_recv_test(("Receive test<br/>serial helper<br/>[recieve_test.py]"))
  node_spec_folder["Folder build<br/>pyinstaller spec<br/>[py232_scale.spec]"]
  node_spec_onefile["One-file build<br/>pyinstaller spec"]
  node_build_bat["Build script<br/>windows batch<br/>[build_exe.bat]"]
  node_setup_bat["Setup script<br/>windows batch<br/>[setup.bat]"]
  node_run_bat["Run script<br/>windows batch<br/>[run.bat]"]
end

node_main_py -->|"starts"| node_gui
node_main_py -->|"wires"| node_core
node_gui -->|"calls"| node_core
node_gui -->|"opens"| node_serial_port
node_serial_port -->|"streams"| node_core
node_core -->|"updates"| node_workbook
node_workbook -.->|"based on"| node_template
node_core -->|"saves to"| node_logs_folder
node_gui -->|"opens"| node_logs_folder
node_core -->|"prints"| node_printer
node_gui -->|"triggers"| node_printer
node_gui -.->|"surfaces"| node_com_test
node_gui -.->|"surfaces"| node_recv_test
node_spec_folder -.->|"packages"| node_main_py
node_spec_onefile -.->|"packages"| node_main_py
node_build_bat -.->|"uses"| node_spec_folder
node_build_bat -.->|"uses"| node_spec_onefile
node_setup_bat -.->|"supports"| node_run_bat

click node_main_py "https://github.com/gipson-dev/py232-scale/blob/main/main.py"
click node_gui "https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/gui.py"
click node_core "https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/core.py"
click node_workbook "https://github.com/gipson-dev/py232-scale/blob/main/weight_qc_checklist_template.xlsx"
click node_template "https://github.com/gipson-dev/py232-scale/blob/main/weight_qc_checklist_template.xlsx"
click node_com_test "https://github.com/gipson-dev/py232-scale/blob/main/com_port_test.py"
click node_recv_test "https://github.com/gipson-dev/py232-scale/blob/main/recieve_test.py"
click node_spec_folder "https://github.com/gipson-dev/py232-scale/blob/main/py232_scale.spec"
click node_spec_onefile "https://github.com/gipson-dev/py232-scale/blob/main/py232_scale_onefile.spec"
click node_build_bat "https://github.com/gipson-dev/py232-scale/blob/main/build_exe.bat"
click node_setup_bat "https://github.com/gipson-dev/py232-scale/blob/main/setup.bat"
click node_run_bat "https://github.com/gipson-dev/py232-scale/blob/main/run.bat"

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_main_py,node_gui,node_core toneBlue
class node_serial_port,node_printer,node_logs_folder,node_workbook,node_template toneAmber
class node_com_test,node_recv_test,node_spec_folder,node_spec_onefile,node_build_bat,node_setup_bat,node_run_bat toneMint
```

## Components

### Application runtime

Desktop app entrypoint, UI, and core log/workbook logic.

- [Startup](https://github.com/gipson-dev/py232-scale/blob/main/main.py): entrypoint · Application launch and top-level wiring. · `main.py`
- [GUI](https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/gui.py): pyside6 desktop · Operator interface for capture, editing, settings, and print actions. · `scale_logger/gui.py`
- [Core](https://github.com/gipson-dev/py232-scale/blob/main/scale_logger/core.py): scale/workbook logic · Parses scale data, manages capture state, and updates workbook contents. · `scale_logger/core.py`

### External boundaries

Hardware, filesystem, workbook, and printer interfaces.

- **Scale**: serial device · Windows COM-port scale stream consumed by the app.
- **Printer**: windows print · Selected Windows printer used to print the QC form sheet.
- **Logs folder**: filesystem store · Persistent location for saved workbook logs.
- [Workbook](https://github.com/gipson-dev/py232-scale/blob/main/weight_qc_checklist_template.xlsx): xlsx log · In-memory and persisted QC log workbook with printable and raw-data sheets. · `weight_qc_checklist_template.xlsx`
- [Template](https://github.com/gipson-dev/py232-scale/blob/main/weight_qc_checklist_template.xlsx): xlsx base · Checklist template used to seed or align generated workbooks. · `weight_qc_checklist_template.xlsx`

### Packaging and support

Build and diagnostic helpers around the desktop distribution.

- [COM test](https://github.com/gipson-dev/py232-scale/blob/main/com_port_test.py): serial helper · Standalone script for port troubleshooting. · `com_port_test.py`
- [Receive test](https://github.com/gipson-dev/py232-scale/blob/main/recieve_test.py): serial helper · Standalone script for receive-loop troubleshooting. · `recieve_test.py`
- [Folder build](https://github.com/gipson-dev/py232-scale/blob/main/py232_scale.spec): pyinstaller spec · PyInstaller spec for folder-based distribution. · `py232_scale.spec`
- [One-file build](https://github.com/gipson-dev/py232-scale/blob/main/py232_scale_onefile.spec): pyinstaller spec · PyInstaller spec for single-file executable distribution. · `py232_scale_onefile.spec`
- [Build script](https://github.com/gipson-dev/py232-scale/blob/main/build_exe.bat): windows batch · Helper script for building the executable. · `build_exe.bat`
- [Setup script](https://github.com/gipson-dev/py232-scale/blob/main/setup.bat): windows batch · Helper script for preparing the project environment. · `setup.bat`
- [Run script](https://github.com/gipson-dev/py232-scale/blob/main/run.bat): windows batch · Helper script for launching the app from source or distribution. · `run.bat`

## Connections

- Startup → GUI: starts · Launch entrypoint initializes the desktop interface.
- Startup → Core: wires · Startup connects UI events to the core processing logic.
- GUI → Core: calls · UI delegates parsing, capture, edit, and workbook actions to core logic.
- GUI → Scale: opens · User configures and starts the COM-port connection from the interface.
- Scale → Core: streams · Raw scale lines flow into parsing and normalization.
- Core → Workbook: updates · Captured readings and item state are written into the workbook model.
- Workbook → Template: based on · Generated logs align with the checklist template structure.
- Core → Logs folder: saves to · Completed logs are persisted as sequential XLSX files.
- GUI → Logs folder: opens · Operator can reopen existing logs for edit/continue workflows.
- Core → Printer: prints · Printable QC sheet is sent directly to a Windows printer.
- GUI → Printer: triggers · Print action is exposed through the operator interface.
- GUI → COM test: surfaces · Troubleshooting access is exposed from the desktop menus.
- GUI → Receive test: surfaces · Receive-loop diagnostics are exposed from the desktop menus.
- Folder build → Startup: packages · Folder distribution bundles the application entrypoint.
- One-file build → Startup: packages · Single-file distribution bundles the application entrypoint.
- Build script → Folder build: uses · Build helper invokes packaging configuration.
- Build script → One-file build: uses · Build helper supports alternate packaging mode.
- Setup script → Run script: supports · Environment setup enables local execution workflow.