# eparirishit/clean-and-green-philly architecture

> Architecture diagram of the GitHub repository eparirishit/clean-and-green-philly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eparirishit/clean-and-green-philly
- Repository: https://github.com/eparirishit/clean-and-green-philly

## Overview

##### A client‐facing web application built with React, NextJS, and Tailwind CSS.
2. A Python-powered data engineering pipeline (including ETL processes) that handles data ingestion, transformation, and possibly some computational steps (with some C++ integrations in the “awkde” module) to support the dashboard’s functionality.

The overall purpose is to empower community groups by providing a dashboard that helps identify vacant properties where cleaning and greening interventions can reduce gun violence in Philadelphia. The system relies on both a modern web frontend for data visualization and user interaction, as well as backend data pipelines for ETL and processing of public datasets that drive decision making.

##### Main Components & Their Roles
- Frontend (Client Web App):
– Built using React and NextJS, organized in the “src/app” folder.
– Contains pages, components (map, property details, informational content), styling (Tailwind CSS), and utilities.
– Acts as the primary interface for users, handling navigation, interactive maps, and property information.
- Backend Data Pipeline:
– Located mainly in the “data/src” directory. This module includes ETL code, data utilities, configuration files, and tests.
– Contains submodules such as “new_etl” and “awkde” (which even integrates C++ via “cpp/backend.cpp”) to process and enhance the data.
– Prepares datasets, runs data transformations, and may update the underlying database tables.
- Database:
– Dockerfiles (Dockerfile, Dockerfile-pg, Dockerfile-timescale) and SQL scripts (init_pg.sql, init_pg_timescale.sql) indicate that PostgreSQL (and possibly TimescaleDB for time-series optimizations) are used.
– Acts as persistent storage for the cleaned, processed data that the frontend displays.

##### Infrastructure and DevOps Components
- Docker & Containerization:
– The “data” folder contains Dockerfiles and a “docker-compose.yml” that likely orchestrates running the database containers and associated back-end services.
- Testing and CI/CD Pipelines:
– The presence of a “.github” folder with configuration for GitHub Actions and additional workflows (e.g., pr_checks, release workflows) indicates automated testing, linting, and release management processes.
- Configuration & Build Tools:
– ESLint and Prettier configuration, TypeScript configurations (tsconfig.json), and front-end build configurations (next.config.js) illustrate that the project is set up with best practices in code quality and build processes.

##### Relationships and Data Flow
- The Frontend sends user interactions (map requests, property queries) likely via API calls (either directly or through server-side fetching in NextJS) which retrieve data from the backend.
- The Python ETL pipeline (running as scheduled jobs or manual triggers) consumes raw public data, processes it (potentially using both Python modules and C++ acceleration in “awkde”), and then updates the PostgreSQL/Timescale databases.
- The database then serves as a data source for the web application, perhaps via API routes (either embedded in NextJS or as a separate API service).
- DevOps pipelines (CI/CD through GitHub Actions) ensure tests and build steps are executed, which then drive deployments for both the React app and the Python backend.

##### Architectural Design Principles
- Separation of Concerns: Clear split between frontend (display and interaction) and backend (data processing and storage).
- Containerization: Use of Docker and docker-compose helps isolate the database and possibly the ETL process.
- Modular Design: Within the Python pipeline, directories are neatly organized into “data_utils”, “classes”, “new_etl”, etc., emphasizing modular, reusable components.
- Automated Testing & CI: Testing directories (e.g., “data/src/test”) and GitHub workflows ensure that quality is enforced throughout the development lifecycle.

## Diagram (Mermaid)

```mermaid
graph TD
    DASH["Clean & Green Philly Dashboard"]:::dashboard

    subgraph "Frontend Layer"
        FE1["NextJS/React App"]:::frontend
        FE2["Pages & Components"]:::frontend
        FE3["Tailwind CSS Styling"]:::frontend
    end

    subgraph "Backend Layer"
        BE1["Python ETL Pipeline"]:::backend
        BE2["new_etl Module"]:::backend
        BE3["Data Utilities"]:::backend
        BE4["awkde Module (C++ integration)"]:::backend
    end

    subgraph "Database Layer"
        DB["Database (PostgreSQL & Timescale)"]:::database
    end

    subgraph "Infrastructure"
        INF1["Docker Infrastructure"]:::infra
        INF2["CI/CD Pipeline"]:::infra
    end

    DASH -->|"UI"| FE1
    FE1 -->|"API_Calls"| DB
    DASH -->|"ETL_Trigger"| BE1
    BE1 -->|"ETL_Updates"| DB
    BE1 -->|"contains"| BE2
    BE1 -->|"contains"| BE3
    BE1 -->|"contains"| BE4
    INF1 -->|"orchestrates"| FE1
    INF1 -->|"orchestrates"| BE1
    INF2 -->|"deploys"| FE1
    INF2 -->|"deploys"| BE1

    click FE1 "https://github.com/eparirishit/clean-and-green-philly/blob/main/src/app/layout.tsx"
    click BE2 "https://github.com/eparirishit/clean-and-green-philly/blob/main/data/src/new_etl/loaders.py"
    click BE3 "https://github.com/eparirishit/clean-and-green-philly/blob/main/data/src/data_utils/utils.py"
    click BE4 "https://github.com/eparirishit/clean-and-green-philly/blob/main/data/src/awkde/cpp/backend.cpp"
    click INF1 "https://github.com/eparirishit/clean-and-green-philly/blob/main/data/docker-compose.yml"
    click INF2 "https://github.com/eparirishit/clean-and-green-philly/blob/main/.github/workflows/pr_checks.yaml"
    click DB "https://github.com/eparirishit/clean-and-green-philly/blob/main/data/init_pg.sql"

    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef dashboard fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
