important

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Architecture choice - Backend SDK vs core dashboard

Status:: accepted
Deciders:: rishabhpoddar, nkshah2, makerboiAdi
Proposed by:: makerboiAdi
Created:: 2022-11-28

Context and Problem Statement#

We need to provide a user management dashboard to our users. For this, we need decide:

What process will serve the dashboard HTML
Where will the APIs exist that the frontend dashboard client can call.
What are the differences between managed and self hosted (if any).

Considered Options#

Have a different github repo for the dashboard and its API that the user can run. This would connect to the user's core service.
Serve the dashboard client via the core and have its APIs exposed by the core as well.
Serve the dashboard client via the backend SDK and have its APIs exposed by the backend as well.

Decision Outcome#

We decided to do with the option that serves the dashboard via the backend SDK and also has its APIs on the backend SDK level (option 3).

User's customisations are applied to dashboard APIs (See below for list of customisations considered).

Pros and Cons of the Options#

Have a different github repo for the dashboard and its API that the user can run. This would connect to the user's core service.#

Further details if necessary

No need to build for different stacks again and again

User has to run this process on their own

Customisations of users aren't applied (See below for list of customisations considered).

On core start, user doesn't see a dashboard - more setup required.

Two dashboard for managed service users (on supertokens.com and the user management one).

Serve the dashboard client via the core and have its APIs exposed by the core as well.#

No need to build for different stacks again and again

User sees dashboard immediately - this is what they expect.

One unified dashboard for managed users.

Customisations of users aren't applied (See below for list of customisations considered).

Users would need to expose the supertokens core to the public network and therefore might require to do additional configs and take more security measures.

We even considered changing how customisations are done to resolve the con above:

Make webhook based customisations where the core queries the backend SDK for email sending etc..
- It would allow the dashboard APIs in the core to take into account customisations of the user.
Bad dev experience when the backend is in localhost, but core is in managed service. The dev would need to expose their backend using ngrok and configure the core to query that.

Make the user upload Java code to the core for customisations:

It would allow the dashboard APIs in the core to take into account customisations of the user.

Users are forced to use Java even if they do not want to.

Users have to maintain a separate code base.

Make the user upload nodejs code to the core for customisations. This can be done :

It would allow the dashboard APIs in the core to take into account customisations of the user.

Users have to maintain a separate code base.

This would require the backend SDK having the APIs anyway (which is same as option 3)

Serve the dashboard client via the backend SDK and have its APIs exposed by the backend as well.#

All customisations of users get applied (See below for list of customisations considered).

No extra infra related setup needs to be done for the user.

On core start, user doesn't see a dashboard - more setup required.

Two dashboard for managed service users (on supertokens.com and the user management one).

Need to build dashboard APIs in all backend SDKs - but this doesn't take too long gien that you already need to build all the recipe functions on the backend SDK level.

Strange that the API layer is serving HTML.

People not using our backend SDK have no dashboard at all - but we are OK with this cause those user's won't be able to use many features of SuperTokens anyway.

CORS and CSP related issues might prevent dashboard from working.

If the backend is hosted on a service that charges on a per request basis then using the dashboard adds to billing and each action taken on the dashboard will be additional requests.

List of customisations considered:#

Email / SMS sending customisations for email verification / reset password emails.
Post user creation operations - this was the most important one.
Recipe functions override.

Extra information#

Link to summary of conversation on slack: https://supertokens.slack.com/archives/C02JS72AE0Z/p1669213735216679