# shelterassociates/shelter architecture

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

- Interactive diagram: https://gitdiagram.com/shelterassociates/shelter
- Repository: https://github.com/shelterassociates/shelter

## Overview

##### Project type and purpose
- This is a full-stack, monolithic Django web application (“shelter” project) for data collection, mapping, reporting and analysis in urban slum contexts.
- It integrates GIS/KML parsing, form surveys (via KoBoToolbox/Avni), dashboards/graphs, and BIRT-based report generation.

##### File structure
- Top-level Django project:
- shelter/  – settings.py, urls.py, wsgi.py
- manage.py
- Six core Django apps, each encapsulating a domain:
- component – KML parsing, KoBo sync, form handling, APIs, cipher utilities
- master – slum mapping, GIS widget integration, Drupal data import
- graphs – data analysis, dashboard card generation, JSON mappings, sync scripts
- mastersheet – accounting/daily reporting sync, Excel export
- sponsor – sponsor management and BIRT fact-sheet integration
- filter – simple model/view filtering utilities
- DBScripts/ – PostgreSQL view definitions and SQL scripts
- ReportFile/ & reports/ – BIRT .rptdesign templates for fact sheets & reports
- deploy/ & scripts/ – shell and Python scripts for data sync (AVNI, KoBo), migrations, image compression, cron jobs
- static/ & templates/ – CSS/JS/images, HTML/Django templates for UI
- requirement.txt & package.json – Python and JS dependencies

##### README
- Confirms use of Python virtualenv, PostgreSQL, Django migrations, and `runserver`.

##### Detail
- Break out each Django app as a separate subcomponent, showing which scripts or templates it manages.
- How deploy/cron scripts trigger data ingestion into the DB.
- How BIRT templates map to DB views (DBScripts/) to generate reports.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Web Browser"]:::external
        StaticAssets["Static Assets"]:::infra
    end

    %% Web Layer
    subgraph "Web Layer"
        Nginx["Nginx"]:::infra
        WSGI["Gunicorn/WSGI"]:::infra
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Django Core"
            Manage["manage.py"]:::infra
            Core["shelter/"]:::backend
        end
        subgraph "Django Apps"
            Component["Component App"]:::backend
            Master["Master App"]:::backend
            Graphs["Graphs App"]:::backend
            Mastersheet["Mastersheet App"]:::backend
            Sponsor["Sponsor App"]:::backend
            FilterApp["Filter App"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        PostgreSQL["PostgreSQL DB"]:::data
        DBScripts["DBScripts/ (SQL Views)"]:::data
    end

    %% Reporting Layer
    subgraph "Reporting Layer"
        BIRTEngine["BIRT Engine"]:::infra
        ReportFile["ReportFile/ Templates"]:::data
        Reports["reports/ Templates"]:::data
    end

    %% External Services
    subgraph "External Services"
        KoBo["KoBoToolbox API"]:::external
        Avni["Avni Data API"]:::external
        Drupal["Drupal Endpoint"]:::external
    end

    %% Deployment & Sync
    subgraph "Deployment & Sync"
        Deploy["deploy/ Scripts"]:::infra
        Scripts["scripts/"]:::infra
    end

    %% Global Templates
    Templates["templates/"]:::infra

    %% Connections
    Browser -->|"HTTP GET"| Nginx
    StaticAssets -->|Serves CSS/JS| Browser

    Nginx -->|"Pass Request"| WSGI
    WSGI -->|"Invoke manage.py"| Manage
    Manage -->|"Load Core"| Core
    Core -->|"Route to Apps"| Component
    Core --> Master
    Core --> Graphs
    Core --> Mastersheet
    Core --> Sponsor
    Core --> FilterApp

    Component -->|"Write/Read"| PostgreSQL
    Component -->|"Fetch Survey Data"| KoBo
    Component -->|"Fetch Survey Data"| Avni

    Master -->|"Write/Read"| PostgreSQL
    Master -->|"Import Data"| Drupal

    Graphs -->|"Query Data"| PostgreSQL
    Graphs -->|"Sync Data"| Avni
    Graphs -->|"Sync Data"| KoBo

    Mastersheet -->|"Sync Reporting"| PostgreSQL

    Sponsor -->|"Read/Write"| PostgreSQL
    Sponsor -->|"Generate Reports"| BIRTEngine

    FilterApp -->|"Filter Queries"| PostgreSQL

    BIRTEngine -->|"Query Views"| PostgreSQL
    BIRTEngine -->|"Load Templates"| ReportFile
    BIRTEngine -->|"Load Templates"| Reports
    BIRTEngine -->|PDF/HTML| Browser

    Deploy -->|"Cron Triggers"| Component
    Deploy --> Scripts
    Scripts -->|"ETL"| PostgreSQL

    Templates --> Core
    Templates --> Component
    Templates --> Master
    Templates --> Graphs
    Templates --> Mastersheet
    Templates --> Sponsor
    Templates --> FilterApp

    %% Click Events
    click Core "https://github.com/shelterassociates/shelter/tree/master/shelter/"
    click Manage "https://github.com/shelterassociates/shelter/blob/master/manage.py"
    click Component "https://github.com/shelterassociates/shelter/tree/master/component/"
    click Master "https://github.com/shelterassociates/shelter/tree/master/master/"
    click Graphs "https://github.com/shelterassociates/shelter/tree/master/graphs/"
    click Mastersheet "https://github.com/shelterassociates/shelter/tree/master/mastersheet/"
    click Sponsor "https://github.com/shelterassociates/shelter/tree/master/sponsor/"
    click FilterApp "https://github.com/shelterassociates/shelter/tree/master/filter/"
    click DBScripts "https://github.com/shelterassociates/shelter/tree/master/DBScripts/"
    click ReportFile "https://github.com/shelterassociates/shelter/tree/master/ReportFile/"
    click Reports "https://github.com/shelterassociates/shelter/tree/master/reports/"
    click Deploy "https://github.com/shelterassociates/shelter/tree/master/deploy/"
    click Scripts "https://github.com/shelterassociates/shelter/tree/master/scripts/"
    click StaticAssets "https://github.com/shelterassociates/shelter/tree/master/static/"
    click Templates "https://github.com/shelterassociates/shelter/tree/master/templates/"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
