# teler-sh/teler architecture

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

- Interactive diagram: https://gitdiagram.com/teler-sh/teler
- Repository: https://github.com/teler-sh/teler

## Overview

##### Project Type & Purpose
- teler IDS is a real‐time intrusion detection system focused on analyzing web logs and alerting on potential security threats.
- It is designed as a CLI tool (with a terminal interface) that provides real-time alerting, monitoring, and logging capabilities. It can also be integrated with dashboards and external alerting services (Slack, Mattermost, Telegram, Discord).
- The README confirms its role as a threat analyzer, and it shows that even though version 3 is in the roadmap (with eBPF and teler-waf integration), the current version (v2) is primarily CLI based with support for incremental log processing.

##### Analyzing the File Structure – Key Components
- Top-Level Indicators: The presence of directories such as “internal”, “pkg”, and “common” shows modular design by functionality.
- Main entry point: main.go – this is the starting point for the application.
- Core Modules (inside the “internal” directory):
– internal/alert: Contains different alerting implementations (e.g., Slack, Discord, Mattermost, Telegram) plus templating and utilities.
– internal/event: Handles event processing; includes both event logic and a “www” subdirectory that seems to serve a dashboard (HTML/JS/CSS) for visualization.
– internal/runner: Manages the core logic for real-time log scanning, connection handling, endpoint management, logs collection, metrics, caching, options handling, and versioning.
- Packages (inside “pkg”):
– pkg/cache, pkg/errors, pkg/logs, pkg/matchers, pkg/metrics, pkg/parsers, pkg/requests, pkg/teler, and pkg/utils: These provide the low-level functionalities utilized by the core modules. They support error handling, matching patterns within logs, configuring parsers, collecting metrics (Prometheus integration), and external HTTP requests.
- Configuration & Resources:
– Files like teler.example.yaml and various configuration examples (e.g., fail2ban configuration) indicate that the system is highly configurable.
– There’s also a “resource” directory containing configuration code.
- Support for Deployment & CI/CD:
– Dockerfile, Makefile, GitHub workflows, and other scripts show that the project maintains structured deployment and CI/CD practices.

a. Main Application (main.go)
– Acts as the orchestrator kicking off all other modules.
b. Runner Module (internal/runner)
– This is the core processing engine: receiving log inputs, validating and parsing them, maintaining connection endpoints, caching, and handling metrics.
c. Alerting Module (internal/alert)
– Works in response to threat detection from the Runner.
– Display branches or sub-components for different alert channel integrations (Slack, Discord, Telegram, Mattermost).
– Indicate bi-directional interactions with the Runner (e.g., sending alerts and receiving configuration parameters).
d. Event Processing Module (internal/event)
– Captures and processes web events; has a static web dashboard as shown in the “internal/event/www” subdirectory.
– Its output can be considered the monitoring visual interface.
e. Utility and Support Libraries (pkg)
– These form the backbone for configuration parsing, error handling, metrics collection (Prometheus) and caching.
– Group these into a “Support Services” or “Infrastructure” block.
f. External Dependencies:
– External monitoring systems like Prometheus (via pkg/metrics) and Zinc logs (via pkg/logs) should also be shown.
– Optionally, include integration options with teler-waf and other security components as noted in the README.
g. Configuration & Resource Loader:
– The project’s configuration (examples like teler.example.yaml) should be shown as an input feeding into multiple modules (runner, alert, etc.).

##### Architectural Design Patterns & Principles
- Modular Design: Separate concerns are split logically (alerting, event processing, log parsing) across different directories.
- Config-Driven Behavior: Use of YAML example and config files denote a high level of customization.
- Real-Time Processing: Emphasis on incremental log processing and immediate alerting.
- Layered Architecture: Higher-level orchestration in main.go, core logic in runner, and support libraries below.
- Integration Points: Clear external interfaces for alerting and monitoring.

- Main blocks: Core System (main.go & Runner), Alerting System, Event Processing/Dashboard, Utility/Support Services.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    subgraph "Core Components"
        A["Main Application (main.go)"]
        B["Runner Module (internal/runner)"]
        C["Alerting Module (internal/alert)"]
        D["Event Processing Module (internal/event)"]
        E["Dashboard (internal/event/www)"]
    end

    %% Support & Config
    subgraph "Support & Config"
        F["Support Libraries (pkg)"]
        G["Configuration Loader (teler.example.yaml & resource)"]
    end

    %% External Services
    subgraph "External Services"
        H["Slack"]
        I["Discord"]
        J["Telegram"]
        K["Mattermost"]
        L["Prometheus"]
        M["Zinc Logs"]
    end

    %% Connections between Core Components
    A -->|"orchestrates"| B
    B -->|"processes_logs"| D
    D -->|"visualizes"| E

    %% Interactions with Alerting Module
    B -->|"sends_alert"| C
    C -->|"acknowledges"| B

    %% Configuration inputs
    G -->|"configures"| B
    G -->|"configures"| C

    %% Support Libraries connections
    F -->|"supports"| B
    F -->|"supports"| C
    F -->|"metrics"| L
    F -->|"logs"| M

    %% External Alerting Services from Alerting Module
    C -->|"alerts_to"| H
    C -->|"alerts_to"| I
    C -->|"alerts_to"| J
    C -->|"alerts_to"| K

    %% Click Events
    click A "https://github.com/teler-sh/teler/blob/v2/main.go"
    click B "https://github.com/teler-sh/teler/tree/v2/internal/runner/"
    click C "https://github.com/teler-sh/teler/tree/v2/internal/alert/"
    click D "https://github.com/teler-sh/teler/tree/v2/internal/event/"
    click E "https://github.com/teler-sh/teler/tree/v2/internal/event/www/"
    click F "https://github.com/teler-sh/teler/tree/v2/pkg/"
    click G "https://github.com/teler-sh/teler/blob/v2/teler.example.yaml"
    click G "https://github.com/teler-sh/teler/tree/v2/resource/"

    %% Class Styles
    class A,B,C,D,E core
    class F,G support
    class H,I,J,K,L,M external

    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef support fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#fbf,stroke:#333,stroke-width:2px;
```
