# anthirian/script.service.janitor architecture

> Architecture diagram of the GitHub repository anthirian/script.service.janitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthirian/script.service.janitor
- Repository: https://github.com/anthirian/script.service.janitor

## Overview

##### Project type and purpose
- This is a Kodi/XBMC addon written in Python.
- It runs as a background “cleaner” service (service.py) and provides a simple UI (default.py with accompanying XML skin files).
- Its purpose is to scan watched media files on local or network disks, apply user‑configured criteria (age, rating, free disk space, exclusions), delete matching files, and expose a log viewer in Kodi’s interface.

##### File structure
- Top‑level files:
- addon.xml – metadata and entrypoints for Kodi
- default.py – UI entrypoint script (invoked when user opens the addon)
- service.py – background service script (runs on Kodi startup or schedule)
- README, LICENSE, changelog – docs
- resources/
- skins/Default – XML layouts for the log viewer UI and Estuary artwork
- language/…/strings.po – localization files
- settings.xml – addon settings schema
- util/
- addon_info.py – reads metadata from addon.xml
- settings.py – loads and validates user settings
- disk.py – disk‑scanning and free‑space checks
- exclusions.py – resolves user‑configured exclusion patterns
- logging/Janitor & kodi.py – write logs both to file and Kodi’s log API

##### README for additional insights
- Describes configuration options (age, rating, free disk space, exclusions)
- Warns about the destructive power of the addon
- Mentions reuse of Estuary artwork under CC BY‑SA 4.0

a. Main components
- Kodi Host Application
- Addon Container (addon.xml defines two entrypoints)
– Service Module (service.py)
– UI Module (default.py + XML skins)
- Utility Library (util/…)
– Settings Loader
– Disk Scanner
– Exclusion Engine
– Logging Subsystem
- Persistent Storage
– File System(s) (local drives, network shares)
– Kodi’s settings storage (where settings.xml is persisted)
b. Relationships & interactions
– Kodi Host loads the addon at startup → service.py begins scheduled scans
– service.py calls util/settings to fetch user criteria
– service.py invokes util/disk to enumerate media files & check free space
– util/exclusions filters out paths/patterns user has excluded
– service.py deletes files via disk module
– util/logging writes actions to both a log file and Kodi’s log
– User opens the addon in Kodi UI → default.py reads log via util/logging & renders it with XML skins
c. Architectural patterns/design principles
– Plugin architecture: addon entrypoints registered in addon.xml
– Separation of concerns: background service vs. interactive UI vs. pure logic in util modules
– Event/schedule‑based design: service triggers periodically or at startup
– Layered design: UI layer, service layer, utilities layer, filesystem
d. Key technologies/frameworks
– Python 3 with Kodi Addon API
– Kodi’s XML‑based skinning engine
– gettext (.po files) for localization
– Standard filesystem and OS libraries for disk operations

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kodi Host"
        KODI_ADDON["Kodi Addon Container"]:::container
        subgraph "Cleaner Service"
            CLEANER_SERVICE["Cleaner Service (service.py)"]:::active
        end
        subgraph "Log Viewer UI"
            LOG_VIEWER_UI["Log Viewer UI (default.py)"]:::active
            SKIN1["JanitorLogViewer.xml"]:::active
            SKIN2["JanitorSkin.xml"]:::active
        end
    end

    subgraph "Utilities"
        ADDON_INFO["Addon Metadata Reader"]:::util
        SETTINGS_UTIL["Settings Loader & Validator"]:::util
        DISK_UTIL["Disk Scanner & Free-Space Checker"]:::util
        EXCLUSIONS_UTIL["Exclusion Pattern Resolver"]:::util
        LOG_FILE_LOGGER["File Logger"]:::util
        LOG_KODI_ADAPTER["Kodi Log API Adapter"]:::util
    end

    FileSystem[(File System)]:::storage
    SettingsStore[(Settings Store)]:::storage
    LogStore[(Log Store)]:::log

    KODI_ADDON --> CLEANER_SERVICE
    KODI_ADDON --> LOG_VIEWER_UI

    CLEANER_SERVICE --> SETTINGS_UTIL
    CLEANER_SERVICE --> DISK_UTIL
    CLEANER_SERVICE --> EXCLUSIONS_UTIL
    CLEANER_SERVICE --> LOG_FILE_LOGGER
    CLEANER_SERVICE --> LOG_KODI_ADAPTER

    SETTINGS_UTIL --> SettingsStore
    DISK_UTIL --> FileSystem
    LOG_FILE_LOGGER --> LogStore
    LOG_KODI_ADAPTER --> LogStore

    LOG_VIEWER_UI --> LOG_FILE_LOGGER
    LOG_VIEWER_UI --> LogStore
    LOG_VIEWER_UI --> ADDON_INFO
    LOG_VIEWER_UI --> SKIN1
    LOG_VIEWER_UI --> SKIN2

    click KODI_ADDON "https://github.com/anthirian/script.service.janitor/blob/master/addon.xml"
    click CLEANER_SERVICE "https://github.com/anthirian/script.service.janitor/blob/master/service.py"
    click LOG_VIEWER_UI "https://github.com/anthirian/script.service.janitor/blob/master/default.py"
    click SKIN1 "https://github.com/anthirian/script.service.janitor/blob/master/resources/skins/Default/720p/JanitorLogViewer.xml"
    click SKIN2 "https://github.com/anthirian/script.service.janitor/blob/master/resources/skins/Default/JanitorSkin.xml"
    click ADDON_INFO "https://github.com/anthirian/script.service.janitor/blob/master/util/addon_info.py"
    click SETTINGS_UTIL "https://github.com/anthirian/script.service.janitor/blob/master/util/settings.py"
    click DISK_UTIL "https://github.com/anthirian/script.service.janitor/blob/master/util/disk.py"
    click EXCLUSIONS_UTIL "https://github.com/anthirian/script.service.janitor/blob/master/util/exclusions.py"
    click LOG_FILE_LOGGER "https://github.com/anthirian/script.service.janitor/blob/master/util/logging/janitor.py"
    click LOG_KODI_ADAPTER "https://github.com/anthirian/script.service.janitor/blob/master/util/logging/kodi.py"
    click README "https://github.com/anthirian/script.service.janitor/tree/master/README"
    click CHANGELOG "https://github.com/anthirian/script.service.janitor/blob/master/changelog.txt"
    click LICENSE "https://github.com/anthirian/script.service.janitor/blob/master/LICENSE.txt"
    click SETTINGS_SCHEMA "https://github.com/anthirian/script.service.janitor/blob/master/resources/settings.xml"
    click LOCALIZATION "https://github.com/anthirian/script.service.janitor/blob/master/resources/language/*/strings.po"

    classDef active fill:#cce5ff,stroke:#004085,color:#004085
    classDef util fill:#d4edda,stroke:#155724,color:#155724
    classDef storage fill:#fff3cd,stroke:#856404,color:#856404
    classDef log fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef container fill:#f5f5f5,stroke:#333333,color:#333333
```
