# wsvargas/scraping_instagram_benford architecture

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

- Interactive diagram: https://gitdiagram.com/wsvargas/scraping_instagram_benford
- Repository: https://github.com/wsvargas/scraping_instagram_benford

## Overview

Para representar con precisión la arquitectura de este proyecto “Analizador de Followers – Ley de Benford”, sigue estos pasos:

##### Tipo de proyecto y propósito
- Proyecto Python de un solo servicio (monolito) que combina:
- Interfaz de usuario (Streamlit)
- Módulo de scraping de Instagram
- Módulo de análisis estadístico (Ley de Benford)
- Módulo de generación de reportes (Gráficos + Excel)
- Propósito: Detectar anomalías en la distribución de seguidores de Instagram para descubrir actividad de bots.

##### Componentes principales a dibujar
A. Usuario / Cliente
– Navegador web
– Interactúa con la UI de Streamlit
B. Capa de Presentación (Streamlit)
– ins.py arranca el servidor Streamlit
– Recibe parámetros (nombre de cuenta, umbrales)
– Muestra dashboards/plots
C. Capa de Negocio
1. Scraping Module
- Lee cookies.env para autenticación
- Gestiona paginación y delays dinámicos
- Llama a los endpoints web de Instagram
- Maneja reintentos y soft-bans (respuesta no-JSON, bloqueos)
2. Analysis Module
- Extrae primer dígito de cada conteo de followers
- Calcula distribución real vs. Ley de Benford
- Mide desviaciones, umbrales, probabilidades
3. Reporting Module
- Genera gráficos con Matplotlib
- Exporta un reporte Excel (pandas + openpyxl)
D. Persistencia / Logging
– logs.txt para seguimiento de ejecución y errores
– respuesta_bloqueo.html para debugging de bloqueos
– Excel resultante como artefacto de salida
E. Servicios Externos
– Instagram Web Endpoints (HTTP requests)

##### Relaciones e interacciones
- Usuario → (HTTP) → Streamlit UI
- Streamlit UI → invoca funciones de ins.py
- Scraping Module → (HTTP) → Instagram Endpoints
- Scraping Module → devuelve datos brutos → Analysis Module
- Analysis Module → datos procesados → Reporting Module
- Reporting Module →
- Gráficos → Streamlit UI
- Excel → sistema de archivos
- Cualquier módulo → logs.txt

##### Patrones y principios arquitectónicos
- Capa de Presentación / Negocio / Persistencia (arquitectura en capas)
- Separación de responsabilidades:
- UI vs. Scraping vs. Lógica de Negocio vs. Reportes
- Robustez y tolerancia a fallos en Scraping (reintentos, delays)

##### Guía para el diagrama
- Usa rectángulos para componentes internos (cada módulo).
- Usa cilindros o documentos para artefactos: logs.txt, Excel.
- Usa nube o icono “WWW” para Instagram (servicio externo).
- Flechas con sentido del flujo de datos (requests, respuestas, resultados).
- Azul (UI)
- Verde (Scraping)
- Amarillo (Análisis)
- Naranja (Reportes)
- Gris (Logging / Artefactos)
- Morado (Servicios externos)

##### Elementos mínimos a incluir
- Etiquetas claras: “Streamlit UI”, “Scraping Module”, “Analysis Module”, “Reporting Module”
- Flechas con anotaciones: “GET followers”, “datos crudos → análisis”
- Conexión a cookies.env para autenticación
- Indicar logs.txt y Excel como salidas
- Ambiente de ejecución: Python 3.x, requirements.txt

Con este esquema tu diagrama mostrará de forma detallada y fiel cada parte del sistema, sus interacciones, tecnologías y flujos de datos.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser (User)"]:::external
        StreamlitUI["Streamlit UI"]:::ui
    end

    %% Business Layer
    subgraph "Business Layer"
        ScrapingModule["Scraping Module"]:::scraping
        AnalysisModule["Analysis Module"]:::analysis
        ReportingModule["Reporting Module"]:::reporting
    end

    %% Persistence / Logging
    subgraph "Persistence / Logging"
        logs["logs.txt"]:::artifact
        block["respuesta_bloqueo.html"]:::artifact
        excel["Excel Report"]:::artifact
    end

    %% External Services
    subgraph "External Services"
        Instagram["Instagram Web Endpoints"]:::external
    end

    %% Environment & Dependencies
    subgraph "Environment & Dependencies"
        requirements["requirements.txt"]:::artifact
        readme["README.md"]:::artifact
        CookiesEnv["cookies.env"]:::artifact
    end

    %% Flows
    Browser -->|"HTTP Request"| StreamlitUI
    StreamlitUI -->|"calls Scraping"| ScrapingModule
    ScrapingModule -->|"auth via"| CookiesEnv
    ScrapingModule -->|"GET followers"| Instagram
    Instagram -->|"response JSON/HTML"| ScrapingModule
    ScrapingModule -->|"raw data → analysis"| AnalysisModule
    AnalysisModule -->|"processed data → reporting"| ReportingModule
    ReportingModule -->|"renders graphs"| StreamlitUI
    ReportingModule -->|"exports Excel"| excel

    %% Logging flows
    ScrapingModule -->|"logs events"| logs
    AnalysisModule -->|"logs events"| logs
    ReportingModule -->|"logs events"| logs
    ScrapingModule -->|"dump blocks"| block

    %% Click Events
    click StreamlitUI "https://github.com/wsvargas/scraping_instagram_benford/blob/main/ins.py"
    click ScrapingModule "https://github.com/wsvargas/scraping_instagram_benford/blob/main/cookies.env"
    click AnalysisModule "https://github.com/wsvargas/scraping_instagram_benford/blob/main/ins.py"
    click ReportingModule "https://github.com/wsvargas/scraping_instagram_benford/blob/main/ins.py"
    click logs "https://github.com/wsvargas/scraping_instagram_benford/blob/main/logs.txt"
    click block "https://github.com/wsvargas/scraping_instagram_benford/blob/main/respuesta_bloqueo.html"
    click excel "https://github.com/wsvargas/scraping_instagram_benford/tree/main/Excel Report"
    click requirements "https://github.com/wsvargas/scraping_instagram_benford/blob/main/requirements.txt"
    click readme "https://github.com/wsvargas/scraping_instagram_benford/blob/main/README.md"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0000cc,color:#0000cc
    classDef scraping fill:#d4edda,stroke:#008000,color:#008000
    classDef analysis fill:#fff3cd,stroke:#ccaa00,color:#ccaa00
    classDef reporting fill:#f8d7da,stroke:#ff8800,color:#ff8800
    classDef artifact fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#e2dbf5,stroke:#6f42c1,color:#6f42c1
```
