# chzou123/buckhack architecture

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

- Interactive diagram: https://gitdiagram.com/chzou123/buckhack
- Repository: https://github.com/chzou123/buckhack

## Overview

##### Project type and purpose
- This is a data‐science/predictive‐analytics pipeline with an interactive dashboard front end.
- Purpose: ingest historical ticketing CSVs, clean and engineer features, build propensity models for new partial ticket plans, then serve insights via a Flask dashboard.

##### File structure
- Top‐level CSV files (raw inputs): AccountInfo.csv, MembersAccounts.csv, NONseasonticket.csv, etc.
- “DataAnalysis/” – Jupyter notebooks for exploratory analysis (linear regression, lasso, PCA, survival analysis, segmentation).
- Cleaning & preprocessing scripts: accountclean.py, dataclean.py, features_add.py, updateAccount.py, accountSort.py, linear_reg_with_features.py.
- “cleanedfiles/” – output of cleaning steps (per‐segment CSVs).
- “dashboard/” – Flask app and modules (app.py, bucks_stats.py, user_data.py).
- Utility module: data.py (likely contains shared data‐loading functions).

##### README for insights
- Four new partial‐ticket plans to model (Value, Marquee, Weekend, Promotional).
- Goals: predict propensity for each account, recommend most likely plan, provide marketing insights.
- Workflow implied: data ingestion → feature engineering → model training → prediction → dashboard.

a. Main components
- Data Ingestion Layer (raw CSVs)
- Data Cleaning & Preprocessing (accountclean.py, dataclean.py → cleanedfiles/)
- Feature Engineering (features_add.py, linear_reg_with_features.py)
- Modeling (Jupyter notebooks + model‐training scripts)
- Model Storage (serialized models, e.g. pickle files)
- Prediction Service (Flask endpoints in dashboard/app.py)
- Visualization & Dashboard (Flask static templates or dynamic UIs)
- Users (Data Scientists, Marketing Analysts, Sales)
b. Relationships & data flow
– Raw CSVs feed into the Cleaning layer
– Cleaning outputs to cleanedfiles/
– Clean data flows into Feature Engineering to produce feature datasets
– Feature datasets feed into Model Training notebooks/scripts
– Trained models are saved and loaded by the Prediction Service
– Prediction Service serves results to Dashboard UI
– Users interact with the Dashboard to view insights
c. Architectural patterns / design principles
– Separation of concerns: ETL (Extract/Transform/Load), Modeling, Serving
– Modular pipelines: each script/notebook handles one stage
– Reproducibility: notebooks for analysis, scripts for production steps
– RESTful service layer (Flask) for real‐time inference
d. Key technologies & libraries
– Python ecosystem: pandas, scikit‐learn, numpy
– Jupyter notebooks for exploratory analysis
– Flask for micro‐service / dashboard
– CSV/flat‐file data storage; potential extension to SQL or NoSQL

- Blue for Data Layer (CSV, cleaned data)
- Green for Compute Layer (scripts, notebooks, model training)
- Orange for Service Layer (Flask API + Dashboard)
- Rectangles for compute modules/scripts

##### Final recommendations
- Be thorough: capture every stage from ingestion to user interaction.
- Infrastructure notes if relevant (e.g., local files vs. cloud storage).
- Review with stakeholders (Data Science, DevOps, Marketing) to ensure completeness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RawCSV["Raw Ticket CSVs"]:::data
        CleanedFiles[(Cleaned CSVs)]:::data
        ModelStore[(Serialized Models)]:::data
    end

    %% Compute Layer
    subgraph "Compute Layer"
        subgraph "Data Pipeline"
            Cleaning1["accountclean.py"]:::compute
            Cleaning2["dataclean.py"]:::compute
            Cleaning3["updateAccount.py"]:::compute
            Cleaning4["accountSort.py"]:::compute
            Features["features_add.py"]:::compute
            Regression["linear_reg_with_features.py"]:::compute
        end
        subgraph "Modeling & Training"
            Notebooks["DataAnalysis/"]:::compute
        end
    end

    %% Service Layer
    subgraph "Service Layer"
        App["app.py"]:::service
        Stats["bucks_stats.py"]:::service
        UserData["user_data.py"]:::service
        Util["data.py"]:::service
    end

    %% Users
    Users["Users (Analysts, Marketing)"]:::user

    %% Data Flows
    RawCSV -->|"CSV"| Cleaning1
    Cleaning1 -->|"DataFrame"| Cleaning2
    Cleaning2 -->|"DataFrame"| Cleaning3
    Cleaning3 -->|"DataFrame"| Cleaning4
    Cleaning4 -->|"CSV"| CleanedFiles

    CleanedFiles -->|"CSV"| Features
    Features -->|"DataFrame"| Regression
    Regression -->|"DataFrame"| Notebooks
    Notebooks -->|"Pickle"| ModelStore

    ModelStore -->|"Load Model"| App
    App -->|"requests"| Stats
    App -->|"requests"| UserData
    App -->|"imports"| Util

    App -->|"Dashboard UI"| Users
    Users -->|"HTTP Requests"| App

    %% Click Events
    click Cleaning1 "https://github.com/chzou123/buckhack/blob/main/accountclean.py"
    click Cleaning2 "https://github.com/chzou123/buckhack/blob/main/dataclean.py"
    click Cleaning3 "https://github.com/chzou123/buckhack/blob/main/updateAccount.py"
    click Cleaning4 "https://github.com/chzou123/buckhack/blob/main/accountSort.py"
    click CleanedFiles "https://github.com/chzou123/buckhack/tree/main/cleanedfiles/"
    click Features "https://github.com/chzou123/buckhack/blob/main/features_add.py"
    click Regression "https://github.com/chzou123/buckhack/blob/main/linear_reg_with_features.py"
    click Notebooks "https://github.com/chzou123/buckhack/tree/main/DataAnalysis/"
    click App "https://github.com/chzou123/buckhack/blob/main/dashboard/app.py"
    click Stats "https://github.com/chzou123/buckhack/blob/main/dashboard/bucks_stats.py"
    click UserData "https://github.com/chzou123/buckhack/blob/main/dashboard/user_data.py"
    click Util "https://github.com/chzou123/buckhack/blob/main/data.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,stroke-width:1px;
    classDef compute fill:#d4edda,stroke:#155724,stroke-width:1px;
    classDef service fill:#ffeeba,stroke:#856404,stroke-width:1px;
    classDef user fill:#f8d7da,stroke:#721c24,stroke-width:1px;
```
