@cdklabs/cdk-appmod-catalog-blueprints 1.0.0

package/lib/document-processing/base-document-processing.d.ts

@@ -0,0 +1,189 @@
+import { Duration, RemovalPolicy } from 'aws-cdk-lib';
+import { IMetric } from 'aws-cdk-lib/aws-cloudwatch';
+import { Table } from 'aws-cdk-lib/aws-dynamodb';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
+import { Bucket } from 'aws-cdk-lib/aws-s3';
+import { Queue } from 'aws-cdk-lib/aws-sqs';
+import { StateMachine } from 'aws-cdk-lib/aws-stepfunctions';
+import { BedrockInvokeModel, LambdaInvoke, StepFunctionsStartExecution } from 'aws-cdk-lib/aws-stepfunctions-tasks';
+import { Construct } from 'constructs';
+import { Network } from '../framework';
+import { EventbridgeBroker } from '../framework/foundation/eventbridge-broker';
+import { LogGroupDataProtectionProps } from '../utilities';
+import { IObservable, ObservableProps } from '../utilities/observability/observable';
+/**
+ * Configuration properties for BaseDocumentProcessing construct.
+ */
+export interface BaseDocumentProcessingProps extends ObservableProps {
+    /**
+     * S3 bucket for document storage with organized prefixes (raw/, processed/, failed/).
+     * If not provided, a new bucket will be created with auto-delete enabled based on removalPolicy.
+     */
+    readonly bucket?: Bucket;
+    /**
+     * DynamoDB table for storing document processing metadata and workflow state.
+     * If not provided, a new table will be created with DocumentId as partition key.
+     */
+    readonly documentProcessingTable?: Table;
+    /**
+     * SQS queue visibility timeout for processing messages.
+     * Should be longer than expected processing time to prevent duplicate processing.
+     * @default Duration.seconds(300)
+     */
+    readonly queueVisibilityTimeout?: Duration;
+    /**
+     * The number of times a message can be unsuccessfully dequeued before being moved to the dead-letter queue.
+     *
+     * @default 5
+     */
+    readonly dlqMaxReceiveCount?: number;
+    /**
+     * Maximum execution time for the Step Functions workflow.
+     * @default Duration.minutes(30)
+     */
+    readonly workflowTimeout?: Duration;
+    /**
+     * Removal policy for created resources (bucket, table, queue).
+     * @default RemovalPolicy.DESTROY
+     */
+    readonly removalPolicy?: RemovalPolicy;
+    /**
+     * Optional EventBridge broker for publishing custom events during processing.
+     * If not provided, no custom events will be sent out.
+     */
+    readonly eventbridgeBroker?: EventbridgeBroker;
+    /**
+     * Enable logging and tracing for all supporting resource
+     * @default false
+     */
+    readonly enableObservability?: boolean;
+    /**
+     * Resources that can run inside a VPC will follow the provided network configuration
+     * @default resources will run outside of a VPC
+     */
+    readonly network?: Network;
+    /**
+     * KMS key to be used.
+     * @default A new key would be created
+     */
+    readonly encryptionKey?: Key;
+}
+/**
+ * S3 prefix constants for organizing documents throughout the processing lifecycle.
+ *
+ * Documents flow through these prefixes based on processing outcomes:
+ * - Upload → raw/ (triggers processing)
+ * - Success → processed/ (workflow completed successfully)
+ * - Failure → failed/ (workflow encountered errors)
+ */
+export declare enum DocumentProcessingPrefix {
+    /** Prefix for newly uploaded documents awaiting processing */
+    RAW = "raw/",
+    /** Prefix for documents that failed processing */
+    FAILED = "failed/",
+    /** Prefix for successfully processed documents */
+    PROCESSED = "processed/"
+}
+/**
+ * Union type for Step Functions tasks that can be used in document processing workflows.
+ * Supports Bedrock model invocation, Lambda function invocation, and nested Step Functions execution.
+ */
+export type DocumentProcessingStepType = BedrockInvokeModel | LambdaInvoke | StepFunctionsStartExecution;
+/**
+ * Abstract base class for serverless document processing workflows.
+ *
+ * Provides a complete document processing pipeline with:
+ * - **S3 Storage**: Organized with prefixes (raw/, processed/, failed/) for document lifecycle management
+ * - **SQS Queue**: Reliable message processing with configurable visibility timeout and dead letter queue
+ * - **DynamoDB Table**: Workflow metadata tracking with DocumentId as partition key
+ * - **Step Functions**: Orchestrated workflow with automatic file movement based on processing outcome
+ * - **Auto-triggering**: S3 event notifications automatically start processing when files are uploaded to raw/ prefix
+ * - **Error Handling**: Failed documents are moved to failed/ prefix with error details stored in DynamoDB
+ * - **EventBridge Integration**: Optional custom event publishing for workflow state changes
+ *
+ * ## Architecture Flow
+ * S3 Upload (raw/) → SQS → Lambda Consumer → Step Functions → Processing Steps → S3 (processed/failed/)
+ *
+ * ## Implementation Requirements
+ * Subclasses must implement four abstract methods to define the processing workflow:
+ * - `classificationStep()`: Document type classification
+ * - `extractionStep()`: Data extraction from documents
+ * - `enrichmentStep()`: Optional data enrichment (return undefined to skip)
+ * - `postProcessingStep()`: Optional post-processing (return undefined to skip)
+ */
+export declare abstract class BaseDocumentProcessing extends Construct implements IObservable {
+    /** Business metric service name. This is part of the initial service dimension */
+    readonly metricServiceName: string;
+    /** Business metric namespace. */
+    readonly metricNamespace: string;
+    /** log group data protection configuration */
+    readonly logGroupDataProtection: LogGroupDataProtectionProps;
+    /** S3 bucket for document storage with organized prefixes (raw/, processed/, failed/) */
+    readonly bucket: Bucket;
+    /** SQS queue for reliable message processing with dead letter queue support */
+    readonly queue: Queue;
+    /** DynamoDB table for storing document processing metadata and workflow state */
+    readonly documentProcessingTable: Table;
+    /** Configuration properties for the document processing pipeline */
+    private readonly props;
+    /** Dead letter queue  */
+    readonly deadLetterQueue: Queue;
+    /** KMS key */
+    readonly encryptionKey: Key;
+    /** Encryption key used by the DocumentProcessingBucket */
+    readonly bucketEncryptionKey?: IKey;
+    /**
+     * Creates a new BaseDocumentProcessing construct.
+     *
+     * Initializes the complete document processing infrastructure including S3 bucket,
+     * SQS queue, DynamoDB table, and sets up S3 event notifications to trigger processing.
+     *
+     * @param scope - The scope in which to define this construct
+     * @param id - The scoped construct ID. Must be unique within the scope.
+     * @param props - Configuration properties for the document processing pipeline
+     */
+    constructor(scope: Construct, id: string, props: BaseDocumentProcessingProps);
+    protected handleStateMachineCreation(stateMachineId: string): StateMachine;
+    protected handleWorkflowTrigger(stateMachine: StateMachine): void;
+    private createSQSConsumerLambda;
+    private createStateMachineRole;
+    private createMoveToFailedChain;
+    private createMoveToProcessedChain;
+    metrics(): IMetric[];
+    /**
+     * Defines the document classification step of the workflow.
+     *
+     * **CRITICAL**: Must set `outputPath` to preserve workflow state for subsequent steps.
+     * The classification result should be available at `$.classificationResult` for DynamoDB storage.
+     *
+     * @returns Step Functions task for document classification
+     */
+    protected abstract classificationStep(): DocumentProcessingStepType;
+    /**
+     * Defines the document processing step of the workflow.
+     *
+     * **CRITICAL**: Must set `outputPath` to preserve workflow state for subsequent steps.
+     * The extraction result should be available at `$.processingResult` for DynamoDB storage.
+     *
+     * @returns Step Functions task for document extraction
+     */
+    protected abstract processingStep(): DocumentProcessingStepType;
+    /**
+     * Defines the optional document enrichment step of the workflow.
+     *
+     * **CRITICAL**: If implemented, must set `outputPath` to preserve workflow state.
+     * The enrichment result should be available at `$.enrichedResult` for DynamoDB storage.
+     *
+     * @returns Step Functions task for document enrichment, or undefined to skip this step
+     */
+    protected abstract enrichmentStep(): DocumentProcessingStepType | undefined;
+    /**
+     * Defines the optional post-processing step of the workflow.
+     *
+     * **CRITICAL**: If implemented, must set `outputPath` to preserve workflow state.
+     * The post-processing result should be available at `$.postProcessedResult` for DynamoDB storage.
+     *
+     * @returns Step Functions task for post-processing, or undefined to skip this step
+     */
+    protected abstract postProcessingStep(): DocumentProcessingStepType | undefined;
+}