feat: add arch diagram and README for AWS infra

Author: jeastham1993

user-management/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Architecture Overview
+
+This is a .NET 8 User Management Service implementing ports and adapters architecture with platform adaptability by design. The service can run on Azure, AWS, or any cloud-agnostic container orchestrator.
+
+### Core Components
+- **Core** (`Stickerlandia.UserManagement.Core`) - Domain services and business logic
+- **Auth** (`Stickerlandia.UserManagement.Auth`) - Authentication using OpenIddict
+- **Agnostic** (`Stickerlandia.UserManagement.Agnostic`) - Cloud-agnostic implementations (Kafka, Postgres)
+- **AWS** (`Stickerlandia.UserManagement.AWS`) - AWS-specific implementations (SNS, SQS)
+- **Azure** (`Stickerlandia.UserManagement.Azure`) - Azure-specific implementations (Service Bus)
+
+### Driving Adapters (Entry Points)
+- **Api** - ASP.NET minimal API (`/api/users/v1`)
+- **Worker** - Background worker service
+- **FunctionApp** - Azure Functions
+- **Lambda** - AWS Lambda functions
+
+## Development Commands
+
+### Local Development with .NET Aspire
+Run from `src/Stickerlandia.UserManagement.Aspire/`:
+
+```bash
+# Agnostic services (Kafka, Postgres)
+dotnet run -lp agnostic
+
+# Azure services (Azure Functions, Service Bus, Postgres)
+dotnet run -lp azure_native
+
+# AWS services (Lambda, SNS, SQS, Postgres)
+dotnet run -lp aws_native
+```
+
+### Testing
+
+**Unit Tests:**
+```bash
+cd tests/Stickerlandia.UserManagement.UnitTest
+dotnet test
+```
+
+**Integration Tests (requires environment variables):**
+```bash
+cd tests/Stickerlandia.UserManagement.IntegrationTest
+
+# Agnostic integration tests
+export DRIVING=AGNOSTIC && export DRIVEN=AGNOSTIC && dotnet test
+
+# Azure integration tests
+export DRIVING=AZURE && export DRIVEN=AZURE && dotnet test
+
+# AWS integration tests
+export DRIVING=AWS && export DRIVEN=AWS && dotnet test
+```
+
+### Infrastructure Deployment
+
+**AWS CDK (from `infra/aws/`):**
+```bash
+npm run build    # Compile TypeScript
+npm run test     # Run infrastructure tests
+npm run cdk      # CDK commands
+```
+
+**Azure Terraform (from `infra/azure/`):**
+Standard Terraform commands for Azure resources.
+
+## Code Quality Standards
+
+- **Static Analysis**: Enforced via `Directory.build.props` and `CodeAnalysis.props`
+- **Warnings as Errors**: All projects treat warnings as errors
+- **Nullable Reference Types**: Enabled across all projects
+- **Implicit Usings**: Enabled for cleaner code
+
+## Event Architecture
+
+The service publishes and consumes events via:
+- **Outbox Pattern**: Implemented for reliable event publishing
+- **Platform-specific Messaging**: SNS/SQS (AWS), Service Bus (Azure), Kafka (Agnostic)
+- **Event Schemas**: Documented in `docs/async_api.yaml`
+
+## Key Patterns
+
+- **CQRS**: Commands and queries are separated in the Core domain
+- **Dependency Injection**: All adapters registered via service extensions
+- **Configuration**: Platform-specific configuration in each adapter
+- **Background Processing**: Handled by workers, functions, or lambdas depending on platform

user-management/README.md

