# starfysh-tech/appletscriptorium architecture

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

- Interactive diagram: https://gitdiagram.com/starfysh-tech/appletscriptorium
- Repository: https://github.com/starfysh-tech/appletscriptorium

## Overview

##### Project Type and Purpose
- AppletScriptorium is a collection of local macOS automation tools.
- It contains two standalone sub‐systems:
a. Summarizer – a full pipeline “intelligence digest generator” that processes Google Alert emails, fetches and cleans article content, uses a local LLM to summarize, and delivers a digest via SMTP.
b. ExtensionAuditor – a command-line Chrome extension security scanner that analyzes installed extensions and produces vulnerability reports.

##### File Structure Analysis
- Top-level:
- install scripts: install.sh, setup-mail-rule.sh, run_workflow.sh
- Summarizer/: Python package with modules, CLI entry point, templates, tests, sample fixtures, deployment scripts, requirements
- ExtensionAuditor/: standalone Python script + README
- Configuration templates: .env.template, Summarizer/templates
- Summarizer directory follows a modular pipeline pattern (extraction → fetching → cleaning → summarization → rendering → delivery), with both event-driven (AppleScript Mail rule) and scheduled (cron or shell) triggers.
- Key external integrations: Mail.app via AppleScript, SMTP service, local LLM backends (LM Studio, optional Ollama), url-to-md CLI, Jina Reader API.

##### Key README Insights
- Summarizer supports two invocation modes: Mail rule event and CLI/cron.
- Config driven by config.py and environment variables in .env.

a. Main Components
- Mail.app with Mail Rule
- AppleScript “process-alert.scpt”
- Summarizer CLI orchestration (cli.py)
- LinkExtractor (link_extractor.py)
- ArticleFetchers (urltomd_fetcher, jana_fetcher, article_fetcher)
- ContentCleaner + MarkdownCleanup
- Summarizer (LLM interface)
- DigestRenderer
- SMTP Server (external)
- Supporting scripts: run_workflow.sh, bin/run_alert.sh, cron job
- Optional extension: ExtensionAuditor tool
b. Relationships and Data Flow
1. Mail.app receives Google Alert → Mail rule triggers AppleScript
2. AppleScript invokes Summarizer CLI (or run_workflow.sh)
3. CLI calls link_extractor → yields URLs
4. Parallel fetch via article_fetcher / url-to-md / Jina fallback
5. Raw HTML → content_cleaner → markdown_cleanup
6. Markdown → summarizer module (local LLM backend)
7. Summaries → digest_renderer → HTML/text digest
8. SMTP module sends digest to recipients
9. Logs and output files written to runs/<timestamp>/
c. Architectural Patterns and Principles
- Pipeline pattern with clearly separated stages (extract, fetch, clean, summarize, render, deliver)
- Modular design: each stage is a distinct Python module
- Configurable backends via environment variables / config.py
- Event-driven vs scheduled invocation paths
- ThreadPoolExecutor for I/O-bound fetching; sequential summarization to throttle LLM
d. Technologies and Frameworks
- AppleScript (process-alert.scpt, fetch-alert-source.applescript)
- Python 3 modules and CLI (click or argparse patterns)
- Local LLM backends: LM Studio REST API, optional Ollama fallback
- url-to-markdown CLI, Jina Reader API
- SMTP libraries (smtplib)
- Pytest for testing pipeline modules

##### Essential Details to Capture
- Distinct invocation paths (AppleScript vs cron vs manual CLI).
- Parallel vs sequential stages.
- Environment configuration points (.env, config.py).
- LLM backend failover logic (LM Studio → Ollama → Jina).
- Output artifacts and logging directory structure.
- Separation between Summarizer and ExtensionAuditor subsystems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Triggers"
        MailApp["Mail.app"]:::triggers
        Cron["Cron / Manual CLI"]:::triggers
    end

    subgraph "Invocation & Orchestration"
        AScript["process-alert.scpt"]:::triggers
        FetchAScript["fetch-alert-source.applescript"]:::triggers
        SetupRule["setup-mail-rule.sh"]:::processing
        RunWorkflow["run_workflow.sh"]:::processing
        RunAlert["run_alert.sh"]:::processing
        CLI["cli.py"]:::processing
    end

    subgraph "Configuration"
        Config["config.py / .env"]:::config
    end

    subgraph "Summarizer Pipeline"
        LinkExt["link_extractor.py"]:::processing
        subgraph "Fetch Stage"
            FetchGen["article_fetcher.py"]:::processing
            FetchMD["urltomd_fetcher.py"]:::processing
            FetchJina["jina_fetcher.py"]:::processing
        end
        Clean["content_cleaner.py"]:::processing
        MDClean["markdown_cleanup.py"]:::processing
        SumML["summarizer.py"]:::processing
        Render["digest_renderer.py"]:::processing
    end

    SMTP["SMTP Server"]:::external
    Storage["runs/<timestamp>/"]:::storage

    subgraph "ExtensionAuditor"
        EA["extension-auditor.py"]:::processing
        EAReadme["README.md"]:::config
    end

    %% Connections
    MailApp -->|"trigger"| AScript
    SetupRule -->|"install rule"| AScript
    AScript -->|"invoke"| CLI
    FetchAScript -.-> AScript
    Cron -->|"schedule"| RunWorkflow
    RunWorkflow --> CLI
    RunAlert --> CLI
    CLI -->|"load config"| Config
    CLI -->|"start pipeline"| LinkExt
    LinkExt -->|"URLs"| FetchGen
    LinkExt -->|"URLs"| FetchMD
    LinkExt -->|"URLs"| FetchJina
    FetchGen -->|"HTML content"| Clean
    FetchMD -->|"HTML content"| Clean
    FetchJina -->|"HTML content"| Clean
    Clean -->|"cleaned markdown"| MDClean
    MDClean -->|"markdown"| SumML
    SumML -->|"summaries"| Render
    Render -->|"digest"| SMTP
    Render -->|"save output"| Storage
    CLI -->|"log to"| Storage

    EA -->|"analyze extensions"| EAReadme
    EA -->|"report"| Storage

    %% Click Events
    click AScript "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/templates/process-alert.scpt"
    click FetchAScript "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/fetch-alert-source.applescript"
    click CLI "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/cli.py"
    click LinkExt "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/link_extractor.py"
    click FetchGen "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/article_fetcher.py"
    click FetchMD "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/urltomd_fetcher.py"
    click FetchJina "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/jina_fetcher.py"
    click Clean "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/content_cleaner.py"
    click MDClean "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/markdown_cleanup.py"
    click SumML "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/summarizer.py"
    click Render "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/digest_renderer.py"
    click Config "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/config.py"
    click SetupRule "https://github.com/starfysh-tech/appletscriptorium/blob/main/setup-mail-rule.sh"
    click RunWorkflow "https://github.com/starfysh-tech/appletscriptorium/blob/main/run_workflow.sh"
    click RunAlert "https://github.com/starfysh-tech/appletscriptorium/blob/main/Summarizer/bin/run_alert.sh"
    click EA "https://github.com/starfysh-tech/appletscriptorium/blob/main/ExtensionAuditor/extension-auditor.py"
    click EAReadme "https://github.com/starfysh-tech/appletscriptorium/blob/main/ExtensionAuditor/README.md"

    %% Styles
    classDef triggers fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef processing fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef storage fill:#DCDCDC,stroke:#000,stroke-width:1px
```
