Refactor readme to act as a landing page

Author: amitkummer

readme.md

@@ -1,51 +1,68 @@
+# Welcome to Mesimä
+
+This is the source of Mesimä (pronounced Mesi-mah). It is a RESTful HTTP application for task managment, written in Python.
+
+Mesimä was created with ❤️ using [Django Rest Framework](https://www.django-rest-framework.org/) and [PostgreSQL](https://www.postgresql.org/).
+
 # Development Instructions
 
-To create the cluster, deploy and watch files:
+## Prerequisites
+
+Running the app requires having tilt, k3d and their dependencies (Docker, kubectl...).
+
+This project was developed using tilt `v0.23.4` and k3d `v5.2.2`.
+Newer version *should* be fine.
+
+## Running the Application
+
+Create a k3d cluster:
 
 ```s
 $ k3d cluster create --config k3d.yaml
-$ kubectl apply -f https://raw.githubusercontent.com/reactive-tech/kubegres/v1.15/kubegres.yaml
-$ tilt up
 ```
 
-To delete the cluster:
+Install Kubegres (a Kuberntes operator for delpoying PostgreSQL clustres):
 
 ```s
-$ k3d cluster delete amit-mini-project
+$ kubectl apply -f https://raw.githubusercontent.com/reactive-tech/kubegres/v1.15/kubegres.yaml
 ```
 
-## Running the Tests
-
-Tests are easiest to run using sqlite. Use the following sequence of commands:
+Start the development setup:
 
 ```s
-$Env:DB="sqlite"
-poetry shell
-python manage.py test
+$ tilt up
 ```
 
-# DRF Useful Links
+Open a web broswer and navigate to `https://localhost:3080/api`. You should see DRF's browseable api client.
 
-- A solution to the wierd API endpoinds in the form of `user/id/tasks` ([link](https://www.django-rest-framework.org/tutorial/6-viewsets-and-routers/#refactoring-to-use-viewsets)).
-
-- Writing 'raw' gin-like views in DRF ([link](https://www.django-rest-framework.org/tutorial/1-serialization/#writing-regular-django-views-using-our-serializer)).
-
-- Overwrite just the post in the viewset which is prob the best move ([link](https://www.django-rest-framework.org/tutorial/quickstart/)).
+To delete the cluster:
 
+```s
+$ k3d cluster delete amit-mini-project
+```
 
+## Running the Tests
 
-# Notes
+It is recommended to run the tests using sqlite, without k3d. 
+This requires having `poetry` installed.
 
-- `Post` returns data in headers. :(
-- `People` email field should be unique.
+Use the following sequence of commands to run the unit-tests:
 
+```s
+$ cd backend
+$ poetry install                       # Install Python dependencies
+$ poetry shell                         # Spawn a shell inside the virtual environemnt
+$ cd manager
+$ DB="sqlite" python manage.py test    # Run the test suite while using sqlite
+```
 
-# Questions to Lecturer
+## Documentation
 
-1. Can we return error messages in `JSON`? (There is a fix though (link)[https://www.django-rest-framework.org/api-guide/settings/#miscellaneous-settings]).
+The Django app and project were generated using `django create project` and `django create app` commands.
 
+Consequentially, a basic understanding of Django's [getting started tutorial](https://docs.djangoproject.com/en/4.0/intro/tutorial01/) should be enough to understand the role of each source file.
 
-# TODO
+To gain understanding of specific aspects of the app (e.g, routing), it is recommended to read the respective source files.
+DRF abstractions are heavily used, which allows most code to be self-documenting.
 
-1. The weird nested endpoints (like `/tasks/id/owner`).
-2. Complete `Person`'s `activeTaskCount`.
+Usage of less common Django/DRF funcitonality is documented inline in each source file, with comments linking to Django documentation.