# cata-af/scandoc architecture

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

- Interactive diagram: https://gitdiagram.com/cata-af/scandoc
- Repository: https://github.com/cata-af/scandoc

## Overview

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: [`scripts/ICMain.gd`](https://github.com/cata-af/scandoc/blob/main/scripts/ICMain.gd) (App controller), [`scripts/ICProcessedFile.gd`](https://github.com/cata-af/scandoc/blob/main/scripts/ICProcessedFile.gd) (File processor), [`main.tscn`](https://github.com/cata-af/scandoc/blob/main/main.tscn) (Main window), [`scenes/processed_file.tscn`](https://github.com/cata-af/scandoc/blob/main/scenes/processed_file.tscn) (Result card)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Godot app"]
  node_node_main_scene["Main window<br/>scene<br/>[main.tscn]"]
  node_node_icmain["App controller<br/>orchestrator<br/>[ICMain.gd]"]
  node_node_processed_scene["Result card<br/>scene"]
  node_node_browser["Browser view<br/>output"]
  node_node_site_container["Site container<br/>ui component"]
  node_node_site_script["Site script<br/>ui logic<br/>[ICSiteContainer.gd]"]
  node_node_theme["Button style<br/>theme"]
end

subgraph group_group_analysis["Document analysis"]
  node_node_icprocessed["File processor<br/>[ICProcessedFile.gd]"]
  node_node_formats["Format rules<br/>[ICFormats.gd]"]
  node_node_xhtml_checks{{"Integrity checks<br/>analysis"}}
  node_node_media{{"Media audit<br/>analysis"}}
  node_node_xml_plugin["XML plugin<br/>[xml.gd]"]
end

subgraph group_group_external["External tools"]
  node_node_lo[("LibreOffice<br/>external converter")]
  node_node_pandoc[("Pandoc<br/>external converter")]
  node_node_7z["7-Zip<br/>extractor"]
  node_node_tar["Tar tool<br/>extractor"]
  node_node_runtime[("Runtime cache<br/>filesystem")]
end

subgraph group_group_aux["Auxiliary subproject"]
  node_node_converter_py["Python converter<br/>subproject<br/>[main.py]"]
end

node_node_main_scene -->|"runs"| node_node_icmain
node_node_main_scene -->|"instantiates"| node_node_processed_scene
node_node_processed_scene -->|"backed by"| node_node_icprocessed
node_node_icmain -->|"manages"| node_node_runtime
node_node_icmain -->|"downloads"| node_node_lo
node_node_icmain -->|"downloads"| node_node_pandoc
node_node_icmain -->|"extracts with"| node_node_7z
node_node_icmain -->|"extracts with"| node_node_tar
node_node_icmain -->|"dispatches"| node_node_icprocessed
node_node_icprocessed -->|"classifies"| node_node_formats
node_node_icprocessed -->|"validates"| node_node_xhtml_checks
node_node_xhtml_checks -->|"includes"| node_node_media
node_node_icprocessed -->|"parses with"| node_node_xml_plugin
node_node_icprocessed -->|"opens"| node_node_browser
node_node_icmain -->|"hosts"| node_node_site_container
node_node_site_container -->|"logic"| node_node_site_script
node_node_main_scene -->|"styles"| node_node_theme
node_node_icmain -.->|"adjacent"| node_node_converter_py

click node_node_main_scene "https://github.com/cata-af/scandoc/blob/main/main.tscn"
click node_node_icmain "https://github.com/cata-af/scandoc/blob/main/scripts/ICMain.gd"
click node_node_processed_scene "https://github.com/cata-af/scandoc/blob/main/scenes/processed_file.tscn"
click node_node_icprocessed "https://github.com/cata-af/scandoc/blob/main/scripts/ICProcessedFile.gd"
click node_node_formats "https://github.com/cata-af/scandoc/blob/main/scripts/ICFormats.gd"
click node_node_xml_plugin "https://github.com/cata-af/scandoc/blob/main/addons/godot_xml/xml.gd"
click node_node_converter_py "https://github.com/cata-af/scandoc/blob/main/docx_to_html_converter/main.py"
click node_node_site_container "https://github.com/cata-af/scandoc/blob/main/scenes/site_container.tscn"
click node_node_site_script "https://github.com/cata-af/scandoc/blob/main/scenes/ICSiteContainer.gd"
click node_node_theme "https://github.com/cata-af/scandoc/blob/main/styles/button_outline.tres"

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_node_main_scene,node_node_icmain,node_node_processed_scene,node_node_browser,node_node_site_container,node_node_site_script,node_node_theme toneBlue
class node_node_icprocessed,node_node_formats,node_node_xhtml_checks,node_node_media,node_node_xml_plugin toneAmber
class node_node_lo,node_node_pandoc,node_node_7z,node_node_tar,node_node_runtime toneMint
class node_node_converter_py toneRose
```

## Components

### Godot app

Desktop UI shell and scene runtime

- [Main window](https://github.com/cata-af/scandoc/blob/main/main.tscn): scene · Top-level Godot interface with dependency panel, input list, and results area · `main.tscn`
- [App controller](https://github.com/cata-af/scandoc/blob/main/scripts/ICMain.gd): orchestrator · Central runtime controller for drag-and-drop, dependency bootstrap, job execution, and shutdown · `scripts/ICMain.gd`
- [Result card](https://github.com/cata-af/scandoc/blob/main/scenes/processed_file.tscn): scene · Reusable collapsible card for one processed document · `scenes/processed_file.tscn`
- **Browser view**: output · Opens generated XHTML for inspection
- [Site container](https://github.com/cata-af/scandoc/blob/main/scenes/site_container.tscn): ui component · Reusable scene/container used by the interface · `scenes/site_container.tscn`
- [Site script](https://github.com/cata-af/scandoc/blob/main/scenes/ICSiteContainer.gd): ui logic · Script behind the site container UI component · `scenes/ICSiteContainer.gd`
- [Button style](https://github.com/cata-af/scandoc/blob/main/styles/button_outline.tres): theme · UI styling resource used by the Godot interface · `styles/button_outline.tres`

### Document analysis

Per-file conversion, XHTML mutation, and integrity checks

- [File processor](https://github.com/cata-af/scandoc/blob/main/scripts/ICProcessedFile.gd): processor · Per-document conversion, validation, XHTML mutation, and UI population · `scripts/ICProcessedFile.gd`
- [Format rules](https://github.com/cata-af/scandoc/blob/main/scripts/ICFormats.gd): rules · Filename-driven document type detection and report-specific validation rules · `scripts/ICFormats.gd`
- **Integrity checks**: analysis · KPI validation, media counting, broken image detection, and integrity comments injection
- **Media audit**: analysis · Scans embedded images and compares declared figures with actual media presence
- [XML plugin](https://github.com/cata-af/scandoc/blob/main/addons/godot_xml/xml.gd): library · Godot XML parsing and traversal support for XHTML/XML content · `addons/godot_xml/xml.gd`

### External tools

Downloaded converters and runtime dependencies

- **LibreOffice**: external converter · Downloaded portable dependency used to generate XHTML
- **Pandoc**: external converter · Downloaded dependency used to generate XML
- **7-Zip**: extractor · Windows extraction dependency for bundled downloads
- **Tar tool**: extractor · Linux extraction path for downloaded archives
- **Runtime cache**: filesystem · Local bin and temp folders used for cached dependencies and conversion outputs

### Auxiliary subproject

Separate Python-based converter code

- [Python converter](https://github.com/cata-af/scandoc/blob/main/docx_to_html_converter/main.py): subproject · Separate docx_to_html_converter project included in the repo · `docx_to_html_converter/main.py`

## Connections

- 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
