jshor / tycho

About This Project

This is a real-time, WebGL-based, 3D visualization of our Solar System. It's a complete re-write of the original Tycho.io project. Check out the full experience at tycho.io!

Table of Contents

• Running the app
• Development
  • Package Management
  • Framework + Libraries
  • Styling
  • Testing
    • Testing Guidelines
• Application Architecture
  • State management
• Static Data
• Folder Structure
• Available Scripts
  • yarn start
  • yarn test
  • yarn test:coverage
  • yarn lint
  • yarn lint:fix
  • yarn build
  • yarn deploy
    • yarn deploy:upload
    • yarn deploy:invalidate
  • yarn orbitals
  • yarn ephemeris
• Supported Language Features and Polyfills
• Credits

Running the app

1. Clone this repo.

git clone https://github.com/jshor/tycho2.git

2. Use the right node version.

nvm use

3. Install dependencies (via yarn).

yarn install

4. Start

yarn start

Development

Package Management

Using Yarn.

Framework + Libraries

This app is built using React.js/Redux, THREE.js, and uses react-three-renderer for THREE-based React components. It's bootstrapped using Create React App.

Styling

Each DOM component contains a corresponding Sass stylesheet and employs the BEM CSS design pattern. This app uses node-sass-chokidar for Sass compilation.

Testing

Tests use Jest, enzyme, and snapshot testing for components.

Testing Guidelines

• The importance of code coverage should not supercede the importance of writing good quality tests.
• Methods for containers should contain a corresponding unit test, and is ideally written as a pure function.
• For exceptions, such as when a local state is updated, there should be a corresponding integration test.
• Components should be snapshot tested.
• TDD and BDD.

Application Architecture

The overall architecture uses the React/Redux container pattern. In a nutshell, containers in this app leverage tasks such as handling state and minor front-end logic, while components simply handle the presentation. Physics calculations and business logic is delegated to services, and some critical components, such as the Camera, have dedicated services.

State management

All shared-state data is stored in the Redux store. This includes the 2D and 3D positions of objects and the current time. This enables unidirectional data flow (see advantages of Redux). In rare cases, some components will use the local state for things internal to that component, when appropriate.

Static Data

The JSON data for orbitals.json is generated by the yarn orbitals script. It will look for all of the JSON files in the public/static/data/orbitals directory. For information on the file structure for these JSON files, please see the Wiki.

Folder Structure

This project utilizes a typical React app flat directory structure. Tests for each item typically live in __tests__. Components have corresponding tests and Sass in the same directory. __tests__ folders may contain __snapshots__ and __fixtures__.

Note that 3D React components and DOMElement ones coexist in the same general paths.

Static assets, such as textures, media, and data are stored in the public folder. The img, js, css and some JSON file contents are generated by build scripts.

Available Scripts

In the project directory, you can run the following commands:

yarn start

Runs the app in the development mode.
It will also build the CSS using build-css. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.

yarn test:coverage

Runs all tests and prints out code covfefe.

yarn lint

Runs the linter using ESLint.

yarn lint:fix

Fixes any linting errors discovered by the linter and reports any issues that could not be addressed automatically.

yarn build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
It also runs the compilation script for the orbital data json.
The build is minified and the filenames include the hashes.

yarn deploy

Performs a full deploy.
Requires credentials defined at ~/.aws/credentials. More info.

yarn deploy:upload

Uploads the build/ contents to the designated production AWS S3 bucket.

yarn deploy:invalidate

Invalidates the designated AWS CloudFront instance.

yarn orbitals

Runs the compilation script for the orbital data json.

yarn ephemeris

Takes all orbital JSONs, probes the NASA/JPL HORIZONS database for ephemeris data, and updates each JSON accordingly. For more information on this script, and on the prerequisite data format, please see this wiki page.

Supported Language Features and Polyfills

This project supports a superset of the latest JavaScript standard.
In addition to ES6 syntax features, it also supports:

• Exponentiation Operator (ES2016).
• Async/await (ES2017).
• Object Rest/Spread Properties (stage 3 proposal).
• Dynamic import() (stage 3 proposal).
• Class Fields and Static Properties (stage 2 proposal).
• JSX.

Learn more about different proposal stages.

The following ES6 polyfills are available:

• Object.assign() via object-assign.
• Promise via promise.
• fetch() via whatwg-fetch.

Credits

• Project developed by Josh Shor
• Planetary ephemerides courtesy of NASA and the Jet Propulsion Laboratory.
• Orbital textures by James Hastings-Trew.
• Ambient music: Ultra Deep Field by Stellardrone.
• Special thanks to the open source community for React.js/Redux, THREE.js, and react-three-renderer.