darkoscode/winelitycs

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.