RFC: New Use-Case Features Strategy

[bestickley]

The goal of Green Boost is to help developers build full-stack serverless web apps fast on AWS. After providing a default template with prescribed open source libraries allowing developers to build on the shoulders of giants, the next step is to provide features that meet common use cases within web apps. While some of the features may be focused on technical problems within web app development like StaticSite, I'd like GB to focus more on "use case features". Examples of use case features include user management, stripe billing dashboard, use case management, communications hub, dream on! The only example of this right now in Green Boost is the user management feature. Most web apps need user management. So Green Boost provides the UserManagement react component from gboost-ui and UserManagement AWS CDK construct from gboost-infra. Example usage:

/ui/src/pages/page.tsx

import type { Page } from "gboost-ui";
import { UserManagement } from "gboost-ui";
import { groups } from "common/groups";
import { MdManageAccounts } from "react-icons/md";

export const pages: Page[] = [
  {
    component: <UserManagement groupNames={groupNames} />,
    icon: <StyledManageAccounts />,
    name: "User Management",
    path: "/user-management",
  },
];

/infra/src/back-end-stack.ts

import { Aspects, CfnOutput, Stack, StackProps } from "aws-cdk-lib";
import type { Construct } from "constructs";
import { UserManagement { from "gboost-infra"

export class BackEndStack extends Stack {
  constructor(scope: Construct, id: string, props: BackEndStackProps) {
    super(scope, id, props);
    //...
    new UserManagement(this, "UserManagement", {
      api: gqlApi,
      userPoolId: userBase.userPool.userPoolId,
      groupNames: groups.map((g) => g.groupName),
      adminGroupNames: ["Admin"],
      stage,
    });
  }
}

This proposal does not concern the React component, but concerns how the backend is setup. Currently the UserManagement construct creates a Node.js lambda function, sets up AppSync resolvers, and adds the necessary GraphQL queries and mutations to support the react component. Think queries like listUser, getUser and mutations like updateUser and createUser. This is fine, but customization is limited. The only way we can customize runtime behavior is by passing environment variables to the Lambda function. For example, adminGroupNames which is passed in the above example is passed into the Lambda function so that the runtime can know which groups to apply to "admin" routes like deleteUser mutation. What if the user wanted to run a custom function upon every user creation? Can we serialize the function, pass it into Lambda via env vars, and then call it in the Lambda? It may be possible, but that won't scale. We need a better way.

Currently Green Boost prescribes (but doesn't enforce) AppSync as the primary API layer. However, this is changing. Green Boost's prescribe template will soon include API Gateway using tRPC. Why? End to end type-safety between your front-end and backend. See GIF on tRPC link to understand and a blog on why a team is ditching GraphQL for tRPC. You can achieve end to end type-safety with GraphQL, but it requires code-generation. The main idea of tRPC is you have a router that routes requests to functions that run your business logic. See example below:

const t = initTRPC.create();
 
const router = t.router;
const publicProcedure = t.procedure;
 
const appRouter = router({
  greeting: publicProcedure
    .input(z.object({ name: z.string() }))
    .query((req) => {
      const { input } = req; 
      return {
        text: `Hello ${input.name}` as const,
      };
  }),
});
 
export type AppRouter = typeof appRouter;

Therefore, with this new assumption of API GW and tRPC, we can shift the abstraction layer from the construct level to the router level. Therefore, in addition to importing UserManagement from gboost-infra, we can import createUserManagementRouter from gboost-node where createUserManagementRouter would accept the same properties as the construct above, but the values don't have to be serialized via env vars. So we can pass in functions that hook into common user management customization use cases like onCreateUser or onUpdateUser. Note, the dev will have to create the lambda function entry-point and pass that file path into the UserManagement construct.

What other properties could we add for further customizations? The createUserManagementRouter accept override properties for the route level, service level, and adapter level. Note, adapters are a hexagonal architecture idea. See more here. Route level is the top level where a dev can overwrite the entire route but is then responsible for all operations including schema validation, authz, service, and adapter. Services and adapters will be exported from gboost-node so developer can still call those functions but they can also add logic surrounding them. Service level is the next level where the developer isn't responsible for schema validation and authz, but is responsible for calling adapters which are exported from gboost-node. The last level is adapter level. This allows dev to override calls to external systems like DBs, email service, and message queues. Note, all of these are optional, the dev can chose to just provide top-level configuration like adminGroupNames and not have to worry about overrides.

We can support deploying UserManagement as it's own lambda/router or as a part of the developer's own app router with custom routes for their business logic. With the former, you'll need to have multiple React context providers as seen here. With that latter, you won't need the UserManagement construct because the developer is already instantiating a Function from SST.