# dogoncouch/logesp architecture

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

- Interactive diagram: https://gitdiagram.com/dogoncouch/logesp
- Repository: https://github.com/dogoncouch/logesp

## Overview

##### Main Components

- Web Frontend & Django Project:
- The primary Django project is located in the LogESP directory, which includes the standard Django files (settings.py, urls.py, views.py, wsgi.py).
- The three major Django apps – SIEM, Risk, and Asset Management (hwam) – provide the core functionalities: SIEM for log event management, risk for risk management, and hwam for asset management.

- Background Daemons:
- The “daemons” directory includes submodules for cleaner, parser, and sentry.
- The parser and sentry daemons are responsible for processing incoming log events and applying rules (including limit and list rules) to generate alerts or events.
- The cleaner daemon likely handles routine maintenance tasks such as purging or archiving logs.

- Configuration & Deployment:
- The “config” folder contains various configuration files for the database (db.conf.example), web servers (nginx configuration, uwsgi parameters), syslog (rsyslog server and client configurations) and parsing (parser.conf.example).
- The use of Makefile, scripts (install.sh, service files) and documentation in the “docs” directory shows that deployment automation and configuration management are key parts of the system.

- External Interfaces and Infrastructure:
- NGINX, uWSGI, and rsyslog configurations indicate that LogESP is designed to sit behind a web server that uses uWSGI to serve the Django application.
- Log sources send syslog messages to LogESP—handled externally by configured syslog daemons—and these logs are processed by the background daemons.

##### Relationships & Interactions Between Components

- Client – Web Frontend:
- Users interact via browsers that communicate with the Django web interface. The interface (templates, forms) is provided by both the core LogESP project and the individual apps.

- Django Server – Application Logic:
- The Django project (LogESP along with apps: hwam, risk, siem) implements the controller logic and the MVC pattern.
- These apps interact with the underlying database (configured externally) to store and retrieve log events, risk data, and asset information.

- Background Processing:
- The background daemons (cleaner, parser, sentry) run as separate processes. They continuously handle incoming and stored log data, process them (via core logic in their respective packages), and then update the database/application state.

- External Services & Infrastructure:
- NGINX acts as the reverse proxy and load balancer that passes requests to uWSGI, which in turn hands them off to Django.
- rsyslog components (configured in the “config/rsyslog” directory) are responsible for forwarding log data from network sources into LogESP’s processing pipeline.

##### Architectural Patterns & Technologies

- MVC / MVT Pattern:

- Modular Separation:
- Separation between the core web application (Django project and apps) and the independent background daemons.

- Unix Philosophy & Simplicity:
- The overall design emphasizes minimalism and independent components that do one thing (e.g., parsing, cleaning, rule evaluation).

- Deployment & Integration:
- Role of configuration (NGINX, uWSGI, rsyslog) in tying the components together.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Web Browser/Client"]:::frontend
        Nginx["NGINX/uWSGI"]:::infrastructure
        Browser -->|"HTTP"| Nginx
    end

    %% Backend Application Layer
    subgraph "Backend Application Layer"
        DjangoApp["Django Web App (LogESP)"]:::backend
        SIEM["SIEM Module"]:::backend
        Risk["Risk Module"]:::backend
        HWAM["Asset Management (HWAM) Module"]:::backend
        DjangoApp --> SIEM
        DjangoApp --> Risk
        DjangoApp --> HWAM
        DjangoApp -->|"Reads/Writes"| Database
    end

    %% Daemon Services Layer
    subgraph "Daemon Services"
        Cleaner["Cleaner Daemon"]:::daemon
        Parser["Parser Daemon"]:::daemon
        Sentry["Sentry Daemon"]:::daemon
        Syslog["Syslog Source"]:::infrastructure
        Syslog -->|"LogData"| Parser
        Syslog -->|"LogData"| Sentry
        Cleaner -->|"Updates"| Database
        Parser -->|"Updates"| Database
        Sentry -->|"Updates"| Database
    end

    %% Infrastructure & Configuration Layer
    subgraph "Infrastructure & Configuration"
        Config["Configuration Files"]:::config
        Config -->|"Configures"| Nginx
        Config -->|"Configures"| DjangoApp
        Config -->|"Configures"| Cleaner
        Config -->|"Configures"| Parser
        Config -->|"Configures"| Sentry
    end

    %% Shared Database Component
    Database["Database"]:::database

    %% Click Events
    click DjangoApp "https://github.com/dogoncouch/logesp/tree/master/LogESP/"
    click SIEM "https://github.com/dogoncouch/logesp/tree/master/siem/"
    click Risk "https://github.com/dogoncouch/logesp/tree/master/risk/"
    click HWAM "https://github.com/dogoncouch/logesp/tree/master/hwam/"
    click Cleaner "https://github.com/dogoncouch/logesp/tree/master/daemons/cleaner/"
    click Parser "https://github.com/dogoncouch/logesp/tree/master/daemons/parser/"
    click Sentry "https://github.com/dogoncouch/logesp/tree/master/daemons/sentry/"
    click Config "https://github.com/dogoncouch/logesp/tree/master/config/"

    %% Styles
    classDef frontend fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef daemon fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef infrastructure fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef database fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
