# urban20/mc-crawler architecture

> Architecture diagram of the GitHub repository urban20/mc-crawler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urban20/mc-crawler
- Repository: https://github.com/urban20/mc-crawler

## Overview

##### Tipo de proyecto y propósito (qué estás diagramando)
**MC Crawler** es una **herramienta CLI** (línea de comandos) orientada a **descubrir, clasificar y mantener un registro de servidores de Minecraft Java**.

Su “pipeline” funcional (según README + árbol) es:
##### Obtención de rangos CIDR asociados a hostings / IPs ocupadas (módulo `cidr_`).
2. **Selección aleatoria de rangos** y **escaneo de puertos a gran escala** (rangos /16) usando un **binario externo “escan”** (Go o `.exe`).
3. **Handshake / paquetes específicos de Minecraft** para inferir características del servidor.
4. **Bot que simula jugador** (sin completar login) para inferir: premium/no-premium, whitelist, mods, ban, etc.
##### Persistencia local en SQLite (dos DBs: `servers.db`, `crackeados.db`).
6. **Operaciones CLI**: Barrido (descubrir), Purgar (limpiar offline), Buscar (no premium), Buscar versión.

**Conclusión para el diagrama**: no es un sistema distribuido clásico con frontend/backend; es un **orquestador CLI local** que coordina: red + binario de escaneo + lógica Minecraft + almacenamiento local.

##### Lectura del file tree (componentes reales que deben aparecer)
Top-level relevante: `src/MC-crawler/` con módulos Python + un escáner en Go.

##### Entrypoint / orquestación
- `main.py`: punto de inicio de la CLI (es donde suele vivir el “control plane” del programa).
- `servers.py`: probable capa de coordinación/operaciones sobre servidores encontrados (según nombre).
- `clases/menu.py`: UI/menú CLI.
- `clases/interruptor.py`, `clases/contador.py`: control de ejecución / flags / contadores (útiles para reflejar “control flow”).

##### Adquisición de rangos / input de IPs
- `cidr_/data.py`, `cidr_/escan_flex.py`: generación/gestión de rangos CIDR y/o preparación para escaneo.

##### Módulo de escaneo (crítico)
- `escaner/`
- `gopython.py`: wrapper Python para invocar el binario.
- `golang/escaner.go` + `go.mod`: fuente del escáner.
- `binario/`: destino del binario (`bin_script.py`, `verificador.py`, `leer.txt` sugieren verificación/ejecución/IO).
- `dependencias.bat`, `iniciar.bat`, `compilar.bat`: scripts de setup/build/run (especialmente para Windows).

**En el diagrama debe existir explícitamente**: “Python CLI” → “Binary Scanner (Go)”.

##### Lógica de protocolo Minecraft / clasificación
- `clases/bot.py`: bot que intenta conexión y observa respuestas.
- `clases/mcserver.py`: modelo/entidad de servidor + propiedades inferidas.
- `clases/MCuuid.py`: utilidades de UUID (Minecraft identity).
- `utilidades/conectividad.py`: sockets/requests/red.
- `utilidades/consola.py`: logging/salida.

##### Persistencia / base de datos local
- `db/db.py`: capa de acceso a datos (SQLite).
- `configuracion/configuracion.py`: parámetros de ejecución (paths, timeouts, cantidad de rangos, etc).
- `requirements.txt`: dependencias Python (mención en diagrama solo si es relevante: por ejemplo “Python runtime + libs”).

##### Diagrama de arquitectura de contenedores (alto nivel)
Enfatiza procesos y dependencias:
- **Usuario** (operador)
- **MC Crawler CLI (Python process)**
- **Binary Scanner `escan` (Go executable)** como proceso separado
- **Minecraft Servers (Internet)** como sistema externo
- **SQLite DB files** (`servers.db`, `crackeados.db`)
- **Sources de CIDR/Hosting ranges** (externo: web/listas; aunque no esté explícito el endpoint, conceptualmente es un “External Data Source”)

Esto responde “qué componentes existen” y “cómo interactúan”.

##### Diagrama de flujo / pipeline (más detallado a nivel ejecución)
Enfatiza etapas y data flow:
- “Barrido”
1. Load config
2. Fetch/Build CIDR ranges
3. Pick random /16
4. Invoke escan (Go) → returns candidate IP:port
5. For each candidate:
- Minecraft ping/handshake (packets)
- Bot connect attempt (pre-login)
- Classify (premium/modded/whitelist/banned/version)
6. Persist results (servers.db + crackeados.db)
- “Purgar”:
- Read servers.db → connectivity check → remove offline
- “Buscar”:
- Query crackeados.db / flag in servers.db
- “Buscar versión”:
- Query by inferred version

