# vida-nyu/urban-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/vida-nyu/urban-pulse
- Repository: https://github.com/vida-nyu/urban-pulse

## Overview

##### Project type and purpose
- Urban Pulse is a hybrid system combining an offline batch data‐processing pipeline (in C++ and Java) with an interactive web visualization client (in Angular).

##### File structure
- Top‐level directories:
- ComputePulse – the core processing framework
– Pulse/ (Java computational-topology code under `hope.it.works.ct` and related packages)
– PulseJNI/ (C++ JNI wrappers to invoke Java topology functions)
– Scalars/ (C++ module to compute scalar functions from CSV)
– common/ (shared C++ utilities)
– build.xml (Ant script for Java)
– ComputePulse.pro (Qt project file for C++ executables)
- vis – Angular 5+ web client (TypeScript/HTML/CSS)
- Build/config files: Ant build.xml, qmake `.pro` files, package.json, tsconfig.json.

##### Extract architecture insights from the README
- Two command-line tools:
- Scalars – reads CSV, outputs multi‐resolution scalar data (writes to `vis/src/data/...`).
- Pulse – loads scalar data (JSON), uses Java topology library (TopoFeatures.jar) via JNI to compute pulses, outputs JSON.
- Visualization: Angular app served by `ng serve` (Node.js), consumes JSON files under `vis/src/data/...`.

##### Main components and their interactions
a. Components:
1. Raw Data (CSV files)
2. Scalars Module (C++ CLI)
3. Pulse Module (C++ CLI + JNI)
4. Java Computational Topology Library (TopoFeatures.jar, with classes in `hope.it.works.ct`)
5. Shared C++ Utilities (`common/`)
6. Output Data Store (JSON files in `vis/src/data/...`)
7. Web Client (Angular app, Node.js development server)
8. User Interfaces:
– CLI terminal (runs `./Scalars`, `./Pulse`)
– Browser (views `http://localhost:4200`)
b. Relationships & data flow:
- CSV → Scalars → scalar JSON outputs
- scalar JSON → Pulse → pulse JSON outputs
- JSON files ↔ served by Node.js → Angular front end → Browser UI
- Pulse module ← JNI wrapper ← TopoFeatures.jar ← Java CT code
c. Architectural patterns and design principles:
- Modular, pipeline architecture for offline data processing
- N-tier separation: data ingestion & processing vs. visualization
- JNI bridging pattern between C++ and Java
- CLI tools for automation; no long-running backend service
- Front end adheres to component-based design (Angular modules/components)
d. Key technologies/frameworks:
- C++11, Qt (qmake)
- Java 8, Ant
- JNI (PulseJNI)
- Angular, TypeScript, Node.js, NPM

##### Elements to include for maximum clarity
- Notes on required external tools (Qt, Ant, Node.js).
- Optionally, illustrate build tools and commands under each module.

## Diagram (Mermaid)

