docs: updated homepage, interfaces and reference architectures

website/docs/interfaces/README.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+slug: /interfaces
+---
+# SBT Interfaces
+
+This documentation covers the interfaces that form the backbone of SBT's authentication, billing, and metering functionalities. These interfaces provide a standardized and consistent approach to handling various operations, making it easier to manage and integrate different components across the system.
+
+By following a consistent interface-driven approach, SBT maintains a high degree of modularity, extensibility, and maintainability. This allows for easy integration of new features, replacement of implementations, and adherence to best practices.
+
+Below, you'll find detailed explanations of each interface, their key features, and links to dive deeper into their documentation.
+
+## IAuth Interface
+
+The IAuth interface defines the contracts for authentication and authorization in an application. It provides various configurations and endpoints related to JSON Web Tokens (JWT), OAuth, client IDs, client secrets, and scopes for different operations. Additionally, it includes Lambda functions for managing users.
+
+Key features include:
+
+🔑 JWT and OAuth Configuration: Properties for setting up JWT issuer, audience, token endpoint, and OAuth client IDs and secrets.
+
+🔍 Scope Management: Scopes for authorizing requests related to tenant registration, user management, and other operations.
+
+👤 User Management: Lambda functions for creating, fetching, updating, enabling, and disabling users.
+
+The interface ensures a consistent and standardized way of handling authentication and authorization across the application, making it easier to manage security-related configurations and user operations.
+
+To learn more about the IAuth interface and its properties and methods, you can dive deeper into the documentation by [clicking here](auth-interface.md).
+
+## IBilling Interface
+
+The IBilling interface defines a standardized way of handling billing-related operations in a cloud-native application. It encapsulates functions for customer and user management, data ingestion, and usage data handling.
+
+Key Features include:
+
+👪 Customer Management: Create and delete customers (entities that can have zero or more users).
+
+🧑‍🤝‍🧑 User Management (Optional): Create and delete users belonging to customers.
+
+📥 Data Ingestion (Optional): Aggregate raw billing data using a data ingestor.
+
+📊 Usage Data Handling (Optional): Push aggregated data to the billing provider on a scheduled basis.
+
+🔗 Webhook Support (Optional): Trigger a function when a webhook request is received.
+
+The interface includes properties for defining the required functions and their triggers, such as onboarding requests, offboarding requests, user creation/deletion events, and scheduled data pushes.
+
+To learn more about the IBilling interface and its functions, you can dive deeper into the documentation by [clicking here](billing-interface.md).
+
+## IMetering Interface
+
+The IMetering interface defines the contracts for metering operations in a system. It provides functions for managing meters, ingesting usage events, handling customer (tenant) operations, and retrieving usage data.
+
+Key features include:
+
+📏 Meter Management: Create, fetch, update, and delete meters used for tracking usage metrics.
+
+📊 Usage Ingestion: Ingest usage events associated with meters to measure and analyze usage data.
+
+👤 Customer Management: Create and delete customers (tenants) for tracking usage.
+
+📥 Usage Retrieval: Fetch usage data for specific meters, supporting features like pagination.
+
+🗑️ Event Cancellation: Cancel or exclude specific usage events from being recorded.
+
+The interface ensures a consistent and standardized way of handling metering operations, making it easier to integrate or replace the implementation in different parts of the system.
+
+To learn more about the IMetering interface and its functions, you can dive deeper into the documentation by [clicking here](metering-interface.md).
+
+## Appendix
+
+- [Auth Interface](auth-interface.md)
+- [Metering Interface](metering-interface.md)
+- [Billing Interface](billing-interface.md)

website/docs/interfaces/_category.json

@@ -0,0 +1,9 @@
+{
+  "label": "SBT Interfaces",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "interfaces/README"
+  }
+}
+

website/docs/interfaces/auth-interface.md

