# meiersmarkus/dienstplan_excel architecture

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

- Interactive diagram: https://gitdiagram.com/meiersmarkus/dienstplan_excel
- Repository: https://github.com/meiersmarkus/dienstplan_excel

## Overview

##### Project type and purpose
- Key use cases: single‐user calendar update (DienstzuARDZDFBox.py), batch updates (DienstplanStart.py using colleagues.json), logging, timing, email notifications.

##### File structure
- Top‐level scripts:
- DienstzuARDZDFBox.py – CLI interface for one user
- DienstplanStart.py – orchestrator for batch updates
- DienstplanDownload.py, Diensteloeschen.py, GruppeVPA.py – domain logic (download, delete old entries, group handling)
- README.md, requirements.txt, environment.yml – documentation & environment
- Configuration files (external, not in repo):
- config.json – credentials & global paths
- colleagues.json – batch user definitions

##### README for additional insights
- Dependencies: standard logging, requests (or CalDAV client), JSON, email (SMTP).
- Logging uses rotating file handler + console.
- Timer utility wraps major tasks to log durations.
- Command-line flags drive behavior (download, rewrite, notify, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actor
    User(["User"]):::actor

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Single["Single-User CLI\n(DienstzuARDZDFBox.py)"]:::internal
        CLI_Batch["Batch CLI\n(DienstplanStart.py)"]:::internal
    end

    %% Configuration
    ConfigLoader["Configuration Loader\n(config.json, colleagues.json)"]:::config

    %% Orchestration
    Orchestrator["Orchestrator\n(loop through users)"]:::internal

    %% Domain Services
    subgraph "Domain Services"
        CalendarDeleter["Calendar Deleter\n(Diensteloeschen.py)"]:::internal
        CalendarDownloader["Calendar Downloader\n(DienstplanDownload.py)"]:::internal
        GroupProcessor["Group Processor\n(GruppeVPA.py)"]:::internal
    end

    %% Persistence & Storage
    LocalStorage[(Local File System)]:::external
    CalDAVServer[(CalDAV Server)]:::external

    %% External Services
    ARD_API["ARD-ZDF Box API"]:::external
    SMTP_Server["SMTP Mail Server"]:::external

    %% Utilities
    Logger["Logger (RotatingFileHandler)"]:::util
    Timer["Timer/Profiler"]:::util
    EmailNotifier["Email Notifier"]:::util

    %% Documentation
    Documentation["Documentation & Env\n(README.md,\nrequirements.txt,\nenvironment.yml)"]:::internal

    %% Flow
    User -->|invoke single| CLI_Single
    User -->|invoke batch| CLI_Batch

    CLI_Single -->|load config| ConfigLoader
    CLI_Batch -->|load config| ConfigLoader

    CLI_Batch -->|start batch| Orchestrator

    %% Single flow
    CLI_Single -->|direct call| CalendarDownloader
    CalendarDownloader -->|GET calendar| ARD_API
    ARD_API -->|return ICS| CalendarDownloader
    CalendarDownloader -->|write ICS| LocalStorage
    CalendarDownloader -->|POST ICS| CalDAVServer

    %% Batch flow
    Orchestrator -->|if rewrite| CalendarDeleter
    Orchestrator -->|download| CalendarDownloader
    Orchestrator -->|process groups| GroupProcessor

    CalendarDeleter -->|delete entries| CalDAVServer
    GroupProcessor -->|update groups| CalDAVServer

    CalendarDownloader -->|GET calendar| ARD_API
    ARD_API --> CalendarDownloader
    CalendarDownloader --> LocalStorage
    CalendarDownloader --> CalDAVServer

    %% Notifications
    Orchestrator -->|notify| EmailNotifier
    CLI_Single -->|notify| EmailNotifier
    EmailNotifier -->|send email| SMTP_Server

    %% Utilities interactions
    CLI_Single -->|log start/end| Logger
    CLI_Batch -->|log start/end| Logger
    Orchestrator -->|log start/end| Logger
    CalendarDownloader -->|log start/end| Logger
    CalendarDeleter -->|log start/end| Logger
    GroupProcessor -->|log start/end| Logger

    CLI_Single -->|time exec| Timer
    CLI_Batch -->|time exec| Timer
    Orchestrator -->|time exec| Timer
    CalendarDownloader -->|time exec| Timer
    CalendarDeleter -->|time exec| Timer
    GroupProcessor -->|time exec| Timer

    %% Documentation link
    CLI_Single -.-> Documentation
    CLI_Batch -.-> Documentation

    %% Click Events
    click CLI_Single "https://github.com/meiersmarkus/dienstplan_excel/blob/main/DienstzuARDZDFBox.py"
    click CLI_Batch "https://github.com/meiersmarkus/dienstplan_excel/blob/main/DienstplanStart.py"
    click Orchestrator "https://github.com/meiersmarkus/dienstplan_excel/blob/main/DienstplanStart.py"
    click CalendarDownloader "https://github.com/meiersmarkus/dienstplan_excel/blob/main/DienstplanDownload.py"
    click CalendarDeleter "https://github.com/meiersmarkus/dienstplan_excel/blob/main/Diensteloeschen.py"
    click GroupProcessor "https://github.com/meiersmarkus/dienstplan_excel/blob/main/GruppeVPA.py"
    click Documentation "https://github.com/meiersmarkus/dienstplan_excel/blob/main/README.md"

    %% Styles
    classDef internal fill:#ccffcc,stroke:#2d2,stroke-width:1px
    classDef external fill:#cce5ff,stroke:#228,stroke-width:1px
    classDef util fill:#ffe0b2,stroke:#e67e22,stroke-width:1px
    classDef config fill:#ffffcc,stroke:#cc0,stroke-width:1px
    classDef actor fill:#e0e0e0,stroke:#999,stroke-width:1px
```
