# markongithub/clever_buses_py architecture

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

- Interactive diagram: https://gitdiagram.com/markongithub/clever_buses_py
- Repository: https://github.com/markongithub/clever_buses_py

## Overview

##### Project type and purpose
- From the file tree and README, “clever_buses_py” is a Python-based data-processing and reporting tool. Its primary purpose is to parse input data (e.g. Clever XML or Parquet), compute metrics (wait times, trip quantities), and output reports (CSV, Parquet, TXT, HTML, plots).
- There is no frontend web UI or microservice network; instead, this is a command-line/CLI pipeline that reads raw data, transforms it, and emits analysis outputs and documentation.

##### File structure
- Top-level scripts:
- parse_clever_xml.py – ingestion of XML data
- separate_trips.py – splitting or filtering trip data
- calculate_wait_times.py – computing wait-time metrics
- state_fair_quantities.py – aggregating trip quantities for “state_fair” context
- state_fair_report.py – composing final text or tabular report
- graph_wait_times.ipynb – exploratory analysis & plotting
- Configuration / dependencies:
- Pipfile & Pipfile.lock – defines Python runtime & libraries (likely pandas, plotly, etc.)
- .gitignore
- Output directories:
- output/ – final .txt, .csv, .parquet artifacts
- docs/ – Jekyll (or MkDocs) source for project documentation and embedded HTML snippets
- test_data/ – sample inputs for testing or CI
- Patterns: a simple data pipeline with discrete stages (ingest → transform → analyze → report).

##### README for additional insights
- The README is minimal, so architecture must be inferred from code and docs folder. The docs subfolder and HTML includes show that the project also exposes snippets and example outputs for documentation purposes.

##### Final advice
- How intermediate files in output/ feed into subsequent stages.
- Docs pipeline separately to illustrate how HTML includes are assembled into final docs.
- Test_data directory and any automated test or CI process as a validating component upstream of each stage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Raw Input
    TestData["Raw Input Data Store\ntest_data/"]:::datastore
    ExternalXML["External XML Feed"]:::datastore

    %% Configuration
    subgraph "Configuration"
        Pipfile["Pipfile & Pipfile.lock"]:::config
        Readme["Project README\nREADME.md"]:::config
        Gitignore["Git Ignore Rules\n.gitignore"]:::config
    end

    %% ETL Pipeline
    CLI["CLI Entry Point\n(user runs scripts)"]:::python

    Ingest["Ingestion:\nparse_clever_xml.py"]:::python
    SepTrips["Transform:\nseparate_trips.py"]:::python
    CalcWait["Transform:\ncalculate_wait_times.py"]:::python
    StateFairAgg["Transform:\nstate_fair_quantities.py"]:::python
    Report["Reporting:\nstate_fair_report.py"]:::python
    Graph["Reporting:\ngraph_wait_times.ipynb"]:::python

    %% Output
    OutputStore["Output Artifacts Store\noutput/"]:::datastore

    %% Documentation
    subgraph "Documentation Site Generator"
        Config["Jekyll/MkDocs Config\ndocs/_config.yml"]:::docs
        DocsIncludes["HTML Includes\ndocs/_includes/"]:::docs
        DocsSource["Site Source Pages\ndocs/state_fair_2024/index.md"]:::docs
    end

    %% Flow
    TestData -->|XML/Parquet| Ingest
    ExternalXML -->|XML| Ingest
    Ingest -->|DataFrame| SepTrips
    SepTrips -->|Trips CSV/Parquet| CalcWait
    CalcWait -->|Wait Times DataFrame| StateFairAgg
    StateFairAgg -->|Aggregated Metrics| Report
    StateFairAgg -->|Aggregated Metrics| Graph
    Report -->|TXT/CSV| OutputStore
    Graph -->|Plots/HTML| OutputStore

    %% Docs Flow
    DocsSource -->|Markdown pages| DocsIncludes
    DocsIncludes -->|HTML snippets| Config

    %% CLI usage
    CLI --> Ingest
    CLI --> SepTrips
    CLI --> CalcWait
    CLI --> StateFairAgg
    CLI --> Report
    CLI --> Graph

    %% Config links
    Pipfile --> CLI
    Readme --> CLI
    Gitignore --> CLI

    %% Click Events
    click Ingest "https://github.com/markongithub/clever_buses_py/blob/main/parse_clever_xml.py"
    click SepTrips "https://github.com/markongithub/clever_buses_py/blob/main/separate_trips.py"
    click CalcWait "https://github.com/markongithub/clever_buses_py/blob/main/calculate_wait_times.py"
    click StateFairAgg "https://github.com/markongithub/clever_buses_py/blob/main/state_fair_quantities.py"
    click Report "https://github.com/markongithub/clever_buses_py/blob/main/state_fair_report.py"
    click Graph "https://github.com/markongithub/clever_buses_py/blob/main/graph_wait_times.ipynb"
    click TestData "https://github.com/markongithub/clever_buses_py/tree/main/test_data/"
    click OutputStore "https://github.com/markongithub/clever_buses_py/tree/main/output/"
    click Config "https://github.com/markongithub/clever_buses_py/blob/main/docs/_config.yml"
    click DocsIncludes "https://github.com/markongithub/clever_buses_py/tree/main/docs/_includes/"
    click DocsSource "https://github.com/markongithub/clever_buses_py/blob/main/docs/state_fair_2024/index.md"
    click Pipfile "https://github.com/markongithub/clever_buses_py/tree/main/Pipfile"
    click Readme "https://github.com/markongithub/clever_buses_py/blob/main/README.md"
    click Gitignore "https://github.com/markongithub/clever_buses_py/blob/main/.gitignore"

    %% Styles
    classDef python fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef datastore fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef docs fill:#FDEBD0,stroke:#E67E22,color:#7E5109;
    classDef config fill:#E5E7E9,stroke:#7F8C8D,color:#2C3E50;
```
