Skip to main content

Copilot Instructions

sdlcs-aws-cdk-lib

This is something new

Product Instructions​

Apply the Product Instructions to all code.

TechStack Instructions​

Apply the TechStack Instructions to all code.

Documentation Instructions​

Apply the Documentation Instructions to all code.

Code Quality Principles​

  • Readability: Easy to read, understand, test, and maintain
  • Operability: Easy to deploy, scale, monitor, and debug
  • Maintainability: Easy to secure, document, refactor, and optimize
  • Extensibility: Easy to extend with new features
  • Imports: Use direct imports (e.g., Duration instead of cdk.Duration)

Workspace Backend​

CDK Stacks​

  • Auth Stack: Manages user authentication with AWS Cognito and Clerk.
  • API Stack: Sets up the API Gateway, Lambda functions, and DynamoDB tables.
  • Frontend Stack: Deploys the React application to S3 and configures CloudFront for CDN.
  • Email Stack: Configures AWS SES for email notifications.
  • Each CDK Stack must be in its own file
  • File name must match the stack name in PascalCase format
  • Example: MyStack.ts for a stack named MyStack
  • Place stack files in the lib directory (no subdirectories)

CDK Stack Coding Conventions​

  • Use cdk-nag to enforce best practices and security checks.
  • Use cdk-assert for unit testing CDK stacks.
  • Never hardcode sensitive information like API keys or secrets in the codebase.
  • Never Use cdk outputs to link resources across stacks. Instead, use ssm parameters.

CDK Constructs​

  • Each AWS resource should be defined in its own Construct
  • Place constructs in lib/{resourceType}/ subdirectories
  • File name must match the Construct name in PascalCase format
  • Make all resources public properties for stack access
  • Must follow standard CDK Construct patterns

Lambda Functions​

  • Always written in TypeScript
  • Organize in src/lambda/{lambdaName} directories for individual lambdas
  • src/lambda/ must be configured as a separate npm workspace
  • Filename must match the lambda name in camelCase format
  • Each lambda must have:
    • Its own package.json
    • Its own tsconfig.json
    • Its own .gitignore
    • Jest tests in its own test directory
  • Always use the NodeJSFunction construct from AWS CDK
  • Specify runtime as Runtime.NODEJS_20_X
  • API methods for example: ['GET', 'POST', 'PUT', 'DELETE'] should be in a single lambdas

Workspace Frontend​

Style Consistency​

  • All new product sections must use shared UI components from src/frontend/components/ui where possible.
  • Tailwind CSS configuration is centralized; do not override styles locally unless necessary.
  • Follow the design tokens and UI patterns documented in /docs/frontend/style-guide.md.
  • When adding new UI components, update the style guide and, if using, Storybook stories.
  • Ensure all frontend code is reviewed for visual and interaction consistency with existing sections.

Workspace Shared​

Domain Model Definitions​

  • All domain models (e.g., Building, LedgerEntry, Unit) are defined in shared/models/.
  • Always import types from shared/models in all backend, frontend, and lambda code.
  • Update or refactor model definitions only in this folder.
  • When adding new models, create a new file in shared/models and export from shared/models/index.ts.
  • All models must include an ownerId field for SaaS multi-tenancy. This is assigned at master account creation and used as the subdomain name.
  • All API, DynamoDB, and business logic must scope data by ownerId.
  • On signup, only master accounts are created, requiring a max 40 character valid word for the subdomain. Sub-users can only be invited by the administrator via the users screen.
  • Use Clerk.com organization feature for member management and invitations.
  • Lambda@Edge must augment all API claims with the ownerId from the subdomain.
  • This ensures consistency, easy refactoring, and version control of all domain types and multi-tenant logic.