@nikovirtala/projen-typedoc 0.0.0

package/.amazonq/rules/standards.md

@@ -0,0 +1,320 @@
+# Business domain
+
+We operate in the retail business, offering services across:
+
+- supermarket trade
+- department store trade
+- specialty store trade
+
+All code examples, domain modeling, and ubiquitous language should reflect retail business concepts (products, assortments, customers, orders, pricing, promotions, etc.).
+
+# Design philosophy
+
+- Favor simplicity over cleverness. Use the simplest solution that solves the core problem. Avoid premature optimization and unnecessary abstractions.
+- Apply Domain-Driven Design with Hexagonal Architecture. Organize code by bounded contexts with a clear separation between domain logic (core), application services (ports), and infrastructure adapters. The domain layer must not depend on external concerns.
+
+# Domain-Driven Design and Hexagonal Architecture
+
+- Structure code by bounded contexts. Each context is independently deployable with its own domain model, application layer, and adapters.
+- Keep domain logic pure. Domain entities, value objects, and aggregates must not import infrastructure code (AWS SDK, database clients, external APIs).
+- Define ports as interfaces in the application layer. Implement adapters in the infrastructure layer (DynamoDB repositories, event publishers, Lambda function handlers).
+- Use ubiquitous language from the business domain in all code, tests, and documentation. Avoid technical jargon in domain layer naming.
+- Communicate between bounded contexts exclusively through domain events. Never share domain models or databases across contexts.
+- Use Anti-Corruption Layer (ACL) adapters when integrating with external systems or legacy services. The ACL translates external models and protocols into your bounded context's domain language, preventing external concepts from polluting your domain model.
+- Cache raw external data before ACL transformation. Store the original payload from external systems (APIs, message queues, webhooks) in DynamoDB with a TTL before processing through the ACL. This enables replay and reprocessing if bugs are discovered in the ACL or business logic, without depending on external system retention policies or availability. Use key pattern: `pk: "RAW#<source>#<id>"`, `sk: "RAW#<timestamp>"`. For financial data, set TTL to 6 years to meet regulatory retention requirements. Use DynamoDB Standard-IA storage class for raw data to optimize costs.
+
+# Architecture
+
+- Default to event-driven architecture. Use events for bounded context communication.
+- Use AWS serverless architecture (Lambda, API Gateway, DynamoDB, EventBridge, etc.).
+- Use AWS CDK (TypeScript) for infrastructure as code.
+- Kafka is hosted on Confluent Cloud.
+
+# Project structure
+
+Each bounded context is a separate git repository organized by hexagonal layers under `src/`:
+
+- `src/domain/` - Entities, value objects, aggregates, domain events (pure TypeScript, no external dependencies)
+- `src/application/` - Use cases and port interfaces (depends only on domain)
+- `src/infrastructure/` - Adapters: repositories, event publishers, Lambda function handlers, Zod schemas (implements ports)
+- `src/stacks/` - CDK stack definitions
+- `src/constructs/` - Reusable CDK constructs
+- `src/` - CDK app entry point
+
+# Documents
+
+- Write all documents in Markdown format.
+- Use sentence case for all document headings (capitalize only the first word and proper nouns).
+- Design documents must include relevant Mermaid visualizations: logical architecture diagrams, process flowcharts, ER models, or sequence diagrams.
+
+# Code documentation
+
+- Use TSDoc for all code documentation. Include appropriate TSDoc tags (@param, @returns, @throws, @example, @deprecated, etc.) to fully describe the API contract.
+- Document all interface properties and enum members with TSDoc comments. Every property and enum value must have a description explaining its purpose and constraints.
+- Include reference links to AWS service documentation when documenting code that uses AWS services. Use @see tag with the relevant docs.aws.amazon.com URL.
+- Add extensive inline documentation throughout business logic and utility code using block comments (`/* */`) to document:
+  - The "what": What the code is doing and why it exists
+  - The "why": Business rules, assumptions, constraints, and reasoning behind implementation decisions
+  - Focus on intent and context, not just mechanics
+- Avoid single-line (`//`) comments for documentation.
+
+# Coding standards
+
+- Use latest TypeScript and Node.js LTS versions.
+- Use TypeScript with ES modules.
+- Use descriptive names; avoid single-letter variables except in loops.
+- Do not expose implementation details in business-facing names. Use domain language for entities, events, use cases, AWS resources, and API endpoints. Reserve technical terms (like "bitemporal", "CQRS", "event-sourced") for infrastructure code, internal documentation, and reusable generic components.
+- Do not use any type. Use specific types or unknown instead.
+- Avoid type assertions (`as` keyword). Use Zod for runtime validation and type inference when handling external data. Use type guards for narrowing types when runtime checks are needed.
+- Use Zod schemas in infrastructure adapters for runtime validation of external data (API requests, database records, event payloads). Keep domain types as pure TypeScript interfaces without runtime validation dependencies.
+- Use JSON format for all logging output.
+- Avoid `forEach()`. Use `for...of` for iteration with async/await or control flow, or use functional methods like `map()`, `filter()`, and `reduce()` for transformations.
+- Use async/await syntax, including top-level await. Parallelize independent operations with `Promise.all()` or `Promise.allSettled()`.
+- Prefer immutable data. Use `const` and avoid mutating objects or arrays.
+- Do not use Express or other traditional web frameworks. Use AWS serverless services (API Gateway, Lambda) for HTTP APIs.
+- Use nullish coalescing.
+- Use satisfies for object literals.
+
+# Data structures
+
+- Use ISO 8601 format for timestamps in data structures to enable lexicographic sorting. Include at least millisecond precision and timezone offset (e.g., `2025-10-30T09:10:51.312+02:00`). Prefer Europe/Helsinki timezone when generating timestamps.
+- Use lowerCamelCase for all data structure attribute/property names.
+- Use PascalCase for classes and interfaces.
+- Use UPPER_SNAKE_CASE for constants.
+
+# DynamoDB
+
+- Each bounded context owns a single DynamoDB table with overloaded `pk`/`sk` keys and GSIs for its access patterns. Use multi-table design within a context only when tables have fundamentally different characteristics (e.g., one table with append-only writes and another with mutable writes).
+- Use lowercase for DynamoDB key attribute names. Default keys: partition key `pk` (string), sort key `sk` (string). GSI keys follow the pattern `gsi1pk`, `gsi1sk`, `gsi2pk`, `gsi2sk`, etc.
+- Use DynamoDB `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb`.
+- Use DynamoDB Streams for event-driven patterns.
+- Enable bisect on function error for DynamoDB Stream event sources.
+- Design DynamoDB access patterns to use Query operations (avoid Scan).
+- Use DynamoDB transactions (`transactWrite` and `transactGet`) for atomic operations across multiple items. Always include condition expressions to verify that source data hasn't changed since it was read.
+
+# AWS SDK
+
+- Use latest major version of the AWS SDK for JavaScript.
+
+# AWS CDK project management
+
+- Check if the project uses Projen (.projenrc.ts or .projenrc.js). If Projen is configured, use it for all project configuration and dependency management.
+- Do not manually edit package.json, tsconfig.json, or other generated files in Projen projects.
+
+# AWS CDK imports
+
+- Import AWS service constructs from the main `aws-cdk-lib` package using named imports with underscore notation.
+- Do not use namespace imports from service-specific subpaths.
+
+**Correct:**
+
+```typescript
+import { aws_lambda, aws_dynamodb, aws_s3 } from "aws-cdk-lib";
+
+const fn = new aws_lambda.Function(this, "MyFunction", { ... });
+const table = new aws_dynamodb.Table(this, "MyTable", { ... });
+```
+
+**Incorrect:**
+
+```typescript
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+```
+
+# AWS CDK security and networking
+
+- Follow least privilege principle for all IAM permissions.
+- Prefer CDK grant methods (e.g., `bucket.grantRead()`, `table.grantWriteData()`) over creating custom IAM roles and policies.
+- For network security groups, use the `connections` property (e.g., `lambda.connections.allowTo()`, `rds.connections.allowFrom()`) instead of manually managing security group rules.
+
+# AWS Lambda
+
+- Use latest available LTS version of Node.js runtime.
+- Use ARM-based architecture.
+- Use AWS CDK `NodeJsFunction` construct to bundle the handler code.
+- For Lambda functions triggered by DynamoDB Streams, enable `bisectBatchOnError: true` on the event source mapping.
+
+# Amazon CloudFront
+
+- Use CloudFront distributions for serving static content.
+- Configure S3 buckets as CloudFront origins with Origin Access Control (OAC).
+- Use CloudFront VPC origins for private Application Load Balancers and other VPC resources.
+
+# Terminology
+
+Use these proper nouns with exact capitalization:
+
+- Sales Flow
+- Session Event
+- Session Service
+- Session Event Design Document
+- Session Service Design Document
+
+# Testing
+
+- All code must have test coverage: use unit tests for business-logic and utility code, integration tests for Lambda function handlers, CDK assertions for infrastructure code.
+- Test domain logic in isolation without any infrastructure dependencies or mocks.
+- If no testing framework is configured, use Vitest.
+- Avoid mocking in tests. Prefer dependency injection and testing pure functions with real implementations. For AWS services, use local alternatives (e.g., DynamoDB Local, LocalStack) or in-memory implementations for integration tests.
+
+# Error handling
+
+- Use custom error classes. Extend the base `Error` class and set the error name.
+- Define all errors in `src/domain/errors.ts` (or `src/domain/errors/` for multiple files).
+- Domain errors represent business rule violations (e.g., `InvalidPriceError`, `ProductNotAvailableError`).
+- Application errors represent operational failures (e.g., `ProductNotFoundError`, `ConcurrencyError`).
+- Infrastructure errors represent technical failures (e.g., `DatabaseConnectionError`, `ExternalServiceError`).
+- Lambda handlers must catch errors and map them to appropriate HTTP status codes or event handling logic.
+- Include relevant context in error messages and properties. Never expose sensitive data.
+- Configure dead letter queues (DLQ) for all asynchronous Lambda invocations, DynamoDB Streams, EventBridge rules, and SNS subscriptions.
+
+**Example:**
+
+```typescript
+export class InvalidPriceError extends Error {
+  constructor(price: number) {
+    super(`Price must be positive, got ${price}`);
+    this.name = "InvalidPriceError";
+  }
+}
+
+export class ProductNotFoundError extends Error {
+  constructor(public readonly productId: string) {
+    super(`Product not found: ${productId}`);
+    this.name = "ProductNotFoundError";
+  }
+}
+```
+
+# Idempotency
+
+- Design all event handlers and async operations to be idempotent.
+- Use DynamoDB conditional writes with idempotency keys. Store the idempotency key with a TTL.
+- For DynamoDB Stream handlers, use the event ID from the stream record as the idempotency key.
+- For EventBridge events, include a unique event ID in the event payload and use it as the idempotency key.
+- Store idempotency records in the same table as your domain data using key pattern: `pk: "IDEMPOTENCY#<eventId>"`, `sk: "IDEMPOTENCY"`.
+- Set TTL on idempotency records (e.g., 24 hours).
+
+**Example:**
+
+```typescript
+async function handleProductUpdate(event: DynamoDBStreamEvent) {
+  for (const record of event.Records) {
+    const idempotencyKey = record.eventID;
+
+    try {
+      await dynamodb.put({
+        TableName: TABLE_NAME,
+        Item: {
+          pk: `IDEMPOTENCY#${idempotencyKey}`,
+          sk: "IDEMPOTENCY",
+          ttl: Math.floor(Date.now() / 1000) + 86400, // 24 hours
+        },
+        ConditionExpression: "attribute_not_exists(pk)",
+      });
+
+      // Process the event - this only runs if idempotency key was successfully stored
+      await processProductUpdate(record);
+    } catch (error) {
+      if (error.name === "ConditionalCheckFailedException") {
+        // Already processed, skip
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+```
+
+# Observability
+
+- Emit a single context-rich structured log (wide event) per service hop for each request.
+- Use high-cardinality fields (user IDs, request IDs, entity IDs).
+- Include high-dimensional data with many fields.
+- Connect all events for a request using a correlation ID (request ID or trace ID).
+- Redact sensitive data (passwords, tokens, PII) before logging.
+
+**Required fields in all events:**
+
+- `requestId` - Correlation ID for the entire request flow
+- `timestamp` - ISO 8601 format with timezone
+- `service` - Service name
+- `message` - Human-readable description
+- `outcome` - Result status (e.g., "ok", "error")
+- `duration` - Operation duration in milliseconds
+
+**Recommended context fields:**
+
+- Request details: `method`, `path`, `statusCode`, `headers`
+- User context: `userId`, user properties relevant to business logic
+- Entity data: Full entity objects involved in the operation
+- Infrastructure: `commitHash`, database queries, cache operations
+- Downstream calls: Service names, durations, status codes
+
+**Example wide event:**
+
+```json
+{
+  "requestId": "8bfdf7ecdd485694",
+  "timestamp": "2024-09-08T06:14:05.680+03:00",
+  "service": "order-processing",
+  "message": "Order placed",
+  "outcome": "ok",
+  "duration": 268,
+  "commitHash": "690de31f245eb4f2160643e0dbb5304179a1cdd3",
+  "event": {
+    "type": "OrderPlaced",
+    "source": "order-service",
+    "eventId": "evt_f8d4d21c-f1fd-48b9"
+  },
+  "customer": {
+    "id": "cust_fdc4ddd4-8b30",
+    "segment": "premium",
+    "storeId": "store-123"
+  },
+  "order": {
+    "id": "ord_f8d4d21c-f1fd",
+    "totalAmount": 45.99,
+    "itemCount": 3,
+    "fulfillmentType": "home-delivery"
+  },
+  "dynamodb": {
+    "operation": "transactWrite",
+    "items": [
+      {
+        "table": "orders-table",
+        "pk": "ORDER#ord_f8d4d21c-f1fd",
+        "sk": "METADATA",
+        "operation": "put"
+      },
+      {
+        "table": "orders-table",
+        "pk": "CUSTOMER#cust_fdc4ddd4-8b30",
+        "sk": "ORDER#ord_f8d4d21c-f1fd",
+        "operation": "put"
+      }
+    ],
+    "duration": 45
+  },
+  "downstream": {
+    "eventBridge": {
+      "eventBus": "retail-events",
+      "published": true,
+      "duration": 12
+    }
+  }
+}
+```
+
+# Formal modeling
+
+When designing logic for event-driven architectures, distributed systems, or asynchronous communication patterns:
+
+- Model the system using P language (https://p-org.github.io/P/) to formally verify correctness
+- Define state machines for each component/actor in the system
+- Specify safety properties (what should never happen) and liveness properties (what should eventually happen)
+- Model all possible event orderings and race conditions
+- Use P's model checker to verify the design before implementation
+- Include the P model specification alongside architecture diagrams
+- Focus on modeling: message protocols, failure scenarios, concurrent interactions, and state transitions