# guilhermecf10/uerj-mat-discreta-2 architecture

> Architecture diagram of the GitHub repository guilhermecf10/uerj-mat-discreta-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guilhermecf10/uerj-mat-discreta-2
- Repository: https://github.com/guilhermecf10/uerj-mat-discreta-2

## Overview

##### Project Type and Purpose
- This is a CLI-driven data-analysis/ETL tool (not a full-stack web app).
- Purpose: scrape bus-stop data from Moovit, geocode stops, build a network graph, and render an interactive map.

##### Main Components
a. AppController (script/main.py)
– Orchestrates the workflow and handles CLI flags (force_rescrape, force_regeocode).
b. MoovitScraper (script/moovit_scraper.py)
– Fetches raw stop data from Moovit pages.
c. GeoCoder (script/geocoder.py)
– Calls Google Maps Geocoding API; enriches stops with lat/lon.
d. DataExporter (script/data_exporter.py)
– Reads/writes CSVs (raw vs. geocoded).
e. GraphBuilder & Analysis (script/graph_analysis.py)
– Constructs NetworkX DiGraph, computes distances, caching.
f. MapGenerator (part of graph_analysis.py)
– Produces interactive HTML map via Folium.
g. Cache & Data Stores
– `/script/cache/cached_moovit_graph.gpickle`
– `/script/data/*.csv`
h. External Services
– Moovit website (HTML pages)
– Google Maps Geocoding API
i. Tests (script/tests/…)
– Example inputs + expected outputs to validate scrapers and mapping.

##### Relationships & Data Flows
1. AppController invokes MoovitScraper → outputs `moovit_stops_raw.csv` → stored in `script/data`.
2. If force_regeocode or missing geocoded CSV, AppController calls GeoCoder → reads raw CSV → writes `moovit_stops_geocoded.csv`.
3. DataExporter abstracts CSV I/O between modules.
4. GraphBuilder reads geocoded CSV → checks for cached GPickle → if absent/forced, builds NetworkX DiGraph (nodes=stops, edges=connections) → writes cache.
5. MapGenerator reads graph → draws markers & edges → outputs `map_moovit_stops.html`.
6. AppController exits, returning path to map.
7. Tests invoke subsets of these modules with controlled data and validate HTML or map files.

##### Architectural Patterns & Principles
- Modular separation: each concern in its own module/class (Single Responsibility Principle).
- Pipeline/ETL flow: linear stages with caching at key points.
- Use of caching for idempotency and performance.
- CLI orchestration (flags to toggle pipelines).
- External-service abstraction (API key via ENV).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    MW["Moovit Website"]:::external
    GM["Google Geocoding API"]:::external

    %% Orchestration
    AC["AppController\n(main.py)"]:::python

    %% Processing Modules
    MS["MoovitScraper\n(moovit_scraper.py)"]:::python
    GC["GeoCoder\n(geocoder.py)"]:::python
    GB["GraphBuilder & Analysis\n(graph_analysis.py)"]:::python
    MG["MapGenerator\n(graph_analysis.py)"]:::python
    DE["DataExporter\n(data_exporter.py)"]:::python

    %% Data Stores
    RAW["moovit_stops_raw.csv"]:::data
    GEO_RAW["moovit_stops_geocoded.csv"]:::data
    GEO_FIL["moovit_stops_geocoded_filtered.csv"]:::data
    CACHE["cached_moovit_graph.gpickle"]:::data
    HTML["map_moovit_stops.html"]:::data

    %% Decision
    D{"force_regeocode?"}:::decision

    %% Workflow
    MW -->|HTML Pages| MS
    MS -->|"raw CSV"| RAW
    MS --> DE
    DE --> RAW
    AC -->|"run pipeline"| MS
    AC -->|"invoke exporter"| DE
    AC -->|"force_regeocode?"| D

    D -->|yes| GC
    D -->|no| GB

    GC --> DE
    DE --> GEO_RAW
    GC -->|"geocoded CSV"| GEO_RAW
    GC --> GM

    GEO_RAW --> GB
    GB -->|"check cache"| CACHE
    CACHE --> GB
    GB -->|"NetworkX Graph"| CACHE

    GB --> MG
    MG -->|"HTML map"| HTML

    AC --> HTML

    %% Tests
    subgraph "Test Suites" 
        subgraph "Optimization Tests" 
            OT_DRV["main.py"]:::test
            OT_MAP["map.html"]:::test
            OT_DOC["readme.md"]:::test
        end
        subgraph "Principal Carlos Marighella Tests"
            PC_DRV["main.py"]:::test
            PC_MAP["map.html"]:::test
            PC_DOC["readme.md"]:::test
        end
    end

    OT_DRV --> MS
    OT_DRV --> GB
    OT_DRV --> MG
    PC_DRV --> MS
    PC_DRV --> GB
    PC_DRV --> MG

    %% Click Events
    click AC "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/main.py"
    click MS "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/moovit_scraper.py"
    click GC "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/geocoder.py"
    click GB "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/graph_analysis.py"
    click MG "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/graph_analysis.py"
    click DE "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/data_exporter.py"
    click RAW "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/data/moovit_stops_raw.csv"
    click GEO_RAW "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/data/moovit_stops_geocoded.csv"
    click GEO_FIL "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/data/moovit_stops_geocoded_filtered.csv"
    click CACHE "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/cache/cached_moovit_graph.gpickle"
    click OT_DRV "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/otimizacao/main.py"
    click OT_MAP "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/otimizacao/map.html"
    click OT_DOC "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/otimizacao/readme.md"
    click PC_DRV "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/principal-carlos-marighella/main.py"
    click PC_MAP "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/principal-carlos-marighella/map.html"
    click PC_DOC "https://github.com/guilhermecf10/uerj-mat-discreta-2/blob/main/script/tests/principal-carlos-marighella/readme.md"

    %% Styles
    classDef python fill:#D3E5FF,stroke:#3182bd,color:#0b3d91,stroke-width:1px;
    classDef data fill:#FFE5B4,stroke:#de7d00,color:#663c00,stroke-width:1px;
    classDef external fill:#D8FFD8,stroke:#31a02c,color:#116611,stroke-width:1px;
    classDef decision fill:#FFD1DC,stroke:#e31a1c,color:#99000a,stroke-width:1px;
    classDef test fill:#EAD1DC,stroke:#6a3d9a,color:#3f007d,stroke-width:1px;
```
