# lucianono/shelteralloc_thesis architecture

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

- Interactive diagram: https://gitdiagram.com/lucianono/shelteralloc_thesis
- Repository: https://github.com/lucianono/shelteralloc_thesis

## Overview

##### Project type and purpose
- ShelterAlloc_Thesis is a standalone Python desktop application (built with PyQt/PySide) that reads community and shelter data from Excel, runs optimization (shelter‐allocation and routing), and produces reports (Excel & HTML maps).
- It is organized around a graphical UI, core optimization/modeling logic, a simple file‐based data layer (Excel + JSON cache), and report generation.

##### File structure
- Top‐level directories:
- DataSets – raw Excel data inputs (community, shelter, distance matrices)
- ProgramSrc – all source code, UI definitions (.ui), compiled resources, templates
- Tests – unit/functional tests for the optimization and various prototypes
- Thesis Final Manuscript / Thesis Proposal Manuscript – documentation (outside runtime scope)
- In ProgramSrc:
- UI layer: *.ui files + generated ui_*.py, index.py (app entry), main.py (PyInstaller spec)
- Controller modules: dashboard_ui.py, entityManagement*.py, helpDialog.py, solveSettings.py, solvingProgress.py
- Domain/Logic: DataSetsModel.py, distanceComputer.py, pathfinder.py, optimizedRouting.py, BNTModelPenalized.py
- Settings & config: modelSettings.py + .ui, solveSettings.py + .ui, cache folder (JSON)
- Reporting: shelterAllocationReport.py (Excel template), map.html & optimized-routes-map.html
- Resources: resources.qrc → resources_rc.py

