# viralvaghela/graphypy architecture

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

- Interactive diagram: https://gitdiagram.com/viralvaghela/graphypy
- Repository: https://github.com/viralvaghela/graphypy

## Overview

##### Project type and purpose
- This is an open-source, command-line Python tool (GraphQL Endpoint Detector) aimed at helping bug bounty hunters and penetration testers automatically detect GraphQL endpoints and schemas on a target URL.

##### File structure
- Top level:
- graphypy.py        – main entry point containing the orchestration logic
- endpoints_wordlist.py – helper module providing common endpoint paths and wordlists
- requirements.txt   – lists external Python dependencies (e.g., requests)
- README.md, LICENSE – documentation and licensing
- No frontend/backend folders because it’s a single-binary CLI.
- No explicit tests directory (could be added later).
- The presence of a wordlist module suggests a brute-forcing component; main script imports and sequences calls.

##### README for additional insights
- The README outlines a 4-step detection sequence:
1) Brute force endpoints from a wordlist
2) Try GraphQL introspection query
3) Fallback to GET introspection
4) Fallback to URL-encoded requests
- There’s a “ToDo” for mutation checks after endpoint detection.
- Usage is via “python graphypy.py URL” after installing dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Tool Internals"
        subgraph "CLI & Orchestrator"
            CLI["CLI Interface"]:::internal
            Orch["Core Orchestrator"]:::internal
        end
        WordEngine["Wordlist Engine"]:::internal
        WordData["Wordlist Data"]:::resource
        HTTPClient["HTTP Client"]:::external
        Decision{"Did introspection succeed?"}:::internal
        OrFailure{"Fallback to GET"}:::internal
        Decision2{"GET succeeded?"}:::internal
        OrFailure2{"Fallback to URL-encoded"}:::internal
        SchemaParser["GraphQL Schema Parser"]:::internal
        Future["Mutation Testing (ToDo)"]:::future
    end

    subgraph "External System"
        Target["Target GraphQL Server"]:::external
    end

    CLI -->|"invoke detection"| Orch
    Orch -->|"1: Get endpoints"| WordEngine
    WordEngine -->|"load wordlist"| WordData
    Orch -->|"brute force requests"| HTTPClient
    HTTPClient -->|">>>"| Target
    Target -->|"responses"| HTTPClient
    Orch -->|"2: Introspection Query"| HTTPClient
    HTTPClient -->|">>>"| Target
    Target -->|"schema payload"| HTTPClient
    HTTPClient -->|"response"| Decision
    Decision -->|"yes"| SchemaParser
    Decision -->|"no"| OrFailure
    OrFailure -->|"3: GET introspection"| HTTPClient
    HTTPClient -->|">>>"| Target
    Target -->|"responses"| HTTPClient
    HTTPClient -->|"response"| Decision2
    Decision2 -->|"yes"| SchemaParser
    Decision2 -->|"no"| OrFailure2
    OrFailure2 -->|"4: URL-encoded request"| HTTPClient
    HTTPClient -->|">>>"| Target
    Target -->|"responses"| HTTPClient
    HTTPClient -->|"valid schema"| SchemaParser
    SchemaParser -->|"output results"| CLI
    SchemaParser -->|"extension point"| Future

    Docs["README.md"]:::resource
    Lic["LICENSE"]:::resource
    Cache["__pycache__/"]:::resource

    Orch --> Docs
    CLI --> Lic
    Orch --> Cache

    click CLI "https://github.com/viralvaghela/graphypy/blob/main/graphypy.py"
    click Orch "https://github.com/viralvaghela/graphypy/blob/main/graphypy.py"
    click WordEngine "https://github.com/viralvaghela/graphypy/blob/main/endpoints_worlist.py"
    click HTTPClient "https://github.com/viralvaghela/graphypy/blob/main/requirements.txt"
    click SchemaParser "https://github.com/viralvaghela/graphypy/blob/main/graphypy.py"
    click Docs "https://github.com/viralvaghela/graphypy/blob/main/README.md"
    click Lic "https://github.com/viralvaghela/graphypy/tree/main/LICENSE"
    click Cache "https://github.com/viralvaghela/graphypy/tree/main/__pycache__/"

    classDef internal fill:#D0E6FF,stroke:#333,stroke-width:1px;
    classDef external fill:#C8F7C5,stroke:#333,stroke-width:1px;
    classDef resource fill:#ECECEC,stroke:#333,stroke-width:1px;
    classDef future fill:#FFF2CC,stroke:#333,stroke-width:1px;
```
