How cata-af/scandoc works
1. Overall shape
- This is a Godot 4.5 desktop tool for validating DOCX reports, not a server or game.
- The app is a thin UI shell around a document-processing pipeline that runs external converters, then inspects the generated XHTML/XML.
2. Main user-facing flow
- The user drops one or more .docx files into the main window.
- The app lists them in the left panel, processes them on demand, and shows a result card per file on the right.
- Each result card can open the generated XHTML in the browser and display integrity comments.
3. Primary orchestration layer
- scripts/ICMain.gd is the central controller.
- It manages runtime folders (bin/ for dependencies, temp/ for outputs), drag-and-drop, dependency checks, download bootstrapping, and per-file conversion jobs.
- It also owns the progress/update flow and closes cleanly when background work is still active.
4. Processing and conversion boundary
- The app does not convert DOCX itself; it delegates conversion to downloaded external tools:
- LibreOffice portable for XHTML generation.
- Pandoc for XML generation.
- These are fetched at runtime and cached locally, which makes the app self-contained after the first download.
- On Windows it depends on 7z.exe for extraction; on Linux there is support for tar-based extraction, and a Linux simulation mode can mimic Windows/Wine behavior.
5. Per-file analysis layer
- scripts/ICProcessedFile.gd encapsulates the work for one converted document.
- It receives the generated XHTML/XML paths, performs integrity checks, mutates the XHTML with annotations, and populates the UI card.
- This keeps the “file processing” boundary separate from the global app orchestration.
6. Document integrity rules
- Validation is content-specific and appears to be tailored to telecom report types:
- LTE: checks KPI sections such as RSRP, SINR, VoLTE drop rate, and handover metrics, with different handling for high/low bands.
- UMTS: checks RSCP, EcIo, call drop rate, and SHO success rate.
- The file type is inferred from the filename, so naming convention is part of the data model.
7. XHTML/XML manipulation
- The app reads and edits generated XHTML, not the original DOCX.
- It injects an “Integrity Check Comments” block, adds warnings for broken images, and annotates media-count discrepancies.
- The bundled addons/godot_xml plugin is the XML-processing dependency that supports parsing/traversal of XML-like document content.
8. Media validation
- A dedicated check scans for broken/corrupt embedded images, using base64-pattern detection and replacing bad content with a visible marker.
- Another pass counts figures, tables, and images by section and compares declared figures against actual media presence.
- This is a key quality-control subsystem because the app is not only checking KPIs but also report completeness.
9. UI structure
- main.tscn is the top-level interface and hosts the dependency panel, input list, and output container.
- scenes/processed_file.tscn is a reusable collapsible card for each processed document.
- scripts/ICProcessedFile.gd and scripts/ICMain.gd are the runtime logic behind those scenes.
10. Runtime and external boundaries
- The repo is a hybrid of Godot UI, external CLI converters, and local file-system processing.
- Network access is only needed to download dependencies the first time.
- The browser is used as an output viewer for the generated XHTML, but the source DOCX is never overwritten.
11. Auxiliary code and tooling
- docx_to_html_converter/ is a separate Python subproject in the repository, but the main app path described in the README relies on Godot plus LibreOffice/Pandoc.
- styles/button_outline.tres and the scene files indicate the UI is theme-driven and assembled in Godot editor rather than handwritten.
12. What an architecture diagram should emphasize
- A single central UI controller orchestrating:
- user input,
- dependency bootstrap,
- document conversion,
- per-file validation,
- and presentation of results.
- The most important boundaries are between Godot UI logic, external document converters, and local XHTML/XML analysis/output.
Main entry points: ICMain.gd App controller · ICProcessedFile.gd File processor · main.tscn Main window · processed_file.tscn Result card
Components 18
Godot app
Desktop UI shell and scene runtime
- Main window · Top-level Godot interface with dependency panel, input list, and results area
main.tscn - App controller · Central runtime controller for drag-and-drop, dependency bootstrap, job execution, and shutdown
scripts/ICMain.gd - Result card · Reusable collapsible card for one processed document
scenes/processed_file.tscn - Browser view · Opens generated XHTML for inspection
- Site container · Reusable scene/container used by the interface
scenes/site_container.tscn - Site script · Script behind the site container UI component
scenes/ICSiteContainer.gd - Button style · UI styling resource used by the Godot interface
styles/button_outline.tres
Document analysis
Per-file conversion, XHTML mutation, and integrity checks
- File processor · Per-document conversion, validation, XHTML mutation, and UI population
scripts/ICProcessedFile.gd - Format rules · Filename-driven document type detection and report-specific validation rules
scripts/ICFormats.gd - Integrity checks · KPI validation, media counting, broken image detection, and integrity comments injection
- Media audit · Scans embedded images and compares declared figures with actual media presence
- XML plugin · Godot XML parsing and traversal support for XHTML/XML content
addons/godot_xml/xml.gd
External tools
Downloaded converters and runtime dependencies
- LibreOffice · Downloaded portable dependency used to generate XHTML
- Pandoc · Downloaded dependency used to generate XML
- 7-Zip · Windows extraction dependency for bundled downloads
- Tar tool · Linux extraction path for downloaded archives
- Runtime cache · Local bin and temp folders used for cached dependencies and conversion outputs
Auxiliary subproject
Separate Python-based converter code
- Python converter · Separate docx_to_html_converter project included in the repo
docx_to_html_converter/main.py
Connections 18
- Main window → App controller: runs · The main scene is driven by the central app controller
- Main window → Result card: instantiates · Creates a result card for each processed file
- Result card → File processor: backed by · Card behavior is implemented by the per-file processor
- App controller → Runtime cache: manages · Creates and uses local cache and temp folders
- App controller → LibreOffice: downloads · Bootstraps LibreOffice for XHTML generation
- App controller → Pandoc: downloads · Bootstraps Pandoc for XML generation
- App controller → 7-Zip: extracts with · Uses 7-Zip on Windows for archive extraction
- App controller → Tar tool: extracts with · Uses tar-based extraction on Linux
- App controller → File processor: dispatches · Hands off each dropped DOCX to a file-level processor
- File processor → Format rules: classifies · Determines LTE or UMTS rules from the filename
- File processor → Integrity checks: validates · Performs report integrity checks on generated XHTML/XML
- Integrity checks → Media audit: includes · Runs media completeness and broken-image checks
- File processor → XML plugin: parses with · Uses the XML plugin to inspect XHTML/XML structure
- File processor → Browser view: opens · Launches generated XHTML in the browser for review
- App controller → Site container: hosts · Composes the interface from reusable scene containers
- Site container → Site script: logic · Container scene behavior is implemented by its script
- Main window → Button style: styles · Applies shared UI theme resources
- App controller → Python converter: adjacent · Repository also contains a separate Python converter subproject