##### README for insights
- README is minimal; project name confirms focus on “Shelter Allocation” as part of a thesis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        DashboardUIDef["dashboard.ui"]:::ui
        click DashboardUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/dashboard.ui"
        DashboardUIGen["ui_dashboard.py"]:::ui
        click DashboardUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_dashboard.py"
        EntityMgmtUIDef["entityManagement.ui"]:::ui
        click EntityMgmtUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/entityManagement.ui"
        EntityMgmtShelUIDef["entityManagementShelter.ui"]:::ui
        click EntityMgmtShelUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/entityManagementShelter.ui"
        EntityMgmtUIGen["ui_entityManagement.py"]:::ui
        click EntityMgmtUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_entityManagement.py"
        EntityMgmtShelUIGen["ui_entityManagementShelter.py"]:::ui
        click EntityMgmtShelUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_entityManagementShelter.py"
        HelpDialogUIDef["helpDialog.ui"]:::ui
        click HelpDialogUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/helpDialog.ui"
        HelpDialogUIGen["ui_helpDialog.py"]:::ui
        click HelpDialogUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_helpDialog.py"
        ModelSettingsUIDef["modelSettings.ui"]:::ui
        click ModelSettingsUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/modelSettings.ui"
        ModelSettingsUIGen["ui_modelSettings.py"]:::ui
        click ModelSettingsUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_modelSettings.py"
        SolveSettingsUIDef["solveSettings.ui"]:::ui
        click SolveSettingsUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/solveSettings.ui"
        SolveSettingsUIGen["ui_solveSettings.py"]:::ui
        click SolveSettingsUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_solveSettings.py"
        ProgrProgressUIDef["solvingprogress.ui"]:::ui
        click ProgrProgressUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/solvingprogress.ui"
        ProgrProgressUIGen["ui_solvingprogress.py"]:::ui
        click ProgrProgressUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_solvingprogress.py"
        ReportUIDef["shelterallocationreport.ui"]:::ui
        click ReportUIDef "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/shelterallocationreport.ui"
        ReportUIGen["ui_shelterallocationreport.py"]:::ui
        click ReportUIGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ui_shelterallocationreport.py"
        Entry["index.py"]:::ui
        click Entry "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/index.py"
        Spec["main.spec"]:::ui
        click Spec "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/main.spec"
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        DashboardCtrl["dashboard_ui.py"]:::controller
        click DashboardCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/dashboard_ui.py"
        EntityCommCtrl["entityManagementComm.py"]:::controller
        click EntityCommCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/entityManagementComm.py"
        EntityShelCtrl["entityManagementShelter.py"]:::controller
        click EntityShelCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/entityManagementShelter.py"
        HelpCtrl["helpDialog.py"]:::controller
        click HelpCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/helpDialog.py"
        SolveSettingsCtrl["solveSettings.py"]:::controller
        click SolveSettingsCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/solveSettings.py"
        ProgressCtrl["solvingProgress.py"]:::controller
        click ProgressCtrl "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/solvingProgress.py"
    end

    %% Core Engine / Business Logic
    subgraph "Core Engine / Business Logic"
        direction TB
        DataModel["DataSetsModel.py"]:::logic
        click DataModel "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/DataSetsModel.py"
        DistanceComp["distanceComputer.py"]:::logic
        click DistanceComp "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/distanceComputer.py"
        Pathfinder["pathfinder.py"]:::logic
        click Pathfinder "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/pathfinder.py"
        OptRouting["optimizedRouting.py"]:::logic
        click OptRouting "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/optimizedRouting.py"
        PenalizedModel["BNTModelPenalized.py"]:::logic
        click PenalizedModel "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/BNTModelPenalized.py"
        ModelSettingsLogic["modelSettings.py"]:::logic
        click ModelSettingsLogic "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/modelSettings.py"
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawExcel["DataSets/*.xlsx"]:::data
        click RawExcel "https://github.com/lucianono/shelteralloc_thesis/tree/main/DataSets/"
        CommExcel["commData.xlsx"]:::data
        click CommExcel "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/commData.xlsx"
        ShelExcel["shelData.xlsx"]:::data
        click ShelExcel "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/shelData.xlsx"
        DistExcel["distance_matrix.xlsx"]:::data
        click DistExcel "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/distance_matrix.xlsx"
        JSONCache["cache/*.json"]:::data
        click JSONCache "https://github.com/lucianono/shelteralloc_thesis/tree/main/ProgramSrc/cache/"
    end

    %% Reporting Layer
    subgraph "Reporting Layer"
        direction TB
        ReportGen["shelterAllocationReport.py"]:::report
        click ReportGen "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/shelterAllocationReport.py"
        ReportTemplate["ReportTemplate.xlsx"]:::report
        click ReportTemplate "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/ReportTemplate.xlsx"
        MapHTML["map.html"]:::report
        click MapHTML "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/map.html"
        OptMapHTML["optimized-routes-map.html"]:::report
        click OptMapHTML "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/optimized-routes-map.html"
        AllocResults["allocation_results.xlsx"]:::report
        click AllocResults "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/allocation_results.xlsx"
    end

    %% Resources
    subgraph "Resources"
        direction TB
        QRC["resources.qrc"]:::external
        click QRC "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/resources.qrc"
        RC["resources_rc.py"]:::external
        click RC "https://github.com/lucianono/shelteralloc_thesis/blob/main/ProgramSrc/resources_rc.py"
        Icons["ICONS/"]:::external
        click Icons "https://github.com/lucianono/shelteralloc_thesis/tree/main/ProgramSrc/ICONS/"
    end

    %% Flows
    UI -->|interacts| DashboardCtrl
    UI -->|interacts| EntityCommCtrl
    UI -->|interacts| HelpCtrl
    DashboardCtrl -->|calls| DataModel
    EntityCommCtrl -->|calls| DataModel
    SolveSettingsCtrl -->|adjusts| ModelSettingsLogic
    ProgressCtrl -->|updates| Pathfinder
    DataModel -->|reads| RawExcel
    DataModel -->|reads| CommExcel
    DataModel -->|reads| ShelExcel
    DistanceComp -->|computes| DistExcel
    Pathfinder -->|routes via| DistanceComp
    OptRouting -->|optimizes via| PenalizedModel
    PenalizedModel -->|caches| JSONCache
    OptRouting -->|outputs| AllocResults
    OptRouting -->|for reporting| ReportGen
    ReportGen -->|uses template| ReportTemplate
    ReportGen -->|generates| AllocResults
    MapHTML -->|"visualizes"| AllocResults
    OptMapHTML -->|"visualizes"| AllocResults
    DashboardCtrl -->|displays| MapHTML
    ReportUIGen -->|embeds| AllocResults

    %% Legend
    subgraph "Legend"
        UIComp["UI Components"]:::ui
        CtrlComp["Controller Modules"]:::controller
        LogicComp["Business Logic"]:::logic
        DataComp["Data Stores"]:::data
        ReportComp["Reporting"]:::report
        ExtComp["External/Resources"]:::external
    end

    classDef ui fill:#DCF1FF,stroke:#0366D6;
    classDef controller fill:#FFF5BA,stroke:#BF8700;
    classDef logic fill:#E2F5D7,stroke:#2E7D32;
    classDef data fill:#F0FFF0,stroke:#388E3C;
    classDef report fill:#FFE5D4,stroke:#D84315;
    classDef external fill:#F5F5F5,stroke:#9E9E9E;
```