```mermaid
flowchart TB
  DataRaw["Raw Data\n(CSV)"]:::data

  subgraph "Offline Processing"
    ScalarModule["Scalars Module\n(C++ CLI)"]:::compute
    subgraph "Scalars Files"
      GS["GenerateScalars.cpp"]:::file
      SFcpp["ScalarFunction.cpp"]:::file
      SFhpp["ScalarFunction.hpp"]:::file
      SP["Scalars.pro"]:::file
    end
    Common["Common Utilities\n(C++ Shared)"]:::compute
    subgraph "Common Files"
      CUcpp["utils.cpp"]:::file
      CUhpp["utils.hpp"]:::file
    end
    PulseModule["Pulse Module\n(C++ CLI + JNI)"]:::compute
    subgraph "PulseJNI Files"
      GP["GeneratePulse.cpp"]:::file
      Pcpp["Pulse.cpp"]:::file
      Phpp["Pulse.hpp"]:::file
      TFcpp["TopologicalFeatures.cpp"]:::file
      TFhpp["TopologicalFeatures.hpp"]:::file
      PP["Pulse.pro"]:::file
    end
    JNIBridge["JNI Bridge\n(PulseJNI)"]:::jni
    JavaLib["TopoFeatures.jar\n(Java CT)"]:::java
    subgraph "Java CT Files"
      BJ["Branch.java"]:::file
      FJ["Function.java"]:::file
    end
  end

  subgraph "Interactive Visualization"
    JSON["JSON Data Store\n(vis/src/assets)"]:::data
    Node["Node.js Dev Server\n(ng serve)"]:::web
    AngularApp["Angular App\n(TypeScript)"]:::web
    subgraph "Web Client Files"
      AM["app.module.ts"]:::file
      AMat["app-material.module.ts"]:::file
      Main["main.component.ts/html"]:::file
      Map["map.component.ts/html"]:::file
      VisC["vis.component.ts/html"]:::file
      EndIndex["index.html"]:::file
      Styles["styles.css"]:::file
      Poly["polyfills.ts"]:::file
      Sys["systemjs.config.js"]:::file
    end
    Browser["Browser UI"]:::ui
  end

  DataRaw -->|"ingest CSV"| ScalarModule
  Common --> ScalarModule
  ScalarModule -->|"compute scalar data"| JSON
  JSON -->|"scalar JSON input"| PulseModule
  Common --> PulseModule
  PulseModule -->|"invoke JNI"| JNIBridge
  JNIBridge -->|"calls Java CT"| JavaLib
  JavaLib -->|"return features"| PulseModule
  PulseModule -->|"compute pulses JSON"| JSON
  JSON -->|"serve JSON over HTTP"| Node
  Node -->|"serve assets"| AngularApp
  AngularApp -->|"render UI"| Browser

  click GS "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Scalars/GenerateScalars.cpp"
  click SFcpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Scalars/ScalarFunction.cpp"
  click SFhpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Scalars/ScalarFunction.hpp"
  click SP "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Scalars/Scalars.pro"
  click CUcpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/common/utils.cpp"
  click CUhpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/common/utils.hpp"
  click GP "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/GeneratePulse.cpp"
  click Pcpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/Pulse.cpp"
  click Phpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/Pulse.hpp"
  click TFcpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/TopologicalFeatures.cpp"
  click TFhpp "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/TopologicalFeatures.hpp"
  click PP "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/PulseJNI/Pulse.pro"
  click BJ "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Pulse/src/hope/it/works/ct/Branch.java"
  click FJ "https://github.com/vida-nyu/urban-pulse/blob/master/ComputePulse/Pulse/src/hope/it/works/ct/Function.java"
  click AM "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/app/app.module.ts"
  click AMat "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/app/app-material.module.ts"
  click Main "https://github.com/vida-nyu/urban-pulse/tree/master/vis/src/app/components/main/main.component.ts/html"
  click Map "https://github.com/vida-nyu/urban-pulse/tree/master/vis/src/app/components/map/map.component.ts/html"
  click VisC "https://github.com/vida-nyu/urban-pulse/tree/master/vis/src/app/components/vis/vis.component.ts/html"
  click EndIndex "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/index.html"
  click Styles "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/styles.css"
  click Poly "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/polyfills.ts"
  click Sys "https://github.com/vida-nyu/urban-pulse/blob/master/vis/src/systemjs.config.js"

  classDef compute fill:#D0E1F9,stroke:#333,stroke-width:1px
  classDef java fill:#E1D0F9,stroke:#333,stroke-width:1px
  classDef jni fill:#D8BFD8,stroke:#333,stroke-width:1px
  classDef web fill:#D0F9E1,stroke:#333,stroke-width:1px
  classDef data fill:#F9F0D0,stroke:#333,stroke-width:1px
  classDef file fill:#FFFFFF,stroke:#666,stroke-width:1px
  classDef ui fill:#C8C8C8,stroke:#333,stroke-width:1px
```
