# vimarsh244/scanclean architecture

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

- Interactive diagram: https://gitdiagram.com/vimarsh244/scanclean
- Repository: https://github.com/vimarsh244/scanclean

## Overview

ScanClean cleans decoded scanned-page pixels conservatively, preserving text while removing document defects. Its primary workflow is either a Python caller supplying an image or the desktop CLI decoding PDF pages; both invoke the core cleaner, which analyzes and removes defects before returning cleaned pixels and optional audit data. The CLI then writes cleaned PDFs. Documented options include deskewing, text-detector guidance, transparency, bilevel output, and audit overlays. The bundled ONNX detector is documented, but its core integration call is not visible in the partial excerpt; that link is therefore shown as unverified.

Main entry points: [`src/scanclean/core.py`](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py) (Page cleaner), [`src/scanclean/cli.py`](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py) (Desktop CLI), [`src/scanclean/__init__.py`](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/__init__.py) (Python API), [`src/scanclean/models/ppocrv6_tiny_det.onnx`](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/models/ppocrv6_tiny_det.onnx) (ONNX text detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["Desktop CLI<br/>[cli.py]"]
  node_pdf_decode["PDF page decoding<br/>[cli.py]"]
end

subgraph group_processing["Cleaning pipeline"]
  node_cleaner["Page cleaner<br/>[core.py]"]
  node_analysis["Page analysis<br/>[core.py]"]
  node_defect_stages["Defect removal stages<br/>[core.py]"]
  node_text_detector["ONNX text detector"]
end

subgraph group_outputs["Output and review"]
  node_pdf_encode["PDF encoding<br/>[core.py]"]
  node_audit_output["Audit overlay PDF<br/>[cli.py]"]
  node_clean_pdf["Cleaned PDF"]
  node_pixels["Cleaned pixels"]
end

node_python_user(("Python caller"))
node_cli_user(("CLI user"))
node_pdf_input["Input PDFs"]

node_python_user -->|"supplies pixels"| node_api
node_api -->|"calls"| node_cleaner
node_cli_user -->|"runs"| node_cli
node_pdf_input -->|"provides pages"| node_pdf_decode
node_cli -->|"decodes pages"| node_pdf_decode
node_pdf_decode -->|"passes pixels"| node_cleaner
node_cli -->|"cleans pages"| node_cleaner
node_cleaner -->|"analyzes page"| node_analysis
node_analysis -->|"removes defects"| node_defect_stages
node_cleaner -.->|"consults optionally"| node_text_detector
node_cleaner -->|"returns result"| node_pixels
node_cli -->|"writes pages"| node_pdf_encode
node_pdf_encode -->|"produces"| node_clean_pdf
node_cli -->|"writes optionally"| node_audit_output

click node_api "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/__init__.py"
click node_cli "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py"
click node_pdf_decode "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py"
click node_cleaner "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py"
click node_analysis "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py"
click node_defect_stages "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py"
click node_text_detector "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/models/ppocrv6_tiny_det.onnx"
click node_pdf_encode "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py"
click node_audit_output "https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.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_api,node_cli,node_pdf_decode,node_cli_user toneBlue
class node_cleaner,node_analysis,node_defect_stages,node_text_detector toneAmber
class node_pdf_encode,node_audit_output,node_clean_pdf,node_pixels toneMint
class node_python_user,node_pdf_input toneIndigo
```

## Components

### User interfaces

- [Python API](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/__init__.py): `src/scanclean/__init__.py`
- [Desktop CLI](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py): `src/scanclean/cli.py`
- [PDF page decoding](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py): `src/scanclean/cli.py`

### Cleaning pipeline

- [Page cleaner](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py): `src/scanclean/core.py`
- [Page analysis](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py): `src/scanclean/core.py`
- [Defect removal stages](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py): `src/scanclean/core.py`
- [ONNX text detector](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/models/ppocrv6_tiny_det.onnx): `src/scanclean/models/ppocrv6_tiny_det.onnx`

### Output and review

- [PDF encoding](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/core.py): `src/scanclean/core.py`
- [Audit overlay PDF](https://github.com/vimarsh244/scanclean/blob/main/src/scanclean/cli.py): `src/scanclean/cli.py`
- **Cleaned PDF**
- **Cleaned pixels**

### Other components

- **Python caller**
- **CLI user**
- **Input PDFs**

## Connections

- Python caller → Python API: supplies pixels (evidence: `README.md`)
- Python API → Page cleaner: calls (evidence: `src/scanclean/__init__.py`)
- CLI user → Desktop CLI: runs (evidence: `README.md`)
- Input PDFs → PDF page decoding: provides pages (evidence: `src/scanclean/cli.py`)
- Desktop CLI → PDF page decoding: decodes pages (evidence: `src/scanclean/cli.py`)
- PDF page decoding → Page cleaner: passes pixels (evidence: `src/scanclean/cli.py`)
- Desktop CLI → Page cleaner: cleans pages (evidence: `src/scanclean/cli.py`)
- Page cleaner → Page analysis: analyzes page (evidence: `README.md`)
- Page analysis → Defect removal stages: removes defects (evidence: `README.md`)
- Page cleaner → ONNX text detector: consults optionally
- Page cleaner → Cleaned pixels: returns result (evidence: `README.md`)
- Desktop CLI → PDF encoding: writes pages (evidence: `src/scanclean/cli.py`)
- PDF encoding → Cleaned PDF: produces (evidence: `README.md`)
- Desktop CLI → Audit overlay PDF: writes optionally (evidence: `src/scanclean/cli.py`)