# clemcer/loggifly architecture

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

- Interactive diagram: https://gitdiagram.com/clemcer/loggifly
- Repository: https://github.com/clemcer/loggifly

## Overview

##### Project type and purpose
- LoggiFly is an open-source, standalone log-monitoring tool written in Python.
- It connects to one or more Docker daemons, watches container logs for keywords or regex patterns, and sends notifications or triggers container actions.

##### File structure
- Top-level files:
- Dockerfile & docker-compose.yaml → container image and orchestration
- config_template.yaml & config_example.yaml → configuration schema
- entrypoint.sh → startup script
- app/ directory:
- app.py → main orchestrator
- load_config.py → reads and watches config.yaml
- docker_monitor.py → connects to Docker API, streams logs, issues restart/stop
- line_processor.py → parses log lines, applies keyword/regex rules
- notifier.py → dispatches notifications via Ntfy, Apprise, webhooks
- requirements.txt → Python dependencies

##### README for additional insights
- Confirms features: multi‐line log detection, automatic config reload, container actions, remote host support, and notification channels.

##### Components
a. Config Layer
- External config.yaml (mounted or via env vars)
- Config Loader (load_config.py)
b. Monitoring Layer
- Docker Monitor (docker_monitor.py)
- Docker Daemon(s) – local socket or remote via DOCKER_HOST (with optional TLS or proxy)
c. Processing Layer
- Line Processor (line_processor.py) – handles multi-line entries, applies per-container and global rules
- Action Trigger → back to Docker Monitor (restart/stop commands)
d. Notification Layer
- Notifier (notifier.py)
- External Services: Ntfy server, Apprise endpoints (Slack, Discord, Telegram…), custom webhooks
e. Orchestration & Deployment
- entrypoint.sh & app.py glue everything
- Dockerfile → image
- docker-compose.yaml → service definition, volume mounts, env vars

##### Relationships and interactions
- Config Loader reads config → passes rules to Docker Monitor & Line Processor
- Docker Monitor opens log streams from Docker Daemon(s) → emits raw log entries
- Line Processor consumes entries → on match:
- invokes Notifier to send alerts
- invokes Action Trigger to restart/stop container via Docker Monitor
- Notifier sends HTTP requests to external notification services

##### Architectural patterns and principles
- Modular pipeline: clear separation of concerns (config, monitoring, processing, notifying)
- Observer pattern: file‐watcher for config reload, log stream watchers
- Plugin-style extensibility: add new notifiers or entry processors

##### Technologies, frameworks, and libraries
- Python 3.x
- Docker Engine API (via docker SDK)
- YAML for configuration
- HTTP clients (requests or similar) for Ntfy/Apprise/webhook
- Docker Compose for deployment, optional Docker Socket Proxy

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration Files"
        CFGT["config_template.yaml"]:::data
        CFGE["config_example.yaml"]:::data
    end

    %% Container Environment
    subgraph "Runtime Container"
        Entrypoint["entrypoint.sh"]:::infra
        App["app.py\n(Main Orchestrator)"]:::internal
        Loader["load_config.py\n(Config Loader)"]:::internal
        Monitor["docker_monitor.py\n(Docker Monitor)"]:::internal
        Processor["line_processor.py\n(Line Processor)"]:::internal
        Notifier["notifier.py\n(Notifier)"]:::internal
    end

    %% Deployment Artifacts
    subgraph "Deployment Artifacts"
        DF["Dockerfile"]:::infra
        DC["docker-compose.yaml"]:::infra
        REQ["requirements.txt"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        DockerDaemon["Docker Daemon\n(local/remote)"]:::external
        NotifServ["Notification Services\n(Ntfy, Apprise, Webhooks)"]:::external
    end

    %% Data Flows
    CFGT -->|"config schema"| Loader
    CFGE -->|"example config"| Loader
    Entrypoint -->|"startup"| App
    App -->|"initialize"| Loader
    App -->|"start"| Monitor
    App -->|"start"| Processor
    App -->|"start"| Notifier
    Loader -->|"reload rules"| Monitor
    Loader -->|"reload rules"| Processor
    Monitor -->|"log stream"| Processor
    Processor -->|"match event"| Notifier
    Processor -->|"trigger action"| Monitor
    Monitor -->|"Docker API calls"| DockerDaemon
    Notifier -->|"HTTP POST"| NotifServ

    %% Click Events
    click Loader "https://github.com/clemcer/loggifly/blob/main/app/load_config.py"
    click CFGT "https://github.com/clemcer/loggifly/blob/main/config_template.yaml"
    click CFGE "https://github.com/clemcer/loggifly/blob/main/config_example.yaml"
    click Monitor "https://github.com/clemcer/loggifly/blob/main/app/docker_monitor.py"
    click Processor "https://github.com/clemcer/loggifly/blob/main/app/line_processor.py"
    click Notifier "https://github.com/clemcer/loggifly/blob/main/app/notifier.py"
    click App "https://github.com/clemcer/loggifly/blob/main/app/app.py"
    click Entrypoint "https://github.com/clemcer/loggifly/blob/main/entrypoint.sh"
    click DF "https://github.com/clemcer/loggifly/tree/main/Dockerfile"
    click DC "https://github.com/clemcer/loggifly/blob/main/docker-compose.yaml"
    click REQ "https://github.com/clemcer/loggifly/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#d1e7dd,stroke:#0f5132,color:#0f5132;
    classDef external fill:#cff4fc,stroke:#055160,color:#055160;
    classDef data fill:#fff3cd,stroke:#664d03,color:#664d03;
    classDef infra fill:#f8d7da,stroke:#842029,color:#842029
```
