# gigachad80/spectra architecture

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

- Interactive diagram: https://gitdiagram.com/gigachad80/spectra
- Repository: https://github.com/gigachad80/spectra

## Overview

##### Project type and purpose
- Spectra is an open-source, command-line Python tool for automated reconnaissance and sensitive-endpoint discovery.
- Its purpose is to orchestrate multiple external scanners (subfinder, httpx, waybackurls, gobuster, ffuf) plus built-in analysis and reporting, producing HTML/JSON/text outputs.

##### File structure
- Top-level files:
- spectra.py – the main Python entry point and orchestration script
- LICENSE, README.md – project metadata
- Directory:
- wordlists/ – contains sensitive_endpoints.txt for endpoint filtering
- No complex subdirectories or microservices—single-process CLI.

##### README for architectural clues
- Workflow phases described:
- Subdomain discovery
- Live host filtering
- Historical endpoint enumeration
- Brute-force scanning
- Analysis & categorization
- Reporting
- External dependencies: Golang tools and Python modules.

##### Main components
a. User Interface (CLI)
- Terminal/console invoking spectra.py
b. Orchestration Engine (spectra.py)
- Argument parsing & workflow selection
- Module invoker for each phase
c. External Scanning Tools
- subfinder
- httpx
- waybackurls
- gobuster / ffuf
d. Wordlist Store
- wordlists/sensitive_endpoints.txt
e. Analysis & Categorization Module
- HTTP status code analysis
- Vulnerability risk tagging
f. Reporting Module
- HTML renderer
- JSON/text writer
g. Output Workspace
- Directory structure for logs and reports
h. External Service
- Wayback Machine API (accessed by waybackurls)

##### Relationships and data flow
- CLI → Orchestration Engine
- Engine → subdomain discovery tool → raw domain list
- Raw list → httpx → filtered live hosts
- Live hosts → waybackurls → archived endpoints
- Live hosts + wordlists → gobuster/ffuf → discovered endpoints
- All endpoints → Analysis Module → categorized findings
- Findings → Reporting Module → output formats → Output Workspace
- Logs generated at each step for troubleshooting.

##### Architectural patterns and design principles
- Modular pipeline: each recon phase is a plug-and-play module
- Single responsibility: separate scanners, analyzers, reporters
- Extensibility: easy to swap or add new tools or wordlists
- CLI-driven configuration and interactive menu support.

##### Relevant technologies/frameworks
- Python 3.6+ (argparse or click)
- Golang-based external tools (subfinder, httpx, waybackurls, gobuster, ffuf)
- HTML templating library for reports (e.g., Jinja2)
- JSON library for structured output
- Logging module for detailed logs

##### Key elements to capture
- Components: CLI, orchestration engine, each scanner, analysis, reporting, data stores
- Flows: raw data ingestion, filtering, enrichment, analysis, output
- External dependencies: tool binaries, API calls
- Output targets: HTML, JSON, text, logs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    UI["User Interface (CLI)"]:::ui
    click UI "https://github.com/gigachad80/spectra/blob/main/spectra.py"

    %% Orchestration Engine
    Engine["Orchestration Engine\n(argument parsing & workflow coordination)"]:::orchestration
    click Engine "https://github.com/gigachad80/spectra/blob/main/spectra.py"

    %% Pipeline Modules
    subgraph "Scanning Modules"
        direction TB
        Subfinder["Subdomain Discovery\n(subfinder)"]:::external
        HTTPX["Live Host Filtering\n(httpx)"]:::external
        WaybackURLs["Historical Endpoint Enumeration\n(waybackurls)"]:::external
        Gobuster["Brute-Force Scanning\n(gobuster/ffuf)"]:::external
    end

    %% Analysis and Reporting
    Analysis["Analysis & Categorization\n(status code analysis, risk tagging)"]:::orchestration
    click Analysis "https://github.com/gigachad80/spectra/blob/main/spectra.py"
    Reporting["Reporting Module\n(HTML/JSON/text renderer)"]:::orchestration
    click Reporting "https://github.com/gigachad80/spectra/blob/main/spectra.py"

    %% Data Stores and External Service
    WordlistStore["Wordlist Store\n(sensitive_endpoints.txt)"]:::datastore
    click WordlistStore "https://github.com/gigachad80/spectra/blob/main/wordlists/sensitive_endpoints.txt"
    OutputWorkspace["Output Workspace\n(logs & reports folder)"]:::datastore
    ExternalAPI["Wayback Machine API"]:::external

    %% Metadata
    Metadata["Project Metadata & Documentation\n(README.md)"]:::datastore
    click Metadata "https://github.com/gigachad80/spectra/blob/main/README.md"
    License["License Information\n(LICENSE)"]:::datastore
    click License "https://github.com/gigachad80/spectra/tree/main/LICENSE"

    %% Flow connections
    UI -->|invoke| Engine
    Engine -->|invoke| Subfinder
    Subfinder -->|raw domains| HTTPX
    HTTPX -->|live hosts| WaybackURLs
    WaybackURLs -->|archived endpoints| Analysis
    HTTPX -->|live hosts| Gobuster
    WordlistStore -->|endpoints list| Gobuster
    Gobuster -->|discovered endpoints| Analysis
    Analysis -->|findings| Reporting
    Reporting -->|reports| OutputWorkspace

    %% External API call
    WaybackURLs -.->|API request| ExternalAPI

    %% Logs at each step
    subgraph Logs
        direction TB
        LogSubfinder["Subfinder Logs"]:::ui
        LogHTTPX["httpx Logs"]:::ui
        LogWayback["waybackurls Logs"]:::ui
        LogGobuster["gobuster/ffuf Logs"]:::ui
        LogAnalysis["Analysis Logs"]:::ui
        LogReporting["Reporting Logs"]:::ui
    end
    Subfinder -->|logs| LogSubfinder --> OutputWorkspace
    HTTPX -->|logs| LogHTTPX --> OutputWorkspace
    WaybackURLs -->|logs| LogWayback --> OutputWorkspace
    Gobuster -->|logs| LogGobuster --> OutputWorkspace
    Analysis -->|logs| LogAnalysis --> OutputWorkspace
    Reporting -->|logs| LogReporting --> OutputWorkspace

    %% Styles
    classDef ui fill:#F0F0F0,stroke:#888;
    classDef orchestration fill:#D0E1FF,stroke:#036;
    classDef external fill:#DFFFE0,stroke:#060,stroke-dasharray: 5 5;
    classDef datastore fill:#FFEFD0,stroke:#E80,shape:cylinder;
```
