# barkahss/ominis-osint architecture

> Architecture diagram of the GitHub repository barkahss/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/barkahss/ominis-osint
- Repository: https://github.com/barkahss/ominis-osint

## Overview

##### Main Components
- Core Script / Entry Point: The primary executable is “ominis.py” (with “ominis.sh” as a helper for convenience). This serves as the user interface (CLI) that triggers the tool’s operations.
- Modular Logic in “src” Directory:
- config.py: Manages configuration data (e.g., SerpAPI keys and other settings).
- proxy_handler.py: Handles proxy validation and now uses aiohttp for asynchronous web requests.
- serp_search.py: Facilitates Google search operations and integrates with SerpAPI.
- tools_handler.py and usr.py: Orchestrate various OSINT search tasks like username searches over a list of URLs.
- utils.py: Provides commons utilities that support operations across modules.
- Auxiliary Files (social_platforms.json and urls.txt): Supply configuration data such as target social platforms and a list of search URLs.
- Resources:
- img assets and video files (in src/img) illustrate user interface design but might be less critical from an architectural perspective.
- Infrastructure & Automation:
- Dockerfile: Indicates containerization for deployment.
- Multiple GitHub Actions workflows (defined under .github/workflows) that automate tasks like web search, username search, and the overall “Ominis Search” process.
- Installation Scripts:
- The inclusion of install.bat, install.sh, installer.nsi, setup.iss, and setup.py shows support for different operating systems and installation mechanisms.

##### Relationships and Data Flow
- The primary executable (ominis.py) receives user invocation and coordinates the entire workflow.
- It loads configurations from src/config.py and reads input URLs from src/urls.txt.
- The tool then passes data to specialized modules:
- serp_search.py for processing search queries and handling API requests.
- proxy_handler.py to verify and use proxies for executing requests securely.
- usr.py and tools_handler.py to handle username searches across a predefined set of websites (as configured in social_platforms.json).
- The modules use asynchronous calls (via aiohttp) and optimized threading to perform concurrent tasks.
- Processed results are collated and eventually output (detailed results, HTTP status codes) back to the user.

##### Architectural Patterns & Design Principles
- Modular Design: Although it is a single application, the clear subdivision in the “src” folder emphasizes separation of concerns.
- Asynchronous & Concurrent Execution: The use of aiohttp and threading optimization is significant—this should be depicted to show non-blocking IO and parallel searches.
- External Integration: Represent integration with external services like Google Search and SerpAPI, illustrating the exchange of data between the internal modules and these external endpoints.

##### Final Checklist
- Clear labels for each component (e.g., “Core Engine”, “Proxy Module”, “SerpAPI Integration”).
- That any dependencies (like asynchronous operations with aiohttp) are noted next to the corresponding module.
- Annotations that mention the asynchronous/threaded design and container/CI integration aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        U["User / CLI"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        CE["Core Engine (ominis.py)"]:::core
        HS["Helper Script (ominis.sh)"]:::core
    end

    %% Modules
    subgraph "Modules"
        CONF["Configuration Module"]:::module
        PH["Proxy Handler Module (aiohttp)"]:::module
        SS["SerpAPI Search Module"]:::module
        USR["Username Search Module (usr.py & tools_handler.py)"]:::module
        UT["Utilities Module"]:::module
    end

    %% Data & Assets
    subgraph "Data & Assets"
        DS["Data Sources (social_platforms.json, urls.txt)"]:::data
        UI["UI Assets (img)"]:::data
    end

    %% External Services
    subgraph "External Services"
        EX["External Services (Google Search, SerpAPI)"]:::external
    end

    %% Infrastructure & Automation
    subgraph "Infrastructure"
        CONT["Containerization (Dockerfile)"]:::infra
        CICD["CI/CD Automation (GitHub Actions)"]:::infra
        subgraph "Installation Scripts"
            IBAT["install.bat"]:::script
            ISH["install.sh"]:::script
            INS["installer.nsi"]:::script
            ISS["setup.iss"]:::script
            IPY["setup.py"]:::script
        end
    end

    %% Flow Connections
    U -->|"triggers"| CE
    CE -->|"invokes"| HS
    CE -->|"loads"| CONF
    CE -->|"validates (async)"| PH
    CE -->|"initiates"| SS
    CE -->|"executes"| USR
    CE -->|"utilizes"| UT
    SS -->|"APIcall"| EX
    USR -->|"reads"| DS

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#FFC300,stroke:#000,stroke-width:1px;
    classDef module fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef infra fill:#F5A9A9,stroke:#000,stroke-width:1px;
    classDef script fill:#F4A460,stroke:#000,stroke-width:1px;

    %% Click Events
    click CE "https://github.com/barkahss/ominis-osint/blob/main//ominis.py"
    click HS "https://github.com/barkahss/ominis-osint/blob/main//ominis.sh"
    click CONF "https://github.com/barkahss/ominis-osint/blob/main//src/config.py"
    click PH "https://github.com/barkahss/ominis-osint/blob/main//src/proxy_handler.py"
    click SS "https://github.com/barkahss/ominis-osint/blob/main//src/serp_search.py"
    click USR "https://github.com/barkahss/ominis-osint/blob/main//src/usr.py"
    click USR "https://github.com/barkahss/ominis-osint/blob/main//src/tools_handler.py"
    click UT "https://github.com/barkahss/ominis-osint/blob/main//src/utils.py"
    click DS "https://github.com/barkahss/ominis-osint/blob/main//src/social_platforms.json"
    click DS "https://github.com/barkahss/ominis-osint/blob/main//src/urls.txt"
    click UI "https://github.com/barkahss/ominis-osint/tree/main//src/img"
    click CONT "https://github.com/barkahss/ominis-osint/tree/main//Dockerfile"
    click CICD "https://github.com/barkahss/ominis-osint/tree/main//.github/workflows"
    click IBAT "https://github.com/barkahss/ominis-osint/blob/main//install.bat"
    click ISH "https://github.com/barkahss/ominis-osint/blob/main//install.sh"
    click INS "https://github.com/barkahss/ominis-osint/blob/main//installer.nsi"
    click ISS "https://github.com/barkahss/ominis-osint/blob/main//setup.iss"
    click IPY "https://github.com/barkahss/ominis-osint/blob/main//setup.py"
```
