path: root/design-documents
diff options
authorSebastian <>2021-03-18 18:58:32 -0300
committerSebastian <>2021-03-18 18:59:40 -0300
commit0073e7d30689ad53f499ea5c9ccc2adc588cecbd (patch)
tree595fdf6e74479c18eb9effa969abd66f07986620 /design-documents
parent7b501372358848266e5e796752ccb36ffecca6f9 (diff)
backoffice routing design
Diffstat (limited to 'design-documents')
1 files changed, 153 insertions, 0 deletions
diff --git a/design-documents/015-merchant-backoffice-routing.rst b/design-documents/015-merchant-backoffice-routing.rst
new file mode 100644
index 0000000..3cf7e80
--- /dev/null
+++ b/design-documents/015-merchant-backoffice-routing.rst
@@ -0,0 +1,153 @@
+Design Doc 015: Merchant backoffice Routing
+A well defined routing will allow users to share backoffice links pointing directly into instance pages (settings, orders, products, etc...)
+The backoffice should load from the instance URL and then allow a internal
+rounting of the views with the posibility to accessing them directly when
+sharing a link.
+Application rounting
+There are 2 type of rounting: external and internal
+ external: define how the pathname of the URL will be interpreted to infer
+ which instance is being accessed. Also the full URL is used as default when
+ no BACKEND_URL exist yet in localStorage. After login, the BACKEND_URL is saved
+ in localStorage and the pathname is parsed to infer the instance id.
+ internal: define wich view will be rendered. It is implemented using a hash
+ routing since 1) the SPA is not server side rendered and 2) the http servers
+ doest not need to care about matching all applications URL
+Some border cases:
+Application Ready definition
+The application is considered ready after
+ * the user tried to login.
+ * the applicaton checked that the backend url points to a merchant backend
+ * the merchant backend response successfully
+The backoffice test for $BACKEND_URL/config to define if the $BACKEND_URL is ok.
+The application can potentially test if the protocol or version matched.
+While the application is not ready, just the top navigation bar will be shown
+with a message in the left and the lang selection option.
+Application entry points
+When the application is ready to start, it queries the backend to test if the
+user can access to the list of instance and decide if the admin panel should be
+All of this entry points that do not require a paramenter (like $ID) should be
+accesbile from the Sidebar.
+If the admin panel is accesible, this entry points are available:
+ - /instances: Show the list of instances currently created
+ - /instance/new: Show a instance creation form
+ - /instance/$ID/update: Show a instance modify form and allow updating it
+Where admin or not, there is also this entry points:
+ - / : redirects to the instance settings page
+ - /update: instance setting page, renders a form and allow modifing it
+ - /products: list of instance products
+ - /product/$ID/update: product modification page
+ - /product/new : product creation page
+ - /orders : list of instance orders
+ - /transfers : list of transfers
+Special cases
+First time
+If the application is loaded for the first time a welcoming message is shown
+with the login form (even if the backend doest not need authentication)
+Log out
+On logout, the application go to the initial state
+For any case that the backend respond 401 the application will render the
+login view showing a notification error that the user must check the login
+credentials or the backend url
+Not found
+For any case that the backend respond 404 the application will render a
+custom not found page
+Missing default instance
+If the **user is admin** AND is loading the setting page (/update), product list
+(/products), order list (/orders) or transfer list (/transfers) AND **gets a
+404** it will tell the user that it need to create a default instance before
+Checking for admin rights
+The token and backend url provided may give access to the default instance and
+in that case an admin functionality should be accesbile.
+This check is done after the query to $BACKEND_URL/config returns 200 validating
+that it points to a correct merchant backend. Sidebar with access to the logout
+button should be shown after this point.
+The user is considered admin if has access to the default instance. This will be
+defined after quering $BACKEND_URL/private/instances.
+ * HTTP response 200: means that $BACKEND_URL points to default instance and
+ user has admin rights
+ * HTTP response 401: means that $BACKEND_URL points to default instance but
+ wrong credentials (either no there or invalid). It will render login screen.
+ * HTTP response 404: means that $BACKEND_URL its not the default instance and
+ will asume that $BACKEND_URL points to a non default instance (since
+ $BACKEND_URL/config should have responded 200)
+ * HTTP respone with error code: render the error message and the login screen.
+When testing for admin rights and if the response is 404, the application will
+parse the $BACKEND_URL pathname and expect to match exactly '/instances/$ID'
+(optionally ending with a slash) and use $ID as the instance $ID for any
+operation that needs it. If fails to infer the instance $ID render an error
+message with a login screen.
+All tokens are saved in localStorage with key ``backend-token-$ID``, the default
+backend token have the key ``backend-token``.
+Default instance user is expected to jump from one instance to another in the
+same session so all queries to the backend will be to
+``${BACKEND_URL}/instances/${CURRENT_INSTANCE_ID}`` with the ``BACKEND_URL`` provided in
+the login form and using the token expected to ``$CURRENT_INSTANCE_ID``.
+Queries from a normal user will be done directly to ``$BACKEND_URL`` and using token
+from the login form.