Account Microservices w/ AWS AppSync & Cognito

Problem statement

Users need to sign up and have an organization created so we can associate billing and other settings.

We also need a Project and Environment created to immediately set up their project, such as copying the script.

Given the following user flow:

On user signup, they are presented with an onboarding flow. This onboarding flow can consist of: • Showing a script to copy and paste on their site.
• KYC: Accepting details about their organization such as name, num employees, etc.
• Inviting other team members to the organization.
• Go straight into creating an experiment.
• Any of these or a combination of these are possible from the user logs in or signs in.

Signup Flow

With the requirements and model described above, we need to have an environment ready when the user signs up. There should be no difference between login and signup to the user, but behind the scenes, we will be either create all the required entities or log the user in.

New User SignUp

This seq diagram demonstrates what happens when the user is detected to be new: Samelogic - New User Signup

Existing User Login

This seq diagram demonstrates an existing user login: Samelogic - Existing User Login

Entity Relationship Models

Domain Models

The Accounts Service will own the following entities:

  • Organizations
    • Memberships - Users - Teams
    • Plans
  • Projects
    • Environments
Organizations

These are entities related to accounts management:

Organizations - These are the parent entities that represent a company. Company settings, payment details, plans, feature flags may be attached at this level. All entities under an organization must have a reference to this entity. Think of Organizations as tenants.

Memberships - When a user or team is associated with an organization, they must have an owner, editor, viewer, etc.

Users - Organisations have many users. In the future, that user may also be a part of other organizations.

Teams - Organisations usually have many teams working on many projects. Users can be placed in teams, and teams are associated by their membership.

Plans - An organization can subscribe to a plan such as Basic with certain features available.

Projects

The nature of Samelogic is to integrate with other SaaS products. This means we should model how these organizations structure their portfolio products and deployment models:

Projects - Projects can be an app or product that the company is working on. Data is kept isolated between projects. Experiments can be created and collaborated on for these projects. Many teams can be associated with a project.

Environment - A project usually has many copies, such as a deployment environment like production and development. An environment is just a copy of a Project, but all data collected from the client will be isolated.

An example of the expected behavior here is that the user can create an experiment for a project, test it in development and then deploy it to production. Data collected for this experiment will be isolated per environment.

ERD

The following ERD explains how these are all connected: Samelogic - ERD

Access Patterns

Since we will be using DynamoDb, we can leverage partition keys to use a single table to store relational data. This requires us to think through our data access patterns before designing the model.

Organizations

Dashboard:

  • We want to get the organization by Id. getOrg(orgId)
    • When a user logs in, get the org and its settings to configure the page and session.
  • We want to get the organization memberships getOrgUsers(orgId) [UserMemberships]
    • View all users in an organization and their roles.

Users

Dashboard:

  • We want to get all users in an organization. getUsers(orgId)
  • We want to get a user by its Id when we view the profile. getUser(userId)
  • We want to update a user by its Id. updateUser(userId, UserProfile)

This allows us to use a single SignUp lambda triggered on AWS Cognito new user signup to create all the entities in DynamoDb tables in a single transaction. This will enable us to prevent data corrupted, such as an incomplete state of a user. Samelogic - OrgID

AWS Infrastructure

The infrastructure architecture below demonstrates two flows. The signup flow and the create experiment flow. This shows the boundaries and communication between services for two different user flows. Samelogic AWS Infrastructure

Sign Up Flow

The following takes place:

  1. The client interacts with Cognito Hosted UI. Cognito sets up the user with organization roles.
  2. When the user is confirmed, Cognito will fire a lambda that resides in the accounts service to execute the flow described above to set up the organization and projects.
  3. The client will have a token that it will use to communicate with the AppSync Gateway.
  4. This gateway will handle authorization and forward the requests to the relevant services.
  5. In this case, it requests the user’s profile to configure the dashboard view. This is done through AppSync resolvers. (mutations are done via lambda for fine-grained control).
Create Experiment Flow

Once we have this auth token, all other flows are similar. The AppSync gateway proxies the requests to the relevant services.