Added PUML overview diagram to README.md for a quick project overview…

README.md

@@ -1,38 +1,49 @@
 # Python Firebase
 
-Python interface to the Firebase's REST API
+Python interface to the Firebase's REST API. Firebase provides a platform that allows you to develop web and mobile applications without server-side programming, making development easier and faster.
 
 [![Firebase](https://szimek.github.io/presentation-firebase-intro/images/firebase_logo.png)](http://www.firebase.com)
 
+## Table of Contents
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Authentication](#authentication)
+- [Concurrency](#concurrency)
+- [System Overview with UML](#system-overview-with-uml)
+- [Further Topics](#further-topics)
+- [Shortcomings](#shortcomings)
+- [TODO](#todo)
+
 ## Installation
 
 [![Build Status](https://travis-ci.org/ozgur/python-firebase.png?branch=master)](https://travis-ci.org/ozgur/python-firebase)
 
-python-firebase highly makes use of the **requests** library so before you begin, you need to have that package installed.
+To use `python-firebase`, you must first install the `requests` library. 
 
-    $ sudo pip install requests
-    $ sudo pip install python-firebase
+```shell
+$ sudo pip install requests
+$ sudo pip install python-firebase
+```
 
 ## Getting Started
 
-You can fetch any of your data in JSON format by appending '.json' to the end of the URL in which your data resides and, then send an HTTPS request through your browser. Like all other REST specific APIs, Firebase offers a client to update(PATCH, PUT), create(POST), or remove(DELETE) his stored data along with just to fetch it.
+With Firebase, you can easily fetch your stored data in JSON format. The `python-firebase` interface provides both synchronous and asynchronous methods to interact with your Firebase storage.
 
-The library provides all the correspoding methods for those actions in both synchoronous and asynchronous manner. You can just start an asynchronous GET request with your callback function, and the method
+You can fetch any of your data in JSON format by appending '.json' to the end of the URL in which your data resides and, then send an HTTPS request through your browser. Like all other REST specific APIs, Firebase offers a client to update(PATCH, PUT), create(POST), or remove(DELETE) his stored data along with just to fetch it.
 
+The library provides all the correspoding methods for those actions in both synchoronous and asynchronous manner. You can just start an asynchronous GET request with your callback function, and the method.
 
 To fetch all the users in your storage simply do the following:
-
 ```python
 from firebase import firebase
 fb_app = firebase.FirebaseApplication('https://your_storage.firebaseio.com', None)
 result = fb_app.get('/users', None)
 print result
 {'1': 'John Doe', '2': 'Jane Doe'}
 ```
-
-
 The second argument of **get** method is the name of the snapshot. Thus, if you leave it NULL, you get the data in the URL **/users.json**. Besides, if you set it to **1**, you get the data in the url **/users/1.json**. In other words, you get the user whose ID equals to 1.
 
+
 ```python
 from firebase import firebase
 fb_app = firebase.FirebaseApplication('https://your_storage.firebaseio.com', None)
@@ -78,7 +89,7 @@ fb_app.delete('/users', '1')
 
 ## Authentication
 
-Authentication in Firebase is nothing but to simply creating a token that conforms to the JWT standards and, putting it into the querystring with the name **auth**. The library creates that token for you so you never end up struggling with constructing a valid token on your own. If the data has been protected against write/read operations with some security rules, the backend sends an appropriate error message back to the client with the status code **403 Forbidden**.
+Firebase uses token-based authentication. Here's how you can authenticate and retrieve data:
 
 ```python
 from firebase import firebase
@@ -123,8 +134,26 @@ def log_user(response):
 fb_app.get_async('/users', None, {'print': 'pretty'}, callback=log_user)
 ```
 
-# TODO
+## System Overview with UML
+
+To better understand the interactions between the user, Python console, and Firebase, refer to the following UML diagram:
+
+![UML Overview](./docs/images/logic_in_uml_structure.png)
+
+## Further Topics
+
+As you delve deeper into `python-firebase`, there are advanced topics you might want to explore, such as integrating Firebase with other services, using Firebase with advanced querying, and more.
+
+## Shortcomings
+
+While `python-firebase` provides a robust interface, there might be certain limitations:
+
+1. It primarily supports RESTful operations. For real-time data synchronization, consider using the official Firebase SDKs.
+2. Error handling might be generic in some cases. Always handle exceptions appropriately.
+
+## TODO
 
 - [ ] Async calls must deliver exceptions raised back to the main process.
 - [ ] More regression/stress tests on asynchronous calls.
 - [ ] Docs must be generated.
+

docs/puml/logic_in_uml_structure.puml

@@ -0,0 +1,35 @@
+@startuml
+
+actor User
+participant "Python Console" as PC
+participant "Firebase" as FB
+
+User -> PC: Install and start python-firebase
+PC -> User: Start success message
+
+User -> PC: Send GET request for data in Firebase
+PC -> FB: Request data
+FB -> PC: Send requested data
+PC -> User: Return the fetched data
+
+User -> PC: Send POST request to create new data in Firebase
+PC -> FB: Create new data
+FB -> PC: Confirm data creation
+PC -> User: Return confirmation 
+
+User -> PC: Send DELETE request to remove data in Firebase
+PC -> FB: Remove data
+FB -> PC: Confirm data deletion
+PC -> User: Return confirmation
+
+User -> PC: Authenticate user in Firebase
+PC -> FB: Send authentication details
+FB -> PC: Authenticate and return token
+PC -> User: Return Firebase auth token
+
+User -> PC: Trigger asynchronous calls
+PC -> FB: Execute async calls and return data
+FB -> PC: Return async call results
+PC -> User: Return results of async calls
+
+@enduml