Esto responde “cómo funciona” con precisión.

##### Componentes principales (qué cajas dibujar)
Te recomiendo separar en **la mayor cantidad de componentes posible** (sin sobrepensarlo), usando los módulos del repo como guía:

##### Control / UI
- `main.py` (Entrypoint)
- `clases/menu.py` (CLI menu / commands dispatcher)

##### Config
- `configuracion/configuracion.py` (Config loader / runtime settings)

##### CIDR Provider
- `cidr_/data.py` (CIDR datasets / sources)
- `cidr_/escan_flex.py` (Range selection / prep)

##### Scanner Subsystem
- `escaner/gopython.py` (Python wrapper)
- `escaner/binario/*` (binary location + verification)
- `escaner/golang/escaner.go` (scanner implementation)
- External process: `escan` binary (artifact)

##### Minecraft Probing / Botting
- `utilidades/conectividad.py` (network I/O)
- `clases/bot.py` (bot behavior)
- `clases/mcserver.py` (server entity + inference fields)
- `clases/MCuuid.py` (UUID utilities)

##### Persistence
- `db/db.py` (SQLite access)
- Data stores (files):
- `servers.db`
- `crackeados.db`

##### Observability / Console
- `utilidades/consola.py` (logging/output)
- `clases/contador.py` (metrics/counters)
- `clases/interruptor.py` (stop/cancel flags)

##### Relaciones e interacciones (flechas concretas)
En el diagrama, dibuja flechas direccionales y etiqueta el tipo de interacción:

##### User → CLI Menu
- “select option: Barrido/Purgar/Buscar/Buscar versión”

##### CLI → Config
- “load config (timeouts, concurrency, paths)”

##### CLI → CIDR Provider
- “get hosting CIDR ranges”
- “select random /16 ranges”

##### CLI → Scanner Wrapper (Python) → `escan` (Go process)
- “spawn process + args (CIDR, ports, rate limits?)”
- `escan` → CLI: “stream results (open ports / candidates)”

##### CLI → Minecraft Servers (Internet)
- “send ping/handshake packets”
- “bot pre-login connect”
- Response back: “status/version/encryption/whitelist hints/ban”

##### CLI → DB Layer → SQLite files
- “upsert server record”
- “insert into crackeados.db if non-premium”
- “purge offline servers”

##### CLI → Console
- “progress, counters, errors”

**Tip**: separa flechas “control” (invocación) vs “data” (result set). Por ejemplo, línea sólida para control, línea punteada para data, o colores distintos.

##### Patrones/decisiones arquitectónicas a resaltar
- **CLI Orchestrator pattern**: Python coordina submódulos.
- **Polyglot / best-tool-for-job**: Go para scanning intensivo (performance), Python para lógica flexible y parsing.
- **External Process Boundary**: el escáner no es librería, es binario; esto implica manejo de:
- verificación de existencia (`verificador.py`)
- compatibilidad OS (Windows `.exe` vs build local)
- **Local persistence**: SQLite como almacenamiento embebido (dos DBs por “dominio”).
- **Pipeline**: descubrir → validar → clasificar → persistir → mantener (purga).

##### Tecnología a etiquetar en el diagrama
Incluye etiquetas pequeñas dentro o debajo de cada caja:
- “Python 3.x” para el proceso principal.
- “Go (escan)” para el binario de escaneo.
- “SQLite” para `servers.db` y `crackeados.db`.
- “Minecraft Java protocol” para el probing/bot.
- “OS: Windows/Linux” en el boundary del binario (porque el README lo hace crítico).

##### Elementos obligatorios
- **Labels claros**: usa nombres de módulos del repo (aumenta trazabilidad).
- **Flechas** con verbos: “invokes”, “reads/writes”, “queries”, “streams results”.
- Rectángulos azules: componentes Python
- Rectángulo verde: binario Go (`escan`)
- Cilindros: DB files (SQLite)
- Nube: Internet/Minecraft servers
- Documento: fuentes CIDR (external lists)

Haz 2 o 3 columnas:

