# scs-labrat/neophreak architecture

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

- Interactive diagram: https://gitdiagram.com/scs-labrat/neophreak
- Repository: https://github.com/scs-labrat/neophreak

## Overview

##### Main Components
- Frontend Web Client: Represented by the HTML templates in the “templates” folder and the static assets (JavaScript, CSS from “static”). This component provides the user interface, including the live output terminal, control panel, forms for entering testing configurations, and the geolocation map (using Leaflet.js).
- Backend Application Server: The “app.py” file serves as the entry point of the backend logic. It orchestrates incoming HTTP requests and integrates with various functional modules such as:
- Protocol Testing Modules: Files like “telcotool.py”, “telco_finder.py”, and “sccp_custom.py” suggest dedicated logic for different telecommunications protocols.
- Live Output/Results Manager: Modules write logs and testing results to the “results” directory (which stores CSV files). This part handles parsing results, possibly formatting them for export.
- Dependency & API Integration: Includes functionality for dependency checks and querying external services (like Shodan’s API) as explained in the README.
- External Services and Tool Integrations:
- Shodan API: For additional reconnaissance data.
- Geolocation Mapping: Using Leaflet.js on the frontend to map discovered IPs.
- Configuration Management: Environment variables managed via a “.env” file, which sets critical runtime parameters (host, port, debug setting, API keys).

##### Relationships and Interactions
- The Frontend (browser) communicates with the backend via HTTP requests. Actions like starting a scan, stopping it, or exporting results trigger specific endpoints in “app.py”.
- The backend distributes tasks to specialized modules (protocol testers, target discoverer, results parser) and aggregates responses.
- Data Flow: Data flows from the user (configuration inputs) → backend processing → interactions with external APIs (Shodan) → results storage (CSV files) and live output to the UI.
- The control panel’s commands (start/stop scan, dependency checks) and real-time logs are piped through the backend to the frontend’s live output terminal.

##### Architectural Patterns & Design Principles
- Layered/MVC-like Pattern: Separation between the “view” (HTML, CSS, JavaScript) and business logic (Python modules) is maintained.
- Modular Design: Different scripts (telco_finder.py, telcotool.py, sccp_custom.py) point to a modular architecture where each module is responsible for a distinct protocol or testing functionality.
- External Integration: Clearly isolated integration points (e.g., Shodan API and geolocation mapping) which can be independently updated or replaced.

##### Technologies and Frameworks
- Python (with Flask or a similar lightweight web framework)
- HTML, CSS, JavaScript (with Bootstrap, Leaflet.js)
- CSV handling (for exporting and parsing testing results)
- Environment configuration through a .env file for runtime settings.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Layer"
        FE["Frontend Web Client (UI: Control Panel, Live Terminal, Geolocation Map)"]:::frontend
    end

    subgraph "Backend Layer"
        BS["Backend Application Server"]:::backend
        subgraph "Protocol Testing Modules"
            TF["Telco Finder"]:::protocol
            TT["Telcotool"]:::protocol
            SC["SCCP Module"]:::protocol
        end
        RM["Results Manager"]:::backend
    end

    subgraph "External Integrations"
        SA["Shodan API"]:::external
        GM["Geolocation Mapping (Leaflet.js)"]:::external
    end

    FE -->|"HTTP_Request"| BS
    BS -->|"Initiate_Scan"| TF
    BS -->|"Initiate_Scan"| TT
    BS -->|"Initiate_Scan"| SC
    TF -->|"Return_Results"| BS
    TT -->|"Return_Results"| BS
    SC -->|"Return_Results"| BS
    BS -->|"Store_Parse_Logs"| RM
    BS -->|"API_Call"| SA
    BS -->|"Send_GeoData"| GM
    RM -->|"Live_Output"| FE

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef protocol fill:#90EE90,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;

    click FE "https://github.com/scs-labrat/neophreak/tree/main/templates/"
    click FE "https://github.com/scs-labrat/neophreak/tree/main/static/"
    click BS "https://github.com/scs-labrat/neophreak/blob/main/app.py"
    click TF "https://github.com/scs-labrat/neophreak/blob/main/telco_finder.py"
    click TT "https://github.com/scs-labrat/neophreak/blob/main/telcotool.py"
    click SC "https://github.com/scs-labrat/neophreak/blob/main/sccp_custom.py"
    click RM "https://github.com/scs-labrat/neophreak/tree/main/results/"
```