@@ -23,6 +23,23 @@ The project follows a ports and adapters architecture style, split down into `Dr
 - **Stickerlandia.UserManagement.Auth** - Core library for auth concerns using [OpenIddict](https://documentation.openiddict.com/)
 
 
+### AWS Architecture
+
+![AWS architecture diagram](./docs/aws_arch.png)
+
+The AWS native implementation of the user management service uses a combination of containers and functions as a service (FaaS), as well as native messaging services. The different components on this diagram tie to specific classes in the AWS CDK IaC project:
+
+- [API](./infra/aws/lib/api.ts)
+    - Amazon ECS for container orchestration, with Fargate providing the underlying compute
+    - A traditional Postgres database, for use with the [OpenIddict](https://documentation.openiddict.com/) auth libraries
+- [Background Workers](./infra/aws/lib/background-workers.ts)
+    - AWS Lambda for the compute, both handling external events and running on a schedule to process items from the outbox
+    - Rules are defined on a shared external Amazon Event Bridge event bus
+    - Amazon SQS provides durability at the boundaries of the system
+    - Internal domian events are published to Amazon SNS
+- [Shared](./infra/aws/lib/sharedResources.ts)
+    - Currently, these are manually created. Eventually these will be created in an external stack and this construct will pull from 
+
 ## API Endpoints
 
 ### User Management API (`/api/users/v1`)

user-management/docs/aws_arch.png

@@ -5,10 +5,8 @@ import {
   Cluster,
   ContainerImage,
   CpuArchitecture,
-  FargateService,
   FargateTaskDefinition,
   FirelensLogRouterType,
-  LogDriver,
   LogDrivers,
   OperatingSystemFamily,
   Protocol,
@@ -17,14 +15,10 @@ import { Repository } from "aws-cdk-lib/aws-ecr";
 import { Topic } from "aws-cdk-lib/aws-sns";
 import { Queue } from "aws-cdk-lib/aws-sqs";
 import {
-  ApplicationLoadBalancer,
-  ApplicationTargetGroup,
-  TargetType,
   ApplicationProtocol,
-  HealthCheck,
   Protocol as HealthCheckProtocol,
 } from "aws-cdk-lib/aws-elasticloadbalancingv2";
-import { Duration, CfnOutput } from "aws-cdk-lib";
+import { Duration } from "aws-cdk-lib";
 import { ApplicationLoadBalancedFargateService } from "aws-cdk-lib/aws-ecs-patterns";
 
 export class ApiProps {

user-management/infra/aws/lib/api.ts

@@ -1,4 +1,3 @@
-import { SubnetType, Vpc } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import { SharedProps } from "./constructs/shared-props";
 import { InstrumentedLambdaFunction } from "./constructs/instrumented-function";
@@ -7,7 +6,7 @@ import { IQueue } from "aws-cdk-lib/aws-sqs";
 import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { SqsDestination } from "aws-cdk-lib/aws-lambda-destinations";
 import {
-  EventBus,
+  IEventBus,
   Rule,
   RuleTargetInput,
   Schedule,
@@ -17,6 +16,7 @@ import { ITopic } from "aws-cdk-lib/aws-sns";
 
 export interface BackgroundWorkersProps {
   sharedProps: SharedProps;
+  sharedEventBus: IEventBus;
   stickerClaimedQueue: IQueue;
   stickerClaimedDLQ: IQueue;
   userRegisteredTopic: ITopic;
@@ -26,10 +26,6 @@ export class BackgroundWorkers extends Construct {
   constructor(scope: Construct, id: string, props: BackgroundWorkersProps) {
     super(scope, id);
 
-    const eventBus = new EventBus(this, "UserManagementEventBus", {
-      eventBusName: `${props.sharedProps.serviceName}-${props.sharedProps.environment}-bus`,
-    });
-
     const environmentVariables = {
       POWERTOOLS_SERVICE_NAME: props.sharedProps.serviceName,
       POWERTOOLS_LOG_LEVEL:
@@ -71,7 +67,7 @@ export class BackgroundWorkers extends Construct {
     );
 
     const rule = new Rule(this, "StickerClaimedEventRule", {
-      eventBus: eventBus,
+      eventBus: props.sharedEventBus,
       ruleName: `${props.sharedProps.serviceName}-${props.sharedProps.environment}-sticker-claimed-rule`,
       eventPattern: {
         source: [`${props.sharedProps.environment}.stickers`],

user-management/infra/aws/lib/background-workers.ts

@@ -1,15 +1,23 @@
-import { SubnetType, Vpc } from "aws-cdk-lib/aws-ec2";
+import { IVpc, SubnetType, Vpc } from "aws-cdk-lib/aws-ec2";
+import { EventBus, IEventBus } from "aws-cdk-lib/aws-events";
 import { Construct } from "constructs";
-export interface NetworkProps {
+export interface SharedResourcesProps {
     networkName: string;
 }
 
-// TODO: move this to a shared infra project to allow one network across multiple services
-export class Network extends Construct {
-  vpc: Vpc;
-  constructor(scope: Construct, id: string, props: NetworkProps) {
+// TODO: move the creation of these resources to a seperate stack and update this stack to pull from SSM parameters
+export class SharedResources extends Construct {
+  vpc: IVpc;
+  sharedEventBus: IEventBus; // Placeholder for shared EventBus ARN or name
+  constructor(scope: Construct, id: string, props: SharedResourcesProps) {
     super(scope, id);
 
+    this.sharedEventBus = new EventBus(this, "UserManagementEventBus", {
+      eventBusName: `stickerlandia-shared-event-bus`,
+    });
+
+    // TODO: Add creation of ALB
+
     this.vpc = new Vpc(this, "Vpc", {
       vpcName: props.networkName,
       maxAzs: 2,

user-management/infra/aws/lib/network.ts …agement/infra/aws/lib/sharedResources.tsuser-management/infra/aws/lib/network.ts renamed to user-management/infra/aws/lib/sharedResources.ts user-management/infra/aws/lib/network.ts renamed to user-management/infra/aws/lib/sharedResources.ts

@@ -2,7 +2,7 @@ import * as cdk from "aws-cdk-lib";
 import { Construct } from "constructs";
 import { SharedProps } from "./constructs/shared-props";
 import { DatadogECSFargate, DatadogLambda } from "datadog-cdk-constructs-v2";
-import { Network } from "./network";
+import { SharedResources } from "./sharedResources";
 import { Api } from "./api";
 import { Cluster } from "aws-cdk-lib/aws-ecs";
 import { BackgroundWorkers } from "./background-workers";
@@ -22,15 +22,15 @@ export class UserServiceStack extends cdk.Stack {
       throw new Error("CONNECTION_STRING environment variable is required");
     }
 
-    const network = new Network(this, "Network", {
+    const sharedResources = new SharedResources(this, "SharedResources", {
       networkName: `${serviceName}-${environment}-vpc`,
     });
 
     const ddSite = process.env.DD_SITE || "datadoghq.com";
     const ddApiKey = process.env.DD_API_KEY || "";
 
     const cluster = new Cluster(this, "ApiCluster", {
-      vpc: network.vpc,
+      vpc: sharedResources.vpc,
       clusterName: `${serviceName}-${environment}`,
     });
 
@@ -86,12 +86,13 @@ export class UserServiceStack extends cdk.Stack {
 
     const api = new Api(this, "Api", {
       sharedProps: sharedProps,
-      vpc: network.vpc,
+      vpc: sharedResources.vpc,
       cluster: cluster,
     });
 
     const backgroundWorkers = new BackgroundWorkers(this, "BackgroundWorkers", {
       sharedProps: sharedProps,
+      sharedEventBus: sharedResources.sharedEventBus,
       stickerClaimedQueue: api.stickerClaimedQueue,
       stickerClaimedDLQ: api.stickerClaimedDLQ,
       userRegisteredTopic: api.userRegisteredTopic,