# gorkemguler/metacls architecture

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

- Interactive diagram: https://gitdiagram.com/gorkemguler/metacls
- Repository: https://github.com/gorkemguler/metacls

## Overview

MetaCLS is a bulk metadata-scrubbing application for documents and media. Users submit files through the CLI, local web UI, REST API, or desktop drop app; the runtime selects format engines, writes cleaned copies or overwrites in place, rescans for residual metadata, and produces per-file evidence reports. Archive recursion and audio/video handling extend the same engine workflow. The graph reflects documented capabilities, but several subsystem connections rely on README statements or SOURCE INDEX references rather than complete source excerpts.

Main entry points: [`src/metacls/cli.py`](https://github.com/gorkemguler/metacls/blob/main/src/metacls/cli.py) (CLI), [`src/metacls/cleaner.py`](https://github.com/gorkemguler/metacls/blob/main/src/metacls/cleaner.py) (Scrub coordinator), [`src/metacls/engines/__init__.py`](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/__init__.py) (Engine selection), [`src/metacls/web.py`](https://github.com/gorkemguler/metacls/blob/main/src/metacls/web.py) (Local web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Local web UI<br/>[web.py]"]
  node_api["REST API<br/>[app.py]"]
  node_jobs["API job queue<br/>[jobs.py]"]
  node_macdrop["Mac drop app<br/>[desktop_runtime.py]"]
end

subgraph group_workflow["Scrub workflow"]
  node_config["Run configuration<br/>[config.py]"]
  node_scanner["File discovery<br/>[scanner.py]"]
  node_cleaner["Scrub coordinator<br/>[cleaner.py]"]
  node_ftp["FTP source<br/>[ftp_source.py]"]
  node_watch["Folder watcher<br/>[watch.py]"]
end

subgraph group_engines["Format engines"]
  node_registry["Engine selection<br/>[__init__.py]"]
  node_base["Engine contract<br/>[base.py]"]
  node_pdf["PDF scrubber<br/>[pdf.py]"]
  node_office["Office scrubber<br/>[office.py]"]
  node_legacy["Legacy Office<br/>[legacy_office.py]"]
  node_image["Image scrubber<br/>[image.py]"]
  node_exiftool["ExifTool adapter<br/>[exiftool.py]"]
  node_media["Audio/video scrubber<br/>[media.py]"]
  node_ebml["EBML/Riff scrubber<br/>[ebml_riff.py]"]
  node_svg["SVG scrubber<br/>[svg.py]"]
  node_containers["Archive scrubber<br/>[container.py]"]
end

subgraph group_results["Results and state"]
  node_models["Result model<br/>[models.py]"]
  node_report["JSON/HTML reports<br/>[__init__.py]"]
  node_diff["Report comparison<br/>[diff.py]"]
end

node_user(("User"))

node_user -->|"runs command"| node_cli
node_user -->|"uploads files"| node_web
node_user -->|"posts files"| node_api
node_user -->|"drops files"| node_macdrop
node_macdrop -->|"invokes scrub"| node_cli
node_cli -->|"sets options"| node_config
node_cli -->|"discovers files"| node_scanner
node_cli -->|"starts cleaning"| node_cleaner
node_cli -->|"starts watching"| node_watch
node_cli -->|"starts UI"| node_web
node_cli -->|"starts service"| node_api
node_cli -->|"renders report"| node_report
node_cli -->|"compares reports"| node_diff
node_web -->|"cleans uploads"| node_cleaner
node_web -->|"sets options"| node_config
node_web -->|"loads FTP files"| node_ftp
node_web -->|"renders results"| node_report
node_api -->|"submits jobs"| node_jobs
node_api -->|"cleans uploads"| node_cleaner
node_api -->|"sets options"| node_config
node_jobs -->|"packages results"| node_report
node_watch -->|"discovers changes"| node_scanner
node_watch -->|"cleans files"| node_cleaner
node_cleaner -->|"selects engine"| node_registry
node_cleaner -->|"enumerates paths"| node_scanner
node_cleaner -->|"uses options"| node_config
node_cleaner -->|"builds results"| node_models
node_registry -->|"dispatches PDFs"| node_pdf
node_registry -->|"dispatches Office"| node_office
node_registry -->|"dispatches legacy"| node_legacy
node_registry -->|"dispatches images"| node_image
node_registry -->|"dispatches media"| node_media
node_registry -->|"dispatches SVG"| node_svg
node_registry -->|"dispatches archives"| node_containers
node_pdf -->|"implements contract"| node_base
node_office -->|"implements contract"| node_base
node_image -->|"uses adapter"| node_exiftool
node_media -->|"uses adapter"| node_exiftool
node_media -->|"uses parser"| node_ebml
node_cleaner -->|"records outcome"| node_models
node_report -->|"serializes results"| node_models

click node_cli "https://github.com/gorkemguler/metacls/blob/main/src/metacls/cli.py"
click node_web "https://github.com/gorkemguler/metacls/blob/main/src/metacls/web.py"
click node_api "https://github.com/gorkemguler/metacls/blob/main/src/metacls/api/app.py"
click node_jobs "https://github.com/gorkemguler/metacls/blob/main/src/metacls/api/jobs.py"
click node_macdrop "https://github.com/gorkemguler/metacls/blob/main/platform/macos/desktop_runtime.py"
click node_config "https://github.com/gorkemguler/metacls/blob/main/src/metacls/config.py"
click node_scanner "https://github.com/gorkemguler/metacls/blob/main/src/metacls/scanner.py"
click node_cleaner "https://github.com/gorkemguler/metacls/blob/main/src/metacls/cleaner.py"
click node_registry "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/__init__.py"
click node_base "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/base.py"
click node_pdf "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/pdf.py"
click node_office "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/office.py"
click node_legacy "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/legacy_office.py"
click node_image "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/image.py"
click node_exiftool "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/exiftool.py"
click node_media "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/media.py"
click node_ebml "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/ebml_riff.py"
click node_svg "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/svg.py"
click node_containers "https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/container.py"
click node_ftp "https://github.com/gorkemguler/metacls/blob/main/src/metacls/ftp_source.py"
click node_watch "https://github.com/gorkemguler/metacls/blob/main/src/metacls/watch.py"
click node_models "https://github.com/gorkemguler/metacls/blob/main/src/metacls/models.py"
click node_report "https://github.com/gorkemguler/metacls/blob/main/src/metacls/report/__init__.py"
click node_diff "https://github.com/gorkemguler/metacls/blob/main/src/metacls/diff.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_cli,node_web,node_api,node_jobs,node_macdrop,node_user toneBlue
class node_config,node_scanner,node_cleaner,node_ftp,node_watch toneAmber
class node_registry,node_base,node_pdf,node_office,node_legacy,node_image,node_exiftool,node_media,node_ebml,node_svg,node_containers toneMint
class node_models,node_report,node_diff toneRose
```

## Components

### User entry points

- [CLI](https://github.com/gorkemguler/metacls/blob/main/src/metacls/cli.py): `src/metacls/cli.py`
- [Local web UI](https://github.com/gorkemguler/metacls/blob/main/src/metacls/web.py): `src/metacls/web.py`
- [REST API](https://github.com/gorkemguler/metacls/blob/main/src/metacls/api/app.py): `src/metacls/api/app.py`
- [API job queue](https://github.com/gorkemguler/metacls/blob/main/src/metacls/api/jobs.py): `src/metacls/api/jobs.py`
- [Mac drop app](https://github.com/gorkemguler/metacls/blob/main/platform/macos/desktop_runtime.py): `platform/macos/desktop_runtime.py`

### Scrub workflow

- [Run configuration](https://github.com/gorkemguler/metacls/blob/main/src/metacls/config.py): `src/metacls/config.py`
- [File discovery](https://github.com/gorkemguler/metacls/blob/main/src/metacls/scanner.py): `src/metacls/scanner.py`
- [Scrub coordinator](https://github.com/gorkemguler/metacls/blob/main/src/metacls/cleaner.py): `src/metacls/cleaner.py`
- [FTP source](https://github.com/gorkemguler/metacls/blob/main/src/metacls/ftp_source.py): `src/metacls/ftp_source.py`
- [Folder watcher](https://github.com/gorkemguler/metacls/blob/main/src/metacls/watch.py): `src/metacls/watch.py`

### Format engines

- [Engine selection](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/__init__.py): `src/metacls/engines/__init__.py`
- [Engine contract](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/base.py): `src/metacls/engines/base.py`
- [PDF scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/pdf.py): `src/metacls/engines/pdf.py`
- [Office scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/office.py): `src/metacls/engines/office.py`
- [Legacy Office](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/legacy_office.py): `src/metacls/engines/legacy_office.py`
- [Image scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/image.py): `src/metacls/engines/image.py`
- [ExifTool adapter](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/exiftool.py): `src/metacls/engines/exiftool.py`
- [Audio/video scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/media.py): `src/metacls/engines/media.py`
- [EBML/Riff scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/ebml_riff.py): `src/metacls/engines/ebml_riff.py`
- [SVG scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/svg.py): `src/metacls/engines/svg.py`
- [Archive scrubber](https://github.com/gorkemguler/metacls/blob/main/src/metacls/engines/container.py): `src/metacls/engines/container.py`

### Results and state

- [Result model](https://github.com/gorkemguler/metacls/blob/main/src/metacls/models.py): `src/metacls/models.py`
- [JSON/HTML reports](https://github.com/gorkemguler/metacls/blob/main/src/metacls/report/__init__.py): `src/metacls/report/__init__.py`
- [Report comparison](https://github.com/gorkemguler/metacls/blob/main/src/metacls/diff.py): `src/metacls/diff.py`

### Other components

- **User**

## Connections

- User → CLI: runs command (evidence: `README.md`)
- User → Local web UI: uploads files (evidence: `README.md`)
- User → REST API: posts files (evidence: `README.md`)
- User → Mac drop app: drops files (evidence: `README.md`)
- Mac drop app → CLI: invokes scrub (evidence: `platform/macos/desktop_runtime.py`)
- CLI → Run configuration: sets options (evidence: `src/metacls/cli.py`)
- CLI → File discovery: discovers files (evidence: `src/metacls/cli.py`)
- CLI → Scrub coordinator: starts cleaning (evidence: `src/metacls/cli.py`)
- CLI → Folder watcher: starts watching (evidence: `src/metacls/cli.py`)
- CLI → Local web UI: starts UI (evidence: `src/metacls/cli.py`)
- CLI → REST API: starts service (evidence: `src/metacls/cli.py`)
- CLI → JSON/HTML reports: renders report (evidence: `src/metacls/cli.py`)
- CLI → Report comparison: compares reports (evidence: `src/metacls/cli.py`)
- Local web UI → Scrub coordinator: cleans uploads (evidence: `src/metacls/web.py`)
- Local web UI → Run configuration: sets options (evidence: `src/metacls/web.py`)
- Local web UI → FTP source: loads FTP files (evidence: `src/metacls/web.py`)
- Local web UI → JSON/HTML reports: renders results (evidence: `src/metacls/web.py`)
- REST API → API job queue: submits jobs (evidence: `src/metacls/api/app.py`)
- REST API → Scrub coordinator: cleans uploads (evidence: `src/metacls/api/app.py`)
- REST API → Run configuration: sets options (evidence: `src/metacls/api/app.py`)
- API job queue → JSON/HTML reports: packages results (evidence: `src/metacls/api/jobs.py`)
- Folder watcher → File discovery: discovers changes (evidence: `src/metacls/watch.py`)
- Folder watcher → Scrub coordinator: cleans files (evidence: `src/metacls/watch.py`)
- Scrub coordinator → Engine selection: selects engine (evidence: `src/metacls/cleaner.py`)
- Scrub coordinator → File discovery: enumerates paths (evidence: `src/metacls/cleaner.py`)
- Scrub coordinator → Run configuration: uses options (evidence: `src/metacls/cleaner.py`)
- Scrub coordinator → Result model: builds results (evidence: `src/metacls/cleaner.py`)
- Engine selection → PDF scrubber: dispatches PDFs (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → Office scrubber: dispatches Office (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → Legacy Office: dispatches legacy (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → Image scrubber: dispatches images (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → Audio/video scrubber: dispatches media (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → SVG scrubber: dispatches SVG (evidence: `src/metacls/engines/__init__.py`)
- Engine selection → Archive scrubber: dispatches archives (evidence: `src/metacls/engines/__init__.py`)
- PDF scrubber → Engine contract: implements contract (evidence: `src/metacls/engines/base.py`)
- Office scrubber → Engine contract: implements contract (evidence: `src/metacls/engines/base.py`)
- Image scrubber → ExifTool adapter: uses adapter (evidence: `src/metacls/engines/image.py`)
- Audio/video scrubber → ExifTool adapter: uses adapter (evidence: `src/metacls/engines/media.py`)
- Audio/video scrubber → EBML/Riff scrubber: uses parser (evidence: `src/metacls/engines/media.py`)
- Scrub coordinator → Result model: records outcome (evidence: `src/metacls/cleaner.py`)
- JSON/HTML reports → Result model: serializes results (evidence: `src/metacls/report/__init__.py`)
