# darkoscode/winelitycs architecture

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

- Interactive diagram: https://gitdiagram.com/darkoscode/winelitycs
- Repository: https://github.com/darkoscode/winelitycs

## Overview

1. **Purpose and shape of the system**
   WineLitycs is a local Python analytics pipeline for a winery. It is not a service/API app; it is a batch-style tool that reads CSV inputs, performs ETL-style transformations, and produces multiple visual reports.

2. **End-to-end data flow**
   The repository follows a simple linear flow: synthetic or existing CSV data in `data/` is read by the `sources/` modules, normalized and aggregated in `dataProcessing.py`, then handed off to the plotting utilities in `visuals/` for static and interactive reporting.

3. **Input data boundary**
   The main inputs are `data/ventas.csv` and `data/inventario.csv`. These are the only persisted business datasets in the repo, and they act as the boundary between raw data and the processing layer.

4. **Data generation subsystem**
   `sources/generadorDeDatos.py` is a support tool that creates the sample datasets under `data/`. This means the project can be bootstrapped without external systems or databases; the architecture is file-based and self-contained.

5. **Source ingestion layer**
   `sources/ventas_csv.py` and `sources/inventario_csv.py` appear to encapsulate CSV loading and cleanup for their respective domains. This is the repository’s first normalization boundary, separating file I/O from downstream analysis logic.

6. **Schema/contract layer**
   The `schema/` package (`inventario.py`, `ventas.py`) centralizes column names and data structures. Architecturally, this reduces coupling between loaders, transforms, and charts by keeping field definitions consistent across the pipeline.

7. **Transformation / ETL core**
   `dataProcessing.py` is the main business-logic layer. According to the README, it cleans data, calculates revenue, determines seasonality, and cross-references sales against physical inventory to support stock and performance analysis.

8. **Analytical outputs**
   The processed dataset is used to derive the main winery KPIs: varietal popularity, seasonal sales behavior, distribution-channel comparison, and restock alerts. These are not separate services; they are reportable views built from the same processed data model.

9. **Visualization subsystem**
   The `visuals/` package contains three presentation adapters:
   - `matplot_utils.py` for a heatmap-style seasonal varietal analysis
   - `seaborn_utils.py` for monthly channel comparison
   - `plotly_utils.py` for an interactive bubble report exported to HTML  
   This is a clear boundary between analytics and presentation.

10. **Runtime orchestration**
    `main.py` is the top-level orchestrator. It likely executes the ETL step first, then opens the visualizations sequentially. The README indicates the process is interactive in places, because the user must close one chart before the next appears.

11. **Presentation/runtime characteristics**
    The stack is pure Python, with plotting split across Matplotlib, Seaborn, and Plotly. Plotly also adds a browser-based output artifact (`visuals/reporte_interactivo.html`), while the other two charts are likely desktop window outputs.

12. **Deployment and infrastructure**
    There is no evidence of a backend server, database, message queue, or cloud dependency. The architecture is local, file-based, and run manually from the command line with Python and pip-installed dependencies.

13. **Key diagram boundaries to show**
    A useful architecture diagram should show:
    raw/generated CSVs → CSV readers → shared schema constants → ETL processing → three visualization paths.  
    The only persistent outputs beyond the CSVs are the interactive HTML report and the transient chart windows.

14. **Main repo pattern**
    Overall, this is a modular analytics pipeline with clear separation of concerns: data generation, data access, transformation, and visualization. The repo is organized around a single orchestration entry point rather than multiple independent components.

