# ravenred/plopper architecture

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

- Interactive diagram: https://gitdiagram.com/ravenred/plopper
- Repository: https://github.com/ravenred/plopper

## Overview

##### Project type and purpose
- This is a small full-stack Python web application whose sole purpose is to parse SNORT alert logs (a file on disk) and present interactive visualizations of that data in a browser.

##### File structure
- Top-level files:
- main.py – CLI entry point that takes “alert.fast” path, calls into parsing and visualization, then spins up the web server.
- snort_parser.py – contains logic to read/parse SNORT alerts into in-memory data structures.
- visualizer.py – prepares chart data (e.g. Plotly/Matplotlib or JSON) from the parsed alerts.
- app.py – defines the HTTP server (likely Flask or similar), routes, and renders HTML/JS pages.
- requirements.txt – lists Python dependencies (e.g. Flask, charting libs).
- No separate “frontend” directory implies templates/static assets are embedded under a default folder (e.g. Flask’s templates/ and static/) or generated dynamically.

##### README for additional insights
- The README confirms: “Parses SNORT logs & visualizes them on a web page.”
- There is a single run command: `python main.py "file/location/alert.fast"` which launches the end-to-end pipeline.

##### Main components & interactions
a. Components:
1. CLI Entrypoint (main.py)
2. Parser Module (snort_parser.py)
3. Visualization Module (visualizer.py)
4. Web Server (app.py – Flask)
5. Browser Client (user’s web browser)
6. File System (input log file)
b. Relationships & dataflow:
- User invokes main.py with path to SNORT log →
- main.py calls snort_parser.parse() → returns structured data →
- main.py passes data to visualizer.build_charts() → returns chart definitions/JSON →
- main.py / app.py injects those charts into HTML templates →
- Flask HTTP server serves endpoint(s) →
- Browser client requests page, receives HTML+JS assets with embedded chart data →
- Browser renders interactive dashboards.
c. Architectural pattern:
- A simple layered/monolithic architecture:
- Layer 1 (Data): File I/O & parsing
- Layer 2 (Business Logic): Data transformation & chart prep
- Layer 3 (Presentation): HTTP server + HTML/JS frontend
d. Key technologies:
- Python 3.x, Flask or micro-framework (app.py)
- Charting library (Plotly, Matplotlib, etc.) in visualizer.py
- SNORT alert parsing logic in snort_parser.py
- Standard HTML/CSS/JS in templates or generated on the fly

##### What
- “CLI Entrypoint (main.py)”
- “Parser Module”
- “Visualization Module”
- “Web Server (Flask app.py)”
- “Browser Client”
- “File System (SNORT log file)”
- From File System → Parser → Visualizer → Web Server → Browser
- Compute modules (Parser, Visualizer, Entrypoint) as rectangles.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Source
    FS["SNORT Log File"]:::datasource

    %% Compute Modules
    CLI["CLI Entrypoint\n(main.py)"]:::compute
    Parser["Parser Module\n(snort_parser.py)"]:::compute
    Visualizer["Visualization Module\n(visualizer.py)"]:::compute

    %% Presentation Layer
    subgraph "Monolithic Backend"
        WebServer["Web Server\n(app.py)"]:::presentation
    end

    Browser["Browser Client"]:::external

    %% Data Flow
    FS -->|"raw alerts"| CLI
    CLI -->|"calls parse()"| Parser
    Parser -->|"parsed records"| CLI
    CLI -->|"calls build_charts()"| Visualizer
    Visualizer -->|"chart JSON"| CLI
    CLI -->|"injects charts"| WebServer
    WebServer -->|HTTP| Browser
    Browser -->|renders HTML/JS| Browser

    %% Click Events
    click CLI "https://github.com/ravenred/plopper/blob/master/main.py"
    click Parser "https://github.com/ravenred/plopper/blob/master/snort_parser.py"
    click Visualizer "https://github.com/ravenred/plopper/blob/master/visualizer.py"
    click WebServer "https://github.com/ravenred/plopper/blob/master/app.py"

    %% Styles
    classDef datasource fill:#ccf,stroke:#333,stroke-width:1px;
    classDef compute fill:#ffc,stroke:#333,stroke-width:1px;
    classDef presentation fill:#cfc,stroke:#333,stroke-width:1px;
    classDef external fill:#eee,stroke:#333,stroke-width:1px;
```
