@shipt/geo-map

Geo Map

Geo Map is a standalone web application for mapping a shopper engagement session to better track current shopper location and provide ETAs.

The service in this repo implements a simple API that calls out to other services such as shopper engagement, metropolis, and geo to retrieve appropriate data.

Project Structure

  assets
  └── mocked backend data
  cmd
  └── geo-map
      └── service entrypoint
  internal
  ├── models
  │   └── models for creating a geo map
  ├── services
  │   ├── geo
  │   │   └── returns polyline between shopper and their next location
  │   ├── geomap
  │   │   └── calls other services and maps geomap models
  │   ├── metropolis
  │   │   └── returns store icon images
  │   └── shopperengagement
  │       └── returns most recent shopper engagement session
  ├── test
  │   └──unit/integration test
  ├── webserver
  │   ├── geomap
  │   │   ├── http.Handler for geomap
  │   ├── health
  │   │   └── http.Handler implementing a service liveness/readiness api
  │   └── a basic webserver with a couple of handlers
  └── worker
      └── a placeholder worker
  src
  ├── components
  │   ├── google
  │   │   └── components used in Google Map component
  │   └── Google, Mapbox, and error page components
  ├── mocks
  │   └── frontend mock server and mock files
  ├── model
  │   └── frontend geomap models
  ├── pages
  │   └── various pages
  └── styles
      └── dark mode style sheets
     

Table of Contents

• Geo Map
  • Project Structure
  • Table of Contents
  • Maintainers
  • Slack Channel
  • Overview
    • Architecture
    • Dependencies
  • Deployment and Configuration
    • Logging
    • Versioning
    • CI/CD
• Developer Details
  • Installation
    • Development Environment
    • Environmental Variables
  • File Linting
  • Git, Pull Requests and Reviews Process
  • Testing

Maintainers

• Jimmy Fu
• Bianca Jemison
• Kaitlyn Peterson

Slack Channel

• Squad Atlas Collective: #squad-atlas-collective
• Engineering Geo Map: #eng-geo-map
• Lounge Geo Experience #lounge-geo-experience

Overview

Geo Map is a standalone web application for mapping a shopper engagement session to better track current shopper location and provide ETAs.

The service in this repo implements a simple API that calls out to other services such as shopper engagement, metropolis, and geo to retrieve appropriate data.

Architecture

Add architecture diagram

Dependencies

• Shopper engagement
• Metropolis
• Geo
• Google Map API
• Mapbox Map API

Deployment and Configuration

Environmental Variables

• Frontend .env.local

  BACKEND_URL=http://localhost:8080
  API_MOCKING=enabled
  
  

• Backend .env.json

  Run the following command to generate the .env.json file with default dev environment variables:

  go run cmd/geo-map/main.go

Logging

All logs are emitted to Scalyr in a structured JSON format. The best way to get to the logs is through Kubedashian.

Versioning

v{MAJOR}.{MINOR}.{PATCH} Increment the MAJOR version when you make incompatible API changes. We should generally not be making breaking API changes, so this should be a rare occurrence. Increment the MINOR version when you add functionality in a backwards-compatible manner. Increment the PATCH version when you make backwards-compatible bug fixes.

CI/CD

On every git pull request and git push, tests are executed in Drone.

Developer Details

Installation

• Golang 1.16.3 - Installation
• Docker Desktop - Installation
• golangci-lint - To install, run: `brew install golangci-lint

Development Environment

Local Shell

To properly develop and run code in this project, you need to set the correct ENV variables in your shell environment .zshrc/.bashrc/.profile file. This is needed to pull private code dependencies. You'll need to make sure you have generated an access token for NPM and have a GitHub Token with Single Sign-on enabled for it.

To generate a Github Token with Single Sign-on, please check how to generate one on this TechHub page.

If you know you don't have access to Shipt npm registry, then you'll need to reach out to #ask-info-sec to request an invitation before continuing.

Once you have access to NPM, you can generate a read-only token. See the NPM documentation if you're unsure how to do this. If you're a frontend engineer and believe you may need to publish to NPM in the future, you may want to generate an access token that can Publish rather than read-only.

Now make sure to place the two values in your shell environment:

• GITHUB_TOKEN
• NPM_TOKEN

Create a fresh command line instance after saving these values before continuing to the next steps.

Backend

The first step in getting your local development environment running is to spin up local versions of external dependencies. We use docker-compose to manage these, and you can bring them up by running the following command:

$ docker-compose up -d

Now you should be able to run the webserver.

$ go run cmd/geo-map/main.go webserver
...
$ curl -v http://localhost:8080/v1/geomap/{shopperID}

Frontend

If you wish to use Yarn, Install by running the following:

brew install yarn

To install Yarn dependencies run:

yarn install

After running the webserver, spin up the development environment with yarn dev. Now you will be able to run the frontend with the following URL:

http://localhost:3000/{shopperID}

There are two optional parameters. The mode parameter specifies dark or light, and defaults to light mode. The `provider' parameter dictates map provider (google or mapbox) and defaults to google. For example:

http://localhost:3000/{shopperID}?mode=darkMode&provider=mapbox

Mock Server

For frontend development, you can use mock data rather than running the backend.

Edit the .env.local file to enable mocking, as shown below:

API_MOCKING=enabled

The possible mock pages can be found in the file:

geo-map/src/mocks/handlers.ts

To create additional mock pages, edit the handlers.ts file to include another option under the results header, and add an additional if-statement under handlers.

Using the mock as your shopper ID, use the frontend URL for development.

File Linting

We recommend you use golangci-lint for source code linting. A linting pass will be run as part of the CI pipeline on any branch push.

Git, Pull Requests and Reviews Process

Before beginning any development task, be sure to create a Shortcut Card. All development should be done in feature branches off of the HEAD of main, with names that can be automatically tracked by Shortcut such as johncarmack/ch123456/all-the-features. When you are satisfied with your changes, you must open a pull request and solicit the wisdom of at least one approving review prior to merging to main.

Testing

From the root directory of the repository, you can run the entire test suite by executing make test. Always strive to increase test coverage when contributing to the project.