High Level Design - gcivil-nyu-org/team2-mon-fall26 GitHub Wiki

High Level Design

Connect NYC ยท Week 4 ยท E01 โ€” Finding a Wi-Fi Hotspot
High-level design ยท October 14, 2026

This design describes how E01's existing discovery and hotspot-information requirements are implemented by a browser, web application and database. The October 13โ€“19 development sprint covers full E01: map browsing, location search, all three filters, hotspot profiles and existing community feedback. Boqing Xin owns the Epic; Boqing Xin and Jiahao Lin implement its discovery and profile flows.

High Level Analysis ยท E01 Epic ยท Week 4 โ€” Sprint Plan

1. Scope and story traceability

Existing requirement Design coverage
US01 / #8 โ€” Interactive map Display official hotspot markers; selecting a marker shows basic location information.
US02 / #9 โ€” Location search Search by location/address; display related hotspots and their locations, or a no-results message. E01 also includes landmark search.
US03 / #10 โ€” Borough or neighborhood Select, change or remove an area filter; display matching markers or a no-results message.
US04 / #11 โ€” Provider Select, change or remove a provider filter; display matching markers or a no-results message.
US05 / #12 โ€” Hotspot type Select, change or remove a type filter; display matching markers or a no-results message.
US31 / #41 โ€” Hotspot profile and existing reviews Implement E01's profile-reading requirement using official information, existing reviews, average ratings from #22 and source labels from #28.
US09 / #19 โ€” Public browsing Browse the map, search, filter and read reviews without signing in.
US12 / #22 โ€” Average rating Display the average of hotspot star ratings; show โ€œNo ratings yetโ€ when no ratings exist.
US18 / #28 โ€” Source labels Label official information separately from community ratings/reviews.

Dependencies: E04 / US16 #26 supplies official records. E03 owns review data and rating aggregation. E01 consumes these through its profile display; the internal administration and contribution workflows are outside this design.

Official-data preparation, field mapping and ERD work are tracked in data task #42, owned by Kavya Mukewar and Suvan Amruth. This task supplies E01's data dependency; it does not include the full E04 administration workflow. Xiao Qi Lee handles acceptance checks, defect recording and demo verification through QA task #43.

Outside this design: registration, review creation/editing/deletion, discussion forums, moderation, availability reports, reliability scoring, favorites, notifications and configurable nearby-radius search.

An official hotspot record identifies a listed location; it does not establish current connectivity.

2. Architecture and component responsibilities

The proposed implementation uses one web application and one relational database. The request-handling and data-access responsibilities below are modules of that application. Framework and hosting products remain implementation choices.

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#000000','secondaryColor':'#ffffff','tertiaryColor':'#ffffff','clusterBkg':'#ffffff','clusterBorder':'#000000','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    UI["Browser UI: map, filters and hotspot profile"]
    API["Web application: discovery and profile reads"]
    DB[("Database: official hotspots and E03 review data")]
    IMPORT["Official-data import: E04 dependency"]
    NYC["NYC Open Data"]
    UI -->|Search and hotspot requests| API
    API -->|Read stored records| DB
    NYC --> IMPORT
    IMPORT -->|Official hotspot records| DB
    classDef mono fill:#fff,stroke:#000,color:#000;
    class UI,API,DB,IMPORT,NYC mono;

Figure 1: Component overview expressed as a Mermaid flowchart. E04 supplies official records; E01 performs discovery and profile reads.

Component Responsibility
Browser UI Display the map and filters, submit the selected search/filter operation, and display hotspot information.
Web application Process location/filter requests, retrieve hotspot profiles, and keep official and community information distinct.
Data access Retrieve matching official records and the information associated with a selected hotspot.
Database Store the official records supplied by E04 and the ratings/reviews managed by E03.
E04 import dependency Supply identifiable official records before E01 queries them, as specified by #26; E01's data preparation and mapping are tracked in #42.

The diagrams show requests against stored data. Map rendering and location matching are internal implementation responsibilities; no external provider is prescribed here.