Main entry points: [`dataProcessing.py`](https://github.com/darkoscode/winelitycs/blob/main/dataProcessing.py) (Processing), [`main.py`](https://github.com/darkoscode/winelitycs/blob/main/main.py) (Main), [`sources/generadorDeDatos.py`](https://github.com/darkoscode/winelitycs/blob/main/sources/generadorDeDatos.py) (Generador), [`sources/ventas_csv.py`](https://github.com/darkoscode/winelitycs/blob/main/sources/ventas_csv.py) (Ventas loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data Inputs"]
  node_data_ventas_csv[("ventas.csv<br/>csv dataset<br/>[ventas.csv]")]
  node_data_inventario_csv[("inventario.csv<br/>csv dataset<br/>[inventario.csv]")]
end

subgraph group_ingest["Ingestion"]
  node_sources_generador_de_datos["Generador<br/>data bootstrap"]
  node_sources_ventas_csv["Ventas loader<br/>csv ingest<br/>[ventas_csv.py]"]
  node_sources_inventario_csv["Inventario loader<br/>csv ingest<br/>[inventario_csv.py]"]
end

subgraph group_contracts["Schema"]
  node_schema_ventas["Ventas schema<br/>field contract<br/>[ventas.py]"]
  node_schema_inventario["Inventario schema<br/>field contract<br/>[inventario.py]"]
end

subgraph group_core["ETL Core"]
  node_data_processing["Processing<br/>etl analytics<br/>[dataProcessing.py]"]
end

subgraph group_viz["Visuals"]
  node_visuals_matplot_utils["Matplotlib view<br/>static viz<br/>[matplot_utils.py]"]
  node_visuals_seaborn_utils["Seaborn view<br/>static viz<br/>[seaborn_utils.py]"]
  node_visuals_plotly_utils["Plotly view<br/>interactive viz<br/>[plotly_utils.py]"]
end

subgraph group_runtime["Runtime"]
  node_main_py{{"Main<br/>orchestrator<br/>[main.py]"}}
end

node_sources_generador_de_datos -->|"generates"| node_data_ventas_csv
node_sources_generador_de_datos -->|"generates"| node_data_inventario_csv
node_data_ventas_csv -->|"reads"| node_sources_ventas_csv
node_data_inventario_csv -->|"reads"| node_sources_inventario_csv
node_schema_ventas -->|"contracts"| node_sources_ventas_csv
node_schema_inventario -->|"contracts"| node_sources_inventario_csv
node_sources_ventas_csv -->|"feeds sales"| node_data_processing
node_sources_inventario_csv -->|"feeds inventory"| node_data_processing
node_schema_ventas -->|"columns"| node_data_processing
node_schema_inventario -->|"columns"| node_data_processing
node_data_processing -->|"seasonality"| node_visuals_matplot_utils
node_data_processing -->|"channels"| node_visuals_seaborn_utils
node_data_processing -->|"kpis"| node_visuals_plotly_utils
node_main_py -->|"bootstraps"| node_sources_generador_de_datos
node_main_py -->|"orchestrates"| node_data_processing
node_main_py -->|"opens"| node_visuals_matplot_utils
node_main_py -->|"opens"| node_visuals_seaborn_utils
node_main_py -->|"exports"| node_visuals_plotly_utils

click node_data_ventas_csv "https://github.com/darkoscode/winelitycs/blob/main/data/ventas.csv"
click node_data_inventario_csv "https://github.com/darkoscode/winelitycs/blob/main/data/inventario.csv"
click node_sources_generador_de_datos "https://github.com/darkoscode/winelitycs/blob/main/sources/generadorDeDatos.py"
click node_sources_ventas_csv "https://github.com/darkoscode/winelitycs/blob/main/sources/ventas_csv.py"
click node_sources_inventario_csv "https://github.com/darkoscode/winelitycs/blob/main/sources/inventario_csv.py"
click node_schema_ventas "https://github.com/darkoscode/winelitycs/blob/main/schema/ventas.py"
click node_schema_inventario "https://github.com/darkoscode/winelitycs/blob/main/schema/inventario.py"
click node_data_processing "https://github.com/darkoscode/winelitycs/blob/main/dataProcessing.py"
click node_visuals_matplot_utils "https://github.com/darkoscode/winelitycs/blob/main/visuals/matplot_utils.py"
click node_visuals_seaborn_utils "https://github.com/darkoscode/winelitycs/blob/main/visuals/seaborn_utils.py"
click node_visuals_plotly_utils "https://github.com/darkoscode/winelitycs/blob/main/visuals/plotly_utils.py"
click node_main_py "https://github.com/darkoscode/winelitycs/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_ventas_csv,node_data_inventario_csv toneBlue
class node_sources_generador_de_datos,node_sources_ventas_csv,node_sources_inventario_csv toneAmber
class node_schema_ventas,node_schema_inventario toneMint
class node_data_processing toneRose
class node_visuals_matplot_utils,node_visuals_seaborn_utils,node_visuals_plotly_utils toneIndigo
class node_main_py toneTeal
```

## Components

### Data Inputs

Persisted winery datasets that define the raw business-data boundary.

- [ventas.csv](https://github.com/darkoscode/winelitycs/blob/main/data/ventas.csv): csv dataset · Sales input data. · `data/ventas.csv`
- [inventario.csv](https://github.com/darkoscode/winelitycs/blob/main/data/inventario.csv): csv dataset · Inventory input data. · `data/inventario.csv`

### Ingestion

CSV readers and bootstrap data generation.

- [Generador](https://github.com/darkoscode/winelitycs/blob/main/sources/generadorDeDatos.py): data bootstrap · Creates sample CSV datasets under data/. · `sources/generadorDeDatos.py`
- [Ventas loader](https://github.com/darkoscode/winelitycs/blob/main/sources/ventas_csv.py): csv ingest · Loads and cleans sales data. · `sources/ventas_csv.py`
- [Inventario loader](https://github.com/darkoscode/winelitycs/blob/main/sources/inventario_csv.py): csv ingest · Loads and cleans inventory data. · `sources/inventario_csv.py`

### Schema

Shared field definitions used across loading, transformation, and reporting.

- [Ventas schema](https://github.com/darkoscode/winelitycs/blob/main/schema/ventas.py): field contract · Shared sales column definitions. · `schema/ventas.py`
- [Inventario schema](https://github.com/darkoscode/winelitycs/blob/main/schema/inventario.py): field contract · Shared inventory column definitions. · `schema/inventario.py`

### ETL Core

Normalization, calculation, and analysis logic.

- [Processing](https://github.com/darkoscode/winelitycs/blob/main/dataProcessing.py): etl analytics · Cleans data, calculates revenue, seasonality, inventory cross-checks, and KPI views. · `dataProcessing.py`

### Visuals

Presentation adapters for static and interactive reports.

- [Matplotlib view](https://github.com/darkoscode/winelitycs/blob/main/visuals/matplot_utils.py): static viz · Heatmap-style seasonal varietal analysis. · `visuals/matplot_utils.py`
- [Seaborn view](https://github.com/darkoscode/winelitycs/blob/main/visuals/seaborn_utils.py): static viz · Monthly channel comparison charts. · `visuals/seaborn_utils.py`
- [Plotly view](https://github.com/darkoscode/winelitycs/blob/main/visuals/plotly_utils.py): interactive viz · Interactive bubble report exported to HTML. · `visuals/plotly_utils.py`

### Runtime

Top-level orchestration entry point.

- [Main](https://github.com/darkoscode/winelitycs/blob/main/main.py): orchestrator · Runs the batch pipeline and opens reports in sequence. · `main.py`

## Connections

- Generador → ventas.csv: generates · Bootstraps sales sample data.
- Generador → inventario.csv: generates · Bootstraps inventory sample data.
- ventas.csv → Ventas loader: reads · Sales CSV is ingested by the sales loader.
- inventario.csv → Inventario loader: reads · Inventory CSV is ingested by the inventory loader.
- Ventas schema → Ventas loader: contracts · Sales loader follows shared sales field definitions.
- Inventario schema → Inventario loader: contracts · Inventory loader follows shared inventory field definitions.
- Ventas loader → Processing: feeds sales · Normalized sales data enters the ETL core.
- Inventario loader → Processing: feeds inventory · Normalized inventory data enters the ETL core.
- Ventas schema → Processing: columns · Processing uses sales field constants.
- Inventario schema → Processing: columns · Processing uses inventory field constants.
- Processing → Matplotlib view: seasonality · Processed analytics drive the heatmap report.
- Processing → Seaborn view: channels · Processed analytics drive channel comparison charts.
- Processing → Plotly view: kpis · Processed analytics drive the interactive report.
- Main → Generador: bootstraps · Main can create sample data before analysis.
- Main → Processing: orchestrates · Main coordinates the ETL step.
- Main → Matplotlib view: opens · Main triggers the first visualization.
- Main → Seaborn view: opens · Main triggers the second visualization.
- Main → Plotly view: exports · Main triggers the interactive Plotly report.