@@ -0,0 +1,203 @@
+---
+sidebar_position: 1
+sidebar_label: "IAuth Interface"
+---
+# IAuth Interface
+
+## Overview
+
+The IAuth interface encapsulates the properties and methods required for authentication and authorization in the application. It provides various configurations and endpoints related to JSON Web Tokens (JWT), OAuth, client IDs, client secrets, and scopes for different operations. Additionally, it includes Lambda functions for managing users.
+
+## Properties
+
+### jwtIssuer
+
+* Type: string
+* Description: The JWT issuer domain for the identity provider. This is the domain where the JSON Web Tokens (JWTs) are issued from.
+
+### jwtAudience
+
+* Type: string[]
+* Description: The list of recipients (audience) for which the JWT is intended. This will be checked by the API Gateway to ensure only authorized clients are provided access.
+
+### tokenEndpoint
+
+* Type: string
+* Description: The endpoint URL for granting OAuth tokens. This is the URL where OAuth tokens can be obtained from the authorization server.
+
+### userClientId
+
+* Type: string
+* Description: The client ID enabled for user-centric authentication flows, such as Authorization Code flow. This client ID is used for authenticating end-users.
+
+### machineClientId
+
+* Type: string
+* Description: The client ID enabled for machine-to-machine authorization flows, such as Client Credentials flow. This client ID is used for authenticating applications or services.
+
+### machineClientSecret
+
+* Type: SecretValue
+* Description: The client secret enabled for machine-to-machine authorization flows, such as Client Credentials flow. This secret is used in combination with the machine client ID for authenticating applications or services.
+
+### machineClientAudience
+
+* Type: string | undefined
+* Description: The audience for the machine client. If provided, this value will be used in the call to generate the access token for the Client Credentials flow.
+
+### fetchTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for fetching a single tenant registration. This scope grants permission to fetch the details of a specific tenant registration.
+
+### fetchAllTenantRegistrationsScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for fetching all tenants. This scope grants permission to fetch the details of all tenants.
+
+### deleteTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for deleting a tenant registration. This scope grants permission to delete a specific tenant registration.
+
+### createTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for creating a tenant registration. This scope grants permission to create a new tenant registration.
+
+### updateTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for updating a tenant registration. This scope grants permission to update the details of a specific tenant registration.
+
+### activateTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for activating a tenant via the tenant registration endpoint. This scope grants permission to activate a specific tenant.
+
+### deactivateTenantRegistrationScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for deactivating a tenant via the tenant registration endpoint. This scope grants permission to deactivate a specific tenant.
+
+### fetchUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for fetching a single user. This scope grants permission to fetch the details of a specific user.
+
+### fetchAllUsersScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for fetching all users. This scope grants permission to fetch the details of all users.
+
+### deleteUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for deleting a user. This scope grants permission to delete a specific user.
+
+### createUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for creating a user. This scope grants permission to create a new user.
+
+### updateUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for updating a user. This scope grants permission to update the details of a specific user.
+
+### disableUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for disabling a user. This scope grants permission to disable a specific user.
+
+### enableUserScope
+
+* Type: string | undefined
+* Description: The scope required to authorize requests for enabling a user. This scope grants permission to enable a specific user.
+
+### wellKnownEndpointUrl
+
+* Type: string
+* Description: The well-known endpoint URL for the control plane identity provider. This URL provides configuration information about the identity provider, such as issuer, authorization endpoint, and token endpoint.
+
+### createUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for creating a user. (POST /users)
+
+### fetchAllUsersFunction
+
+* Type: IFunction
+* Description: The Lambda function for fetching all users. (GET /users)
+
+### fetchUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for fetching a user. (GET /user/\{userId})
+
+### updateUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for updating a user. (PUT /user/\{userId})
+
+### deleteUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for deleting a user. (DELETE /user/\{userId})
+
+### disableUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for disabling a user. (PUT /user/\{userId}/disable)
+
+### enableUserFunction
+
+* Type: IFunction
+* Description: The Lambda function for enabling a user. (PUT /user/\{userId}/enable)
+
+## Methods
+
+### createAdminUser(scope: Construct, id: string, props: CreateAdminUserProps): void
+
+* Description: Function to create an admin user.
+* Parameters:
+  * scope (Construct): The scope in which the admin user should be created.
+  * id (string): The unique identifier for the admin user.
+  * props (CreateAdminUserProps): An object containing the properties for creating the admin user.
+
+The CreateAdminUserProps interface has the following properties:
+
+* name (string): The name of the new admin user.
+* email (string): The email address of the new admin user.
+* role (string): The name of the role of the new admin user.
+
+## Usage
+
+To use the IAuth interface, you'll need to implement it and provide the required configurations and Lambda functions. Here's an example of how you might use it:
+
+```typescript
+import { IAuth, CreateAdminUserProps } from './auth-interface';
+
+class MyAuth implements IAuth {
+  // Implement the properties and methods of the IAuth interface
+  // ...
+
+  createAdminUser(scope: Construct, id: string, props: CreateAdminUserProps): void {
+    // Implement the logic to create an admin user
+    // ...
+  }
+}
+
+const myAuth = new MyAuth();
+
+// Use the properties and methods of the IAuth interface
+const jwtIssuer = myAuth.jwtIssuer;
+const tokenEndpoint = myAuth.tokenEndpoint;
+
+// Create an admin user
+const adminUserProps: CreateAdminUserProps = {
+  name: 'John Doe',
+  email: 'john.doe@example.com',
+  role: 'Admin',
+};
+myAuth.createAdminUser(this, 'AdminUser', adminUserProps);

website/docs/interfaces/billing-interface.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 2
+sidebar_label: "IBilling Interface"
+---
+
+# IBilling Interface
+
+## Overview
+
+The IBilling interface encapsulates the list of properties for a billing construct. It includes functions for customer and user management, data ingestion, and usage data handling. This interface is designed to provide a standardized way of handling billing-related operations in a cloud-native application.
+
+## Properties
+
+### createCustomerFunction
+
+- Type: IASyncFunction
+- Description: The async function responsible for creating a new customer. A customer in this context is an entity that can have zero or more users.
+- Default Event Trigger: ONBOARDING_REQUEST
+
+### deleteCustomerFunction
+
+- Type: IASyncFunction
+- Description: The async function responsible for deleting an existing customer. A customer in this context is an entity that can have zero or more users.
+- Default Event Trigger: OFFBOARDING_REQUEST
+
+### createUserFunction
+
+- Type: IASyncFunction (Optional)
+- Description: The async function responsible for creating a new user. A user in this context is an entity that belongs to a customer.
+- Default Event Trigger: TENANT_USER_CREATED
+
+### deleteUserFunction
+
+- Type: IASyncFunction (Optional)
+- Description: The async function responsible for deleting an existing user. A user in this context is an entity that belongs to a customer.
+- Default Event Trigger: TENANT_USER_DELETED
+
+### ingestor
+
+- Type: IDataIngestorAggregator (Optional)
+- Description: The IDataIngestorAggregator responsible for accepting and aggregating raw billing data.
+
+### putUsageFunction
+
+- Type: IFunctionSchedule (Optional)
+- Description: The async function responsible for taking the aggregated data and pushing it to the billing provider.
+- Default Event Trigger: events.Schedule.rate(cdk.Duration.hours(24)) (Triggered every 24 hours)
+
+### webhookFunction
+
+- Type: IFunctionPath (Optional)
+- Description: The function to trigger when a webhook request is received.
+- Default HTTP Path: POST /billing/\{$webhookPath}
+
+## Additional Interfaces
+
+### IFunctionSchedule
+
+This interface allows specifying both the function to trigger and the schedule by which to trigger it.
+
+Properties:
+
+- handler: The function definition (IFunction).
+- schedule: The schedule that will trigger the handler function (Schedule).
+
+### IFunctionPath
+
+This interface allows specifying both the function to trigger and the path on the API Gateway that triggers it.
+
+Properties:
+
+- path: The path to the webhook resource (string).
+- handler: The function definition (IFunction).
+
+## Usage
+
+To use the IBilling interface, you need to implement the required properties and pass them to the billing construct. Here's an example:
+
+```
+import { IBilling } from 'your-billing-interface';
+
+const billing: IBilling = {
+  createCustomerFunction: /* Provide your implementation */,
+  deleteCustomerFunction: /* Provide your implementation */,
+  createUserFunction: /* Provide your implementation (optional) */,
+  deleteUserFunction: /* Provide your implementation (optional) */,
+  ingestor: /* Provide your implementation (optional) */,
+  putUsageFunction: /* Provide your implementation (optional) */,
+  webhookFunction: /* Provide your implementation (optional) */,
+};
+
+// Pass the `billing` object to your billing construct
+const billingConstruct = new BillingConstruct(scope, 'BillingConstruct', billing);
+```
+In this example, you need to provide implementations for the required properties (createCustomerFunction and deleteCustomerFunction). The optional properties can be provided based on your specific requirements.