# andreaquelali/mivoto_tss architecture

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

- Interactive diagram: https://gitdiagram.com/andreaquelali/mivoto_tss
- Repository: https://github.com/andreaquelali/mivoto_tss

## Overview

Para diseñar un diagrama de arquitectura preciso para el “Simulador Electoral Bolivia 2025”, sigue estos pasos adaptados a la naturaleza de este proyecto (aplicación de escritorio en Python con GUI):

##### Identificar el tipo de proyecto y su propósito
- Es una aplicación de escritorio monolítica en Python.
- Objetivo: simular y visualizar resultados electorales (históricos y escenarios hipotéticos) usando Tkinter, pandas, matplotlib y openpyxl.

##### Analizar la estructura de archivos
- Único módulo principal: src/app.py.
- Dependencias declaradas en requirements.txt.
- No hay separación de frontend/backend tradicional ni servicios externos web; todo corre localmente.

##### Extraer información clave del README
- Componentes principales: interfaz gráfica, cálculo D’Hondt, manejo de datos (Excel/CSV), gráficos interactivos, simulación de segunda vuelta.
- Herramientas: tkinter, pandas, openpyxl, matplotlib.

##### Componentes y límites del sistema
a. Capa de Presentación (UI)
- Tkinter: ventanas, formularios (agregar partidos, botones).
- Paneles o pestañas: “Resultados Históricos”, “Simulación”.
b. Capa de Lógica de Negocio
- Módulo de simulación: aplicación del método D’Hondt.
- Algoritmos de umbral (3%), simulación aleatoria de nuevos partidos, segunda vuelta.
c. Capa de Datos
- Lectura/escritura de hojas Excel (openpyxl) o DataFrames (pandas).
- Posible almacenamiento temporal en memoria (pandas DataFrame).
d. Capa de Visualización
- matplotlib: generación de gráficos de pastel, barras, distribuciones de escaños.
e. Entorno de Ejecución
- Python 3.6+ local.
- Dependencias gestionadas por requirements.txt y entorno virtual.
f. Extensiones
- Hooks para agregar nuevos módulos (p. ej., exportar resultados, importar otro formato).

##### Relaciones e interacciones
- El usuario interactúa con la UI (Tkinter).
- UI invoca funciones de la Lógica de Negocio, pasando parámetros (resultados históricos, partidos nuevos).
- Lógica de Negocio lee datos con pandas/openpyxl, procesa y retorna DataFrames con resultados.
- Módulo de Visualización toma esos resultados y produce gráficos matplotlib.
- UI incrusta o muestra los gráficos en ventanas Tkinter.
- Flujo de datos bidireccional UI ↔ Lógica de Negocio ↔ Datos/Visualización.

##### Patrones y principios arquitectónicos
- Separación de capas (aunque en un solo archivo, conceptualiza Presentation, Business y Data/Visualization).
- Principio de responsabilidad única: cada componente (UI, cálculo, datos, gráficos) tiene su propia responsabilidad.
- Extensibilidad: punto de extensión para formatos de entrada/salida o nuevos algoritmos electorales.

##### Tecnologías clave
- Tkinter (UI), pandas/openpyxl (gestión de datos), matplotlib (gráficos), Python (lenguaje y runtime).

##### Guía para el diagrama
- Dibuja rectángulos para cada componente:
· UI (Tkinter)
· Simulador (D’Hondt + umbrales + segunda vuelta)
· Capa de Datos (pandas/openpyxl)
· Visualización (matplotlib)
· Entorno Python / Sistema Operativo
- Usa flechas direccionales:
· Usuario → UI
· UI → Simulador → Datos
· Simulador → Visualización → UI
· UI (azul claro / rectángulo de borde grueso)
· Lógica de negocio (verde / rectángulo)
· Datos (amarillo / cilindro o rectángulo con esquinas redondeadas)
· Visualización (naranja / óvalo)
· Entorno (gris / contorno o nube)
- Etiquetas claras con nombres de módulos o librerías (por ejemplo, “pandas.read_excel”, “matplotlib.pyplot”).

##### Recomendaciones finales
- Captura las capas conceptuales aunque sea un único script.
- Marca dependencias externas (pip install, versiones).
- Destaca flujos de datos (lectura → cálculo → gráficos → pantalla).
- Incluye notas de extensión: dónde añadir nuevas funciones o formatos.

Con estos lineamientos, el diagrama mostrará de forma clara y detallada la arquitectura de tu simulador, enfatizando la separación de responsabilidades y las interacciones entre componentes clave.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"Interacts with"| UI

    %% Core Components
    UI["UI (Tkinter)"]:::ui
    Business["Business Logic\n(D’Hondt, umbrales,\nsegunda vuelta)"]:::business
    Data["Data Layer\n(pandas/openpyxl)"]:::data
    Viz["Visualization\n(matplotlib)"]:::viz

    %% Environment and Others
    Env["Environment\nPython 3.6+"]:::env
    Deps["Dependencies\n(requirements.txt)"]:::misc
    Docs["Documentation\n(README.md)"]:::misc

    %% Data Flow
    UI -->|"Invokes"| Business
    Business -->|"Reads/Writes"| Data
    Business -->|"Sends results to"| Viz
    Viz -->|"Renders in"| UI

    %% Supplemental Connections
    Env -.->|Runs on| UI
    Env -.->|Runs on| Business
    Env -.->|Runs on| Data
    Env -.->|Runs on| Viz
    Deps -.->|Defines libraries| Env
    Docs -.->|Describes project| Env

    %% Click Events
    click UI "https://github.com/andreaquelali/mivoto_tss/blob/main/src/app.py"
    click Business "https://github.com/andreaquelali/mivoto_tss/blob/main/src/app.py"
    click Data "https://github.com/andreaquelali/mivoto_tss/blob/main/src/app.py"
    click Viz "https://github.com/andreaquelali/mivoto_tss/blob/main/src/app.py"
    click Deps "https://github.com/andreaquelali/mivoto_tss/blob/main/requirements.txt"
    click Docs "https://github.com/andreaquelali/mivoto_tss/blob/main/README.md"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFFACD,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef viz fill:#FFA500,stroke:#000,stroke-width:1px,shape:ellipse
    classDef env fill:#D3D3D3,stroke:#000,stroke-width:1px,shape:cloud
    classDef misc fill:#E0E0E0,stroke:#000,stroke-width:1px
    class User external
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,shape:circle
```