##### Conecta a
- “Config (configuracion.py)”
- “CIDR provider (cidr_)”
- “Scanner wrapper (gopython.py)”
- “Minecraft probe/bot (bot.py + conectividad.py)”
- “DB layer (db.py) → servers.db / crackeados.db”
- “Console/logging”
##### Fuera del contenedor
- “Minecraft servers (Internet)”
- “CIDR sources / hosting ranges (Internet)”
5. Añade el proceso “escan (Go binary)” como caja separada, conectada desde “Scanner wrapper”.

Si quieres que el diagrama quede extremadamente fiel al repo, el siguiente paso sería abrir `main.py` y `servers.py` para mapear **exactamente** qué funciones llaman a cuáles (y así rotular flechas con nombres reales de funciones/commands). Pero con el árbol + README ya puedes dibujar un diagrama correcto y muy detallado a nivel de componentes y data-flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External actors/systems
    User["User / Operator"]:::external
    CIDRSrc["CIDR Sources / Hosting Ranges (Internet)"]:::external
    MCNet["Minecraft Java Servers (Internet)"]:::external

    %% Local host boundary
    subgraph "Local Host Machine (Windows/Linux)"
        direction TB

        subgraph "CLI Orchestrator (Python 3.x)"
            direction TB
            Main["main.py\nEntrypoint"]:::py
            Menu["clases/menu.py\nCLI Menu / Command Dispatcher"]:::py
            ServersOps["servers.py\nServer Ops / Pipeline Coordinator"]:::py

            Interruptor["clases/interruptor.py\nInterrupt / Stop Flags"]:::control
            Contador["clases/contador.py\nCounters / Progress Metrics"]:::control

            Consola["utilidades/consola.py\nConsole / Logging"]:::obs
            Config["configuracion/configuracion.py\nConfig Loader / Runtime Settings"]:::cfg
        end

        subgraph "CIDR Provider (cidr_)"
            direction TB
            CIDRPackage["cidr_/\nPackage"]:::py
            CIDRData["cidr_/data.py\nCIDR Datasets / Sources"]:::py
            CIDRFlex["cidr_/escan_flex.py\nRange Selection / Prep"]:::py
        end

        subgraph "Scanner Subsystem (Polyglot Boundary)"
            direction TB

            subgraph "Python Wrapper"
                direction TB
                GoPy["escaner/gopython.py\nSpawn External Scanner + Parse Output"]:::py
            end

            subgraph "Binary Artifacts / Utilities"
                direction TB
                BinDir["escaner/binario/\nBinary Location + Helpers"]:::artifact
                BinScript["bin_script.py\nRun Helper"]:::artifact
                Verificador["verificador.py\nBinary Verify (exists/compat)"]:::artifact
            end

            subgraph "Go Scanner Implementation"
                direction TB
                GoSrc["golang/escaner.go\nScanner Source (Go)"]:::go
                GoMod["golang/go.mod\nGo Module / Build Deps"]:::go
                EscanProc["escan (Go Executable)\nExternal Process"]:::goexe
            end
        end

        subgraph "Minecraft Probing / Classification"
            direction TB
            NetIO["utilidades/conectividad.py\nSockets / Network IO"]:::py
            Bot["clases/bot.py\nPre-login Bot Probe"]:::py
            MCServer["clases/mcserver.py\nServer Entity + Inference Fields"]:::py
            MCUUID["clases/MCuuid.py\nUUID Utilities"]:::py
        end

        subgraph "Persistence (SQLite)"
            direction TB
            DBLayer["db/db.py\nSQLite Data Access Layer"]:::dbaccess
            ServersDB[("servers.db\nSQLite")]:::db
            CrackedDB[("crackeados.db\nSQLite")]:::db
        end

        subgraph "Build / Setup Scripts (Windows)"
            direction TB
            BuildBat["compilar.bat\nBuild Scanner"]:::script
            DepsBat["dependencias.bat\nInstall Dependencies"]:::script
            StartBat["iniciar.bat\nRun Entry Script"]:::script
            Reqs["requirements.txt\nPython Dependencies"]:::script
        end
    end

    %% User interactions (control)
    User -->|"selects_command"| Menu
    Menu -->|"dispatches"| Main
    Main -->|"runs_pipeline"| ServersOps

    %% Cross-cutting control/observability
    Main -->|"load_config"| Config
    ServersOps -->|"check_stop_flag"| Interruptor
    ServersOps -->|"update_progress"| Contador
    Main -->|"log_output"| Consola
    ServersOps -->|"log_output"| Consola

    %% CIDR acquisition
    ServersOps -->|"get_cidr_ranges"| CIDRPackage
    CIDRPackage -->|"load_datasets"| CIDRData
    CIDRData -.->|"fetch/read_lists"| CIDRSrc
    CIDRPackage -->|"select_random_/16"| CIDRFlex

    %% Scanning (Python -> Go executable boundary)
    CIDRFlex -->|"prepare_scan_targets"| GoPy
    GoPy -->|"verify_binary"| Verificador
    Verificador -->|"uses_helpers"| BinDir
    BinDir -->|"run_helper"| BinScript

    GoPy -->|"spawn_process+args"| EscanProc
    EscanProc -->|"built_from"| GoSrc
    GoSrc -->|"deps"| GoMod
    BuildBat -->|"go_build"| GoSrc
    StartBat -->|"launch_cli"| Main
    DepsBat -->|"install_python_deps"| Reqs

    %% Scanner results (data stream)
    EscanProc -.->|"streams_candidates(IP:port)"| GoPy
    GoPy -.->|"candidate_targets"| ServersOps

    %% Probing / bot classification
    ServersOps -->|"ping/handshake_packets"| NetIO
    NetIO -->|"connects_to"| MCNet
    MCNet -.->|"status/version/flags"| NetIO

    ServersOps -->|"pre_login_probe"| Bot
    Bot -->|"uses_network_io"| NetIO
    Bot -->|"uses_uuid_utils"| MCUUID
    Bot -.->|"inference_signals"| MCServer
    ServersOps -.->|"server_model_updates"| MCServer

    %% Persistence
    ServersOps -->|"upsert_server_record"| DBLayer
    DBLayer -->|"read/write"| ServersDB
    DBLayer -->|"insert_non_premium"| CrackedDB
    ServersOps -->|"purge_offline"| DBLayer
    ServersOps -->|"query_non_premium"| DBLayer
    ServersOps -->|"query_by_version"| DBLayer

    %% Click events (paths only; not visible in node labels)
    click Main "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/main.py"
    click ServersOps "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/servers.py"
    click Menu "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/menu.py"
    click Interruptor "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/interruptor.py"
    click Contador "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/contador.py"
    click CIDRData "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/cidr_/data.py"
    click CIDRFlex "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/cidr_/escan_flex.py"
    click CIDRPackage "https://github.com/urban20/mc-crawler/tree/main/src/MC-crawler/cidr_/"
    click GoPy "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/escaner/gopython.py"
    click GoSrc "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/escaner/golang/escaner.go"
    click GoMod "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/escaner/golang/go.mod"
    click BinDir "https://github.com/urban20/mc-crawler/tree/main/src/MC-crawler/escaner/binario/"
    click BinScript "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/escaner/binario/bin_script.py"
    click Verificador "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/escaner/binario/verificador.py"
    click Bot "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/bot.py"
    click MCServer "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/mcserver.py"
    click MCUUID "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/clases/MCuuid.py"
    click NetIO "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/utilidades/conectividad.py"
    click DBLayer "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/db/db.py"
    click Config "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/configuracion/configuracion.py"
    click Consola "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/utilidades/consola.py"
    click BuildBat "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/compilar.bat"
    click DepsBat "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/dependencias.bat"
    click StartBat "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/iniciar.bat"
    click Reqs "https://github.com/urban20/mc-crawler/blob/main/src/MC-crawler/requirements.txt"

    %% Styles
    classDef external fill:#F3F4F6,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef py fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1B3A
    classDef control fill:#E0E7FF,stroke:#4338CA,stroke-width:1.5px,color:#111827
    classDef cfg fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5px,color:#0B1B3A
    classDef obs fill:#FFEDD5,stroke:#C2410C,stroke-width:1.5px,color:#111827
    classDef go fill:#D1FAE5,stroke:#047857,stroke-width:1.5px,color:#052E1B
    classDef goexe fill:#BBF7D0,stroke:#065F46,stroke-width:2px,color:#052E1B
    classDef artifact fill:#DCFCE7,stroke:#16A34A,stroke-width:1.5px,color:#052E1B
    classDef dbaccess fill:#FEF3C7,stroke:#B45309,stroke-width:1.5px,color:#111827
    classDef db fill:#FDE68A,stroke:#92400E,stroke-width:1.5px,color:#111827
    classDef script fill:#E5E7EB,stroke:#6B7280,stroke-width:1.5px,color:#111827
```
