# anoncatalyst/ominis-osint architecture

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

- Interactive diagram: https://gitdiagram.com/anoncatalyst/ominis-osint
- Repository: https://github.com/anoncatalyst/ominis-osint

## Overview

##### Project’s Purpose and Nature
- The README makes it clear that this is an OSINT “Web Hunter” tool designed to perform digital reconnaissance. It gathers data from search engines, validates proxies, randomizes user agents, and performs username searches over a set of URLs.
- The project is most likely used as both a standalone CLI tool and via dockerized or scripted installations for both Windows and Unix environments.

##### File Structure
- Top-Level Files and Directories:
- The main script “ominis.py” is the central engine.
- “ominis.sh”, “install.sh”, “install.bat”, and installer scripts (setup.py, installer.nsi, setup.iss) indicate cross-platform installation strategies.
- A Dockerfile and GitHub Actions workflows (.github/) show that CI/CD and deployment are also considered.
- The “src” directory:
- Contains supporting modules such as “proxy_handler.py” (for proxy validation using aiohttp), “tools_handler.py”, “usr.py”, and “utils.py”.
- “social_platforms.json” likely contains configuration data for known platform endpoints.
- “urls.txt” contains target URLs for username searches.
- Media files (img directory with images and a video) support documentation or UI aspects.
- Ancillary directories like “Results” suggest output storage for search findings.

##### Main Components
- User Interface / Entry Point:
- “ominis.py” as the starting point where the user initiates a search—this could include a command-line UI or integrated web-based interface in future iterations.
- Core OSINT Engine:
- Modules handling search orchestration, including Google Search Filtering and Username Search.
- Incorporate “tools_handler.py” and “usr.py” as part of the logic that processes and organizes the user inputs and calls to other services.
- Proxy & Network Layer:
- “proxy_handler.py” is distinctly responsible for managing network requests with proxy validation, randomizing user agents, and using asynchronous operations (aiohttp replaces httpx).
- Data and Configuration:
- Data configuration files (“social_platforms.json”, “urls.txt”) form the basis for determining target endpoints and filters to be used during searches.
- Auxiliary/Supporting Modules:
- “utils.py” likely provides helper functions that support threading or repeated operations.
- Continuous Integration/Deployment:
- Dockerfile, GitHub Actions workflows, and installer scripts as part of the deployment/setup component.

##### Relationships and Data Flow
- The Core Engine will call the tools within “src”:
- The engine routes tasks to the Proxy Handler for initiating asynchronous HTTP requests, ensuring anonymity.
- The Engine also engages “tools_handler.py” to manage specific tasks like filtering, threading for the username search, and processing the results.
- Data Flow:
- Configuration data from “urls.txt” and “social_platforms.json” feed into the OSINT Engine.
- Search results and validations are processed through multi-threaded operations (as mentioned in the username search feature) and output to the “Results” directory.
- External Dependencies:
- Outbound web requests to search engines (Google) and other social media platforms are a critical part of the flow.

##### Architectural Patterns and Technologies
- Asynchronous Processing and Threading: Essential for handling multiple web requests concurrently.
- Modular Architecture: Separate concerns into distinct modules (proxy handling, tools, utilities) to ease maintenance and further development.
- Continuous Deployment: Via Dockerfile and GitHub Actions, showcasing an automated build and deployment pipeline.
- Cross-Platform Support: Installer scripts and platform-specific files indicate design for both Windows and Unix-like systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        UI["ominis.py"]:::UI
    end

    %% Core OSINT Engine
    subgraph "Core OSINT Engine"
        TH["tools_handler.py"]:::Core
        USR["usr.py"]:::Core
    end

    %% Proxy & Network Module
    subgraph "Proxy & Network Module"
        PH["proxy_handler.py"]:::Network
    end

    %% Data & Configuration
    subgraph "Data & Configuration"
        SP["social_platforms.json"]:::Data
        URL["urls.txt"]:::Data
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        UTIL["utils.py"]:::Aux
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        DOCK["Dockerfile"]:::CI
        GH[".github/workflows"]:::CI
        ISH["install.sh"]:::CI
        IBAT["install.bat"]:::CI
        SETUPPY["setup.py"]:::CI
        NSI["installer.nsi"]:::CI
        ISS["setup.iss"]:::CI
    end

    %% External Services
    EXT["External_APIs"]:::External

    %% Connections
    UI -->|"initiates"| TH
    UI -->|"initiates"| USR

    TH -->|"calls"| PH
    USR -->|"calls"| PH

    SP -->|"provides"| TH
    URL -->|"provides"| TH
    SP -->|"provides"| USR
    URL -->|"provides"| USR

    TH -->|"uses"| UTIL
    USR -->|"uses"| UTIL

    PH -->|"requests"| EXT

    %% CI/CD integration (Automated Deployments)
    DOCK ---|"builds"| UI
    GH ---|"builds"| UI
    ISH ---|"deploys"| UI
    IBAT ---|"deploys"| UI
    SETUPPY ---|"deploys"| UI
    NSI ---|"deploys"| UI
    ISS ---|"deploys"| UI

    %% Styling
    classDef UI fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef Core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef Network fill:#f94144,stroke:#333,stroke-width:2px;
    classDef Data fill:#577590,stroke:#333,stroke-width:2px;
    classDef Aux fill:#277da1,stroke:#333,stroke-width:2px;
    classDef CI fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef External fill:#f3722c,stroke:#333,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/anoncatalyst/ominis-osint/blob/main/ominis.py"
    click TH "https://github.com/anoncatalyst/ominis-osint/blob/main/src/tools_handler.py"
    click USR "https://github.com/anoncatalyst/ominis-osint/blob/main/src/usr.py"
    click PH "https://github.com/anoncatalyst/ominis-osint/blob/main/src/proxy_handler.py"
    click SP "https://github.com/anoncatalyst/ominis-osint/blob/main/src/social_platforms.json"
    click URL "https://github.com/anoncatalyst/ominis-osint/blob/main/src/urls.txt"
    click UTIL "https://github.com/anoncatalyst/ominis-osint/blob/main/src/utils.py"
    click DOCK "https://github.com/anoncatalyst/ominis-osint/tree/main/Dockerfile"
    click GH "https://github.com/anoncatalyst/ominis-osint/tree/main/.github/workflows"
    click ISH "https://github.com/anoncatalyst/ominis-osint/blob/main/install.sh"
    click IBAT "https://github.com/anoncatalyst/ominis-osint/blob/main/install.bat"
    click SETUPPY "https://github.com/anoncatalyst/ominis-osint/blob/main/setup.py"
    click NSI "https://github.com/anoncatalyst/ominis-osint/blob/main/installer.nsi"
    click ISS "https://github.com/anoncatalyst/ominis-osint/blob/main/setup.iss"
```
