documentation: update readme structure and add ToC

README.md

@@ -1,36 +1,76 @@
-# ADA502FireGuardProject
+<!-- TOC start (generated with https://github.com/derlin/bitdowntoc) -->
 
-## Prerequisites
-Before you run this project you need: 
-Docker
-Postman
+- [Introduction](#introduction)
+   * [Getting started](#getting-started)
+      + [Prerequisites](#prerequisites)
+      + [Getting started](#getting-started-1)
+      + [Accessing the API](#accessing-the-api)
+         - [Authentication](#authentication)
+   * [Background](#background)
+      + [Overall Architecture](#overall-architecture)
+      + [Techonolgies applied](#techonolgies-applied)
+      + [API/Business Logic](#api-structure)
+      + [Databases](#databases)
+      + [Messaging System](#messaging-system)
+      + [Authentication and Authorization](#authentication-and-authorization)
+      + [CI/CD and package control](#cicd-and-package-control)
 
+<!-- TOC end -->
 
+<!-- TOC --><a name="introduction"></a>
+# Introduction
+This repository is a project completed as part of the ADA502 - Cloud Computing course at HVL, and encompasses creating a REST API interface for getting firerisk with the [FRCM python library](https://pypi.org/project/dynamic-frcm/). 
+
+<!-- TOC --><a name="getting-started"></a>
 ## Getting started
-This project is still under heavy development, and while functional there is no claim that this follows the best practices for security. Anyways, to run the project in it's current state.
-1. Clone the repository
-2. Edit the values in the .env file, especially mongo_db relies on external services
-3. Run the Docker compose, everything should work out of the box as long as the environment varibles are correct
-
-## Accessing the API
-In your webrowser you can now access localhost:8000/ and localhost:8000/public. All other URL's require authentication for access. This can be done several ways, but we have opted to use postman. 
-In postman open a new tab. In this new tab, choose POST and use this link http://localhost:8080/realms/FireGuard/protocol/openid-connect/token. You also have to provide some information for the body. Choose "body" underneath the link you just posted and check off the x-www-form-urlencoded. 
-In your body you need : 
-client_id : your_client_id
-username : your_username
-password : your_password
-grant_type : password
-
-which has to match a user in the database. For demonstration purposes we have created a test user that can be used, which you will find in the picture. Your tab in postman should now look something like this: 
+
+<!-- TOC --><a name="prerequisites"></a>
+### Prerequisites
+This approach to running the project is based on you having access to the following technolgies in your environment: git, Docker-Desktop, DockerHub and Postman. You can use similar techonolgies as alternatives if you would like. The project has been tested against the recommended technolgies and we highly recommend them for beginners.
+
+
+<!-- TOC --><a name="getting-started-1"></a>
+### Getting started
+This project is the result of an assignment for creating a API for calculating firerisk in areas of Norway, and should be considered a result of learning and testing new techonologies.  
+The project is still undergoing changes and can be considered a v0 for further development.  
+To run the project in it's current state you can do the following:
+1. Clone this repository
+2. Edit the values in the .env file to match your setup. Take especially note of the values related to the MongoDB
+3. Run all the services in the Docker compose using `docker-compose up -d`, all containers should run locally out of the box 
+
+<!-- TOC --><a name="accessing-the-api"></a>
+### Accessing the API
+In your webrowser you can now access the public URLs exposed by the API. Since the API is built upon FastAPI one of these is localhost:8000/docs where all endpoints are detailed. Currently the following are available:
+| Endpoint                             	| Authentication 	|
+|--------------------------------------	|----------------	|
+| localhost:8000/                      	| None           	|
+| localhost:8000/public                	| None           	|
+| localhost:8000/docs                  	| None           	|
+| localhost:8000/api                   	| Token          	|
+| localhost:8000/api/{location}        	| Token          	|
+| localhost:8000/api/{location}/trends 	| Token          	|
+
+<!-- TOC --><a name="authentication"></a>
+#### Authentication
+To access the endpoints requiring authentication you need a JWT-token aquired from Keycloak. To do this you need to send a POST-request to http://localhost:8080/realms/FireGuard/protocol/openid-connect/token. With the following parameters in the body of the HTTP-request (note also that the body has x-www-form-urlencoded):
+| **Key**    	| **Content**                     	| **Test Value** 	|
+|------------	|---------------------------------	|----------------	|
+| client_id  	| ClientID registered in Keycloak 	| FireGuardAPI   	|
+| username   	| User in keycloak database         | test           	|
+| password   	| Password for user               	| testing        	|
+| grant_type 	| Type of authentication          	| password       	|
+
+
+*Using the provisioned test-user in Postman looks like this:*
 ![image](https://github.com/user-attachments/assets/1d840207-bdef-4a7c-ad25-f0eb2f7c5759)
 
-Click send and if all goes well you will get a respones including an access_token. As you can see in this image you get the HTTP response in the right corner (200) and the access_token is the first value in the response. ![image](https://github.com/user-attachments/assets/0bca506b-b5b0-46b3-8f64-35ca5458dfa9)
+From the POST-request will get the access-token in the response-body. To access endpoints protected by the API you can now send GET-requests to any API with this access token in the body. The figure below shows this completed for the endpoint localhost:8000/api/bergen in Postman. If everything is set up correctly you should get firerisk predictions in the response
 
-Copy your token (without the "") and head over to a new tab in postman. Go to Authorization (whichs you will find on the same line as body) and choose the Bearer token. Paste your token, write the URL you want (for eks. localhost:8000/api/bergen) and click post. If you have done everything right you will now get the firerisks in Bergen. 
 ![image](https://github.com/user-attachments/assets/82079123-d36d-4c9c-a44d-31f6079a0239)
 
 
-The token do have a timeout, and you will have to get a new token each time this happens. Just repeat the earlier steps and replace your old token with the new one. 
+The token does have a timeout, and you will have to get a new token each time this happens. Just repeat the earlier steps and replace your old token with the new one. 
+
 
 Remember ! To access your login-priviliges you have to use localhost:8080, but when you want to access the api you have to use localhost:8000
 
@@ -41,12 +81,40 @@ localhost:8000/api
 localhost:8000/api/{location}
 localhost:8000/api/{location}/trends
 
+<!-- TOC --><a name="background"></a>
+## Background
 
-## Architecture
+<!-- TOC --><a name="overall-architecture"></a>
+### Overall Architecture
 This project is setup as containerized services orchastrated through tools such as Docker-Compose or Kubernetes. The following services are planned:
 - API connectionpoint
 - KeyCloak with database for persistent storage
 - Database for FireGuard data (external) 
 - Messaging service
 
-## API structure
+<!-- TOC --><a name="techonolgies-applied"></a>
+### Techonolgies applied
+- Python -> Poetry package manager
+- Docker -> Composes and images
+- Keycloak
+- HiveMQ Cloud
+- MongoDB
+- PostgreSQL
+- GitHub/GitHub Actions
+
+
+<!-- TOC --><a name="api-structure"></a>
+### API/Business Logic
+- REST API
+
+<!-- TOC --><a name="databases"></a>
+### Databases
+
+<!-- TOC --><a name="messaging-system"></a>
+### Messaging System
+
+<!-- TOC --><a name="authentication-and-authorization"></a>
+### Authentication and Authorization
+
+<!-- TOC --><a name="cicd-and-package-control"></a>
+### CI/CD and package control