Fog of World is an mobile/web application that borrows the idea of fog of war (a concept in strategy games meaning you can only see the part of game map where you have visited, see image below) to encourage people to travel and physically discover the world.

The application provides incentives for travelling by only showing the part of the world map where the user has physically been to, and covering the rest of map with a thin layer of fog.

My original intention for starting this project was to familiarize myself with the Spring framework by actually writing a usable web app with Spring Boot. The project is supposed to be another stepping stone on my roadmap of becoming a full-fledged backend developer, and an improvement upon my previous web development project Commentaria.

The scope of the project was limited to building just the backend server. However as the development progressed I realized having a frontend would make it so much more convenient to do data generation and testing. So I decided to expand the project to include the frontend components, which consist of a mobile app for collecting location data and a web app for displaying data and easier debugging (see Architecture for details).

Below is a diagram that shows how the major components of Fog of World are connected:

The backend part of the application consists of a data server, a web app server and a database.

The data server provides a RESTful API as an interface to communicate with frontend clients. Both the mobile app and the web app talk to this server to upload or download data.

The RESTful API is written in Java using the Spring framework. The structure of the API can be described as 3 layers:

• Controller layer: receive and verify incoming requests from clients, extract DTOs and route them to corresponding services, formulate responses and send them back to clients.
• Service layer: take in DTOs from controllers, perform business logic, manipulate data by calling persistence layer.
• Domain model & persistence layer: manage domain models, repository interfaces and their implementations, store and retrieve data from the database.

The data server also has Spring Security filters laid in front of the controller layer. The filters intercept unauthenticated or unauthorized requests, send back corresponding error codes. Among them are two custom JWT filters that create JWT tokens for successfully authenticated requests and verify them in order to save the hassle of repeated authentication.

This server is relatively simple compared to the data server. It simply serves up frontend web app scripts when clients request for them.

The database stores internal data and is managed by the persistence layer of the data server through JPA.

The frontend consists of two clients: a mobile app (Android) and a web app (React).

The mobile app serves as the primary source of data thanks to the location services prevalent on mobile devices. It is also the primary user interface of the application.

The web app serves as a display tool for data and an easily accessible data interface for debug purposes.

This is a non-exhaustive list of designed features. More will be added in as the development goes on.

• User can upload their current location as a single record point
• User may also upload photos and associate them with a record point, and they may choose to share them publicly.
• User can record a journey by turning on location tracking service, and then upload the journey
• User can see a list of their travel records
• User can see a map with their footprints rendered on it (rest of the map should be covered by fog)
• User will obtain achievements and be awarded badges if they complete travelling challenges (e.g. been present on all continents of the world)
• User can see locations on the map where photos have been taken and shared by other users.

• Backend
  • See build.gradle for a definitive list of dependencies
  • Spring (Boot, Web, Data, Security) - web framework used for server
  • JJWT - Java JWT library
  • Lombok - Java efficiency utility library (no more boilerplate codes!)
• Frontend
  • Mobile App
    • Android - Mobile platform the app is developed on
  • Web App
    • React - Web app framework
    • Lodash - JavaScript utility library

• Yuhang Li - Architect, backend developer (also frontend & UI for now)
• ? - web frontend developer
• ? - mobile developer
• ? - UI designer

As the primary purpose of this project is to facilitate learning, anyone willing to practice their developing skills in frontend web app, mobile app, UI design may contact me to participate. Though the backend part of the project is mostly done, you are welcome to make improvements, add new features and/or give suggestions to the current codebase.

You are free to view, download and modify the code as you want for learning, but you are not allowed to redistribute the source code or use it for commercial purposes.

Below are some useful tutorials/references that I came across during this project. Give them a good read and you may soon have your epiphany!

• Spring Framework
  • String Boot Starter Kit - small template Spring Boot project for beginners
  • Spring Boot 2.0 — Project Structure and Best Practices
  • Entity To DTO Conversion
  • Guide to Spring Data JPA
  • Spring Security for a REST API
  • Spring Boot application.properties file
  • Guide to @ConfigurationProperties in Spring Boot - how to programmatically read and validate properties
• JWT authentication
  • Implementing JWT with Spring Boot and Spring Security
  • Implementing JWT Authentication on Spring Boot APIs
  • JWT control flow well explained
• REST API
  • User registration/authentication flow on a REST API
• Meta
  • README templates
    • PurpleBooth
    • fvcproductions
    • dbader
  • GitHub Mastering Markdown
  • draw.io - easily make UML diagrams
  • Choose an open source license
  • Choose README badges

Special thanks to the authors of all the above resources!