3. User interaction

  1. A visitor opens the map without signing in and sees selectable official hotspot markers (#8, #19).
  2. The visitor searches by location/address or uses a borough/neighborhood, provider or type filter (#9โ€“#12).
  3. The map shows matching hotspots and their locations. Searches or filters with no matches display a clear message (#9โ€“#12).
  4. The visitor can change or remove a filter (#10โ€“#12).
  5. Selecting a hotspot marker displays its information. The profile includes existing reviews and average ratings, with official and community fields labeled separately (#41, #8, #22, #28).

4. UML sequence โ€” search and filter

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#000000','actorBkg':'#ffffff','actorBorder':'#000000','actorTextColor':'#000000','actorLineColor':'#000000','signalColor':'#000000','signalTextColor':'#000000','labelBoxBkgColor':'#ffffff','labelBoxBorderColor':'#000000','labelTextColor':'#000000','loopTextColor':'#000000','noteBkgColor':'#ffffff','noteBorderColor':'#000000','noteTextColor':'#000000','activationBkgColor':'#ffffff','activationBorderColor':'#000000'}}}%%
sequenceDiagram
    actor U as Visitor
    participant UI as Browser UI
    participant APP as Web application
    participant DB as Database
    U->>UI: Open map, search location, or change/remove a filter
    UI->>APP: Request hotspots for the selected operation
    APP->>DB: Find official hotspots matching the request
    DB-->>APP: Matching hotspot records
    APP-->>UI: Hotspot records and locations
    alt Matching hotspots exist
        UI-->>U: Show selectable hotspot markers and locations
    else Search or filter has no matches
        UI-->>U: Show no matching hotspots message
    end

Figure 2: Opening the map is covered by #8; location search and the three filter categories are covered by #9โ€“#12. Changing or removing a filter uses the same request path. Public access is covered by #19.

5. UML sequence โ€” view hotspot details

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#000000','actorBkg':'#ffffff','actorBorder':'#000000','actorTextColor':'#000000','actorLineColor':'#000000','signalColor':'#000000','signalTextColor':'#000000','labelBoxBkgColor':'#ffffff','labelBoxBorderColor':'#000000','labelTextColor':'#000000','loopTextColor':'#000000','noteBkgColor':'#ffffff','noteBorderColor':'#000000','noteTextColor':'#000000','activationBkgColor':'#ffffff','activationBorderColor':'#000000'}}}%%
sequenceDiagram
    actor U as Visitor
    participant UI as Browser UI
    participant APP as Web application
    participant DB as Database
    U->>UI: Select a hotspot marker
    UI->>APP: Request information for the selected hotspot
    APP->>DB: Read official hotspot information
    DB-->>APP: Official location and provider information
    APP->>DB: Read existing E03 reviews and rating summary
    DB-->>APP: Review text and average rating, if ratings exist
    APP-->>UI: Official information and community feedback
    UI-->>U: Show hotspot profile with source labels and reviews
    alt The hotspot has ratings
        UI-->>U: Show average star rating
    else The hotspot has no ratings
        UI-->>U: Show No ratings yet
    end

Figure 3: Marker selection and basic location information trace to #8. US31 / #41 implements E01's hotspot-profile and existing-review reading flow; #22 supplies the average-rating/no-rating behavior, #28 supplies source labels, and #19 permits anonymous reading. E03 owns the rating summary and review data consumed here.

A written review is optional when submitting a rating (#21). A hotspot can therefore have ratings without written reviews. โ€œNo ratings yetโ€ depends on the absence of ratings, not the absence of review text.

6. Data design and source transparency

The official source is NYC Wi-Fi Hotspot Locations.

Kavya Mukewar and Suvan Amruth own the source-field mapping and ERD in #42, including the relationship between a hotspot and its existing E03 ratings/reviews.

The proposed data representation supports fields already used by the stories:

Data Purpose and requirement
Hotspot identifier and official source identity Keep marker selections associated with the correct record and retain its source (#8, #26).
Name/location description and coordinates Locate official hotspots on the map and show location information (#8, #9, #26).
Borough/neighborhood, provider and hotspot type Support the existing filter stories (#10โ€“#12). Field coverage and vocabulary depend on the official data mapping.
Existing hotspot ratings and review text Supply #41's profile display through E03's rating/review data and #22's average rating; #21 defines the existing contribution data.
Official/community source labels Make the origin of displayed information clear (#28).

Average rating is calculated from hotspot star ratings under E03. An absent written review does not remove an otherwise valid rating from that calculation. If no ratings exist, the average is absent and the UI displays โ€œNo ratings yet.โ€ Forum content, helpfulness votes and availability reports do not enter the average.

7. Application read interfaces

The following are logical request boundaries for the sequence diagrams. Concrete URLs, parameter names and transport formats are implementation choices.

Read operation Input Result Requirement
Read map hotspots Initial map request Official hotspot records and locations #8
Search or filter hotspots Location/address or the selected filter operation Matching hotspots, or no matches #9โ€“#12
Read hotspot information Selected hotspot identifier Official information, existing reviews and average-rating status #41, #8, #22, #28

The application validates requests and handles failed data reads. An empty successful search is distinct from a failed request. These are technical responsibilities of the read interfaces.

8. Deployment view

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#000000','secondaryColor':'#ffffff','tertiaryColor':'#ffffff','clusterBkg':'#ffffff','clusterBorder':'#000000','edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    subgraph CLIENT["User device"]
        WEB["Browser: map and hotspot information"]
    end
    subgraph HOST["Proposed application hosting environment"]
        APP["Web application: UI assets and read requests"]
        STORE[("Relational database")]
        JOB["Official-data import: E04 dependency"]
        APP -->|Private connection| STORE
        JOB --> STORE
    end
    DATA["NYC Open Data"]
    WEB -->|HTTPS| APP
    JOB -->|Read official data| DATA
    classDef mono fill:#fff,stroke:#000,color:#000;
    class WEB,APP,STORE,JOB,DATA mono;

Figure 4: Deployment view expressed in Mermaid flowchart notation, with nodes grouped by runtime location.

The browser accesses the web application over HTTPS. Database access remains within the application environment; official data enters through E04's import capability. Connection credentials are held in configuration outside source control. The framework, database product and hosting provider remain open implementation choices.

9. Why these diagrams

  • UML sequence diagrams explain the order of requests and the responsibilities of the browser, application and database for existing E01 requirements.
  • Component overview identifies the main modules and E04 data dependency.
  • Deployment view identifies runtime locations and their connections.
  • No separate activity diagram in this version: the numbered user flow and sequence alternatives cover the selected interactions.
  • No detailed class diagram in this version: the data table and read interfaces describe the relevant data boundaries at this design level.

All diagrams use a black-and-white style for readability and consistency with the project Wiki.

10. Open design decisions

  1. Framework, database product, hosting environment and map-rendering implementation โ€” Boqing Xin and Jiahao Lin.
  2. Location/address/landmark matching for US02 โ€” Boqing Xin and Jiahao Lin.
  3. Official-data mapping for borough, neighborhood, provider and hotspot type, including source-field coverage and the ERD โ€” Kavya Mukewar and Suvan Amruth, tracked in #42.
  4. US31 / #41 integration with the existing E03 rating/review data and E04 source labels โ€” Boqing Xin and Jiahao Lin.

The Week 4 Sprint Plan records the selected full-E01 backlog for October 13โ€“19, responsibilities and the agreed Definition of Done.