Readme & LicenseHEADmaster

1 files changed, 100 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f32bb27
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# Robot Tracker
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Features](#features)
+3. [Installation](#installation)
+4. [Architecture](#architecture)
+
+## Introduction
+
+Robot Tracker is a demo application with an underlying simulation of movement, in order to showcase tracking current positions on a map with frequent live updates.
+
+## Features
+
+- Login and protected Dashboard page
+- OpenLayers map for tracking the current position of all robots
+- Start and stop the backend robot movement simulation for all or individual robots
+- Add new robots
+- WebSocket connection
+- Redis cache
+
+## Installation
+
+First clone this repository and move into the parent directory by running the following commands in your terminal:
+```bash
+git clone https://codeberg.org/arrief/robot-tracker.git
+cd robot-tracker
+```
+
+Now you have two options to run *Robot Tracker* on your machine:
+
+### 1. Docker (recommended)
+
+**Prerequisites**: you need to have *Docker* with *Docker Compose* installed. Confirm by running `docker -v` and `docker-compose -v` in your terminal.
+
+In order to start the application, simply run the following command in your terminal:
+
+```bash
+docker compose up --build
+```
+
+Wait until you see the notifications that the database, redis, the backend and the frontend are ready. Then application can be accessed on `http://localhost:5173/` and the user credentials for logging in are:
+- **email**: admin@test.com
+- **password**: test123
+
+If you want to quit run `docker compose down` to keep your data and continue where you left off once you restart the app again.
+\
+Or run `docker compose down -v` to erase the Docker volume/database and have a clean start the next time you run the app.
+
+### 2. Manual setup
+
+**Prerequisites**: you need to have *npm* and *PostgreSQL* installed. Confirm by running `npm -v` and `psql --version` in your termial. You will also need Redis either locally installed or an account for the Redis Cloud.
+
+Assuming you already set up your Postgres, log in and create the required database and user for the app:
+
+```sql
+CREATE DATABASE robot_tracker_db;
+CREATE USER robot_master WITH PASSWORD 'yourPassword';
+GRANT ALL PRIVILEGES ON DATABASE robot_tracker_db TO robot_master;
+```
+
+Now you can import the dump file `database/init.sql` in order to have the required tables, the demo user and some robots to start you out. For the import, exit your database and simply run the following terminal command from the root directory of the app (replace "postgres" with your root user name if named differently):
+
+```bash
+psql -U robot_master -d robot_tracker_db -f database/init.sql
+```
+
+Next, in the `backend` directory, rename the file **.env.sample** to just **.env**, open the file in a text editor or IDE of your choice and replace the placeholder values inside with your actual PostgreSQL data and credentials, same for your Redis connection and credentials.
+
+Similarly rename the **env.sample file in the frontend directory** to simply .env, but this time only change its content if you prefer to have your backend running on another port than the default port 3000 (if you change it, remember to change the PORT environment variable in `backend/.env` too!).
+
+Finally you need to install the required node modules/npm dependencies for **both** the frontend and backend before you are ready to launch both with their startup scripts. Still from the project's root directory, open up a second terminal tab and run:
+```bash
+# Terminal tab 1
+cd frontend
+npm install
+npm start
+# Terminal tab 2
+cd backend
+npm install
+npm run dev
+```
+
+Keep both terminal tabs/windows open and running while using the application locally. Now you can visit `http://localhost:5173/` to interact with the application. The user credentials for logging in are:
+- **email**: admin@test.com
+- **password**: test123
+
+## Architecture
+The **frontend** is a classic SPA written in **TypeScript**, using **React** with **React Router** and **Vite**. The styling is done with **vanilla CSS**.
+\
+It contains two "pages", the login screen and the dashboard, the latter being protected via **JSON Web Token** from unauthorized access. Here the user will be presented with an **OpenLayers map** that displays the current position of robots in a city.
+\
+The user is able to start or stop the backend smovement simulation, either setting all robots at once or individual robots in motion or to idle. New robots can be created as well and the simulation will continue to run even if the user logs out. The position updates coming from the backend are received via **WebSocket** connection.
+
+The **backend** is a **Node.js** application with **Express.js**, also written in TypeScript and implementing a **WebSocket broadcast** as well as a **Redis cache** for the data queried from the **PostgreSQL** database.
+\
+Aside from listening to frontend request to sign a user in and create and verify the **JWT** (as well as a single-use convenience route to create the admin test user with a hashed password with **bcrypt**), the API has several protected routes: one for creating new robots and the rest for the controllers connected to the centerpiece of the API, the robot movement simulation under `src/simulation/robotMovementSimulatior`.
+\
+This simulation handles the creation of new positions of the robots within an area defined by geocoordinates, updates the current robot positions as well as the log of previous positions in the database and broadcasts the updates to the frontend over the WebSocket connection.
\ No newline at end of file