warehouse-master/ARCHITECTURE.md

Architecture

Overview

Warehouse Master is a desktop application for printing numbered PDF labels and tracking laptop reassembly via Google Sheets. Two independent tabs: Labels (PDF generation) and Reassembly (Google Sheets sync).

File structure

File	Purpose
main.py	Entry point, LabelApp main window, tab lifecycle, i18n dispatch
printing.py	Utilities: file I/O, resource paths, printer discovery, app config folder
styles.py	Stylesheet builder: build_stylesheet(dark: bool) → returns CSS for both themes
workers.py	Background threads: PDFWorker (reportlab), ReassemblyWorker (gspread sync)
widgets.py	Reusable UI: NoScrollComboBox, RangeRowWidget, PreferencesDialog
strings.py	i18n: STRINGS dict {"en": {...}, "ru": {...}} with all UI strings
sheet_manager.py	Google Sheets API wrapper: config-driven column indices, category calculation, batch updates
sheet_config.example.json	Template config: worksheets, column mappings, translators, statuses
WarehouseMaster.spec	PyInstaller spec: bundles Inter.ttf, builds single-file exe
requirements.txt	Dependencies: PyQt5, reportlab, gspread, google-auth

Module responsibilities

main.py

• Loads/saves QSettings (theme, language, window state)
• Renders two tabs: labels and reassembly
• Wires up event handlers
• Calls _retranslate() on locale change
• Temp file cleanup on close

printing.py

• resource_path() — finds bundled files (Inter.ttf, icon.ico)
• app_data_dir() — %APPDATA%/WarehouseMaster/ for token.json, local configs
• config_path() — returns sheet_config.json (local or appdata)
• register_fonts() — loads Inter.ttf into reportlab
• get_installed_printers() — enumerates Windows printers (win32api)
• open_file() — cross-platform file open (Windows/macOS/Linux)
• print_file() — print to specific printer or system default

styles.py

• build_stylesheet(dark: bool) — single function, returns full QPalette CSS
• Colors hardcoded (dark: #212529 bg, #f8f9fa text; light: inverse)
• Called on theme toggle → setStyleSheet()

workers.py

• PDFWorker(QThread) — generates PDF in background, emits finished(filepath) or error_occurred(str)
• ReassemblyWorker(QThread) — calls SheetManager.process_reassembly(), emits finished_signal(comment, tech_op) or error_signal(str)
• Both prevent UI freeze

widgets.py

• NoScrollComboBox — suppresses scroll-wheel zoom
• RangeRowWidget — start/end inputs + +/- buttons; callback-driven
• PreferencesDialog — language + theme + sheet URL + save folder, saves to QSettings

strings.py

• Two dicts: STRINGS["en"], STRINGS["ru"]
• Keys: "window_title", "tab_labels", message templates with {n} placeholders
• No locale switching logic — main.py reads settings.value("locale") and indexes

sheet_manager.py

• SheetManager(sheet_url, config_path) — loads config.json, authorizes gspread
• process_reassembly(laptop_id, parts_str, ssd_id, akb_id) — atomically updates: marks parts shipped, writes grades to laptop row, recalculates category (D/C/B/A/NEW)
• _calculate_category(laptop_data) — rule-based scoring (D if any part ≤rank 1, NEW if all ≥A and cycles < 150, etc.)
• Config-driven: all column indices, range clears, status values from sheet_config.json

Hot paths

PDF generation

1. User clicks "Generate PDF"
2. _start_generation() validates ranges (start ≤ end), spawns PDFWorker
3. PDFWorker.run() → reportlab.canvas draws labels in grid layout
4. On success: _on_pdf_done() → open file or print
5. UI unblocked (worker thread)

Reassembly sync

1. User fills order/parts, clicks "Apply changes"
2. _run_reassembly() spawns ReassemblyWorker
3. ReassemblyWorker.run() → SheetManager.process_reassembly()
4. Manager: fetches IDs from all worksheets, processes each part (SSD/battery/part), calculates new category
5. Batch updates all sheets, returns comment + tech lines
6. _on_reassembly_done() displays results
7. UI unblocked

Adding things

New label format (e.g., 6×6 grid)

1. Add to PAGE_SIZES and DEFAULT_FONT_SIZES in workers.py
2. Add radio button in _init_gen_tab()
3. Add branch in PDFWorker.run() for grid layout

New reassembly field

1. Add config key to sheet_config.example.json (e.g., "warranty_months": 52)
2. Read in SheetManager.__init__() via self.cfg
3. Add processing in _process_part() or new _process_<thing>() method

New language

1. Add STRINGS["new_lang"] dict in strings.py
2. Add to language combo in PreferencesDialog (widgets.py)
3. Map combo index → locale code (e.g., index 2 → "de")

New Google Sheets worksheet

1. Add to sheet_config.json → worksheets
2. Add column mappings if needed
3. Add fetch/batch in SheetManager methods
4. Wire up in process_reassembly()

Gotchas

• QSettings casing: Linux filenames are case-sensitive; use lowercase keys ("sheet_url" not "SheetURL")
• Token refresh: If gspread credentials expire mid-session, worker will fail; user must restart and re-auth
• Column alignment: reportlab canvas Y-axis is bottom-up (0 = bottom). Grid layout offsets Y correctly with ph - (row + 1) * cell_h
• Config missing: If sheet_config.json missing, SheetManager raises on init; handle in UI with try-except, show user-friendly message
• Cyrillic grades: Before rank check, normalize Cyrillic А/В/С/Д → Latin A/B/C/D via str.maketrans()
• Printer not found: If saved printer deleted, findText() returns -1; guard before setCurrentIndex()
• Temp files: If app crashes, temp PDFs not deleted; consider OS-level temp cleanup (tmp dirs auto-purge)