init

profiles/cdk-ts.md

@@ -0,0 +1,378 @@
+# CDK TypeScript Profile
+
+## Concept → CDK Mapping
+
+| ABC Concept   | Meaning                 | CDK Mapping                             |
+|---------------|-------------------------|-----------------------------------------|
+| ABC‑C0        | Construct               | `Construct` subclass                    |
+| ABC‑C1        | Application Stack       | `Stack` subclass                        |
+| ABC‑C2        | Logical Unit (LU)       | `Construct` subclass with LU semantics  |
+| ABC‑C3        | Resource Group (RG)     | `Construct` subclass with RG semantics  |
+| ABC‑C4        | Input Contract          | TypeScript interface (`InputContract`)  |
+| ABC‑C5        | Output Contract         | TypeScript interface (`OutputContract`) |
+| ABC‑C6        | Instantiation Interface | Constructor (`scope`, `id`, `inputs`)   |
+| ABC‑C7        | Capturing Down          | Passing inputs to children              |
+| ABC‑C8        | Bubbling Up             | Exposing outputs upward                 |
+
+*ABC* itself remains naming‑agnostic; this profile defines CDK‑idiomatic
+conventions.
+
+## Rules
+
+These are profile‑specific rules for CDK-Typescript users.
+
+### ABC-PROFILE-CDKTS‑R1 (SHOULD)
+
+The directory structure SHOULD reflect the ABC hierarchy:
+
+Application Stack → Logical Units → Resource Groups.
+
+### ABC-PROFILE-CDKTS‑R2 (SHOULD)
+
+Each Logical Unit SHOULD reside in its own top‑level directory:
+
+```default
+src/
+  app-stack.ts
+  data/
+  logic/
+  presentation/
+```
+
+### ABC-PROFILE-CDKTS‑R3 (SHOULD)
+
+Each Resource Group SHOULD reside inside its parent Logical Unit:
+
+```default
+src/data/storage/
+src/data/database/
+```
+
+### ABC-PROFILE-CDKTS‑R4 (SHOULD)
+
+Each construct directory SHOULD contain an index.ts exporting the construct.
+
+### ABC-PROFILE-CDKTS‑R5 (SHOULD)
+
+File and directory names SHOULD follow CDK naming conventions.
+
+### ABC-PROFILE-CDKTS‑R6 (MAY)
+
+Modules MAY split into multiple files if needed, as long as they remain in the
+same directory.
+
+### ABC-PROFILE-CDKTS‑R7 (SHOULD)
+
+Each construct module SHOULD define its own `InputContract` and
+`OutputContract`.
+
+### ABC-PROFILE-CDKTS‑R8 (SHOULD)
+
+Within a module, contracts SHOULD be named simply `InputContract` and
+`OutputContract`.
+
+### ABC-PROFILE-CDKTS‑R9 (SHOULD)
+
+When importing contracts from another module, they SHOULD be aliased:
+
+### ABC-PROFILE-CDKTS‑R10 (MUST)
+
+Constructs MUST be instantiated using a single InputContract object.
+
+Also see ABC‑R30/32.
+
+### ABC-PROFILE-CDKTS‑R11 (MUST)
+
+All cross‑construct wiring MUST occur in the parent construct.
+
+Also see ABC‑R44.
+
+### ABC-PROFILE-CDKTS‑R12 (SHOULD)
+
+Imported contracts SHOULD be aliased to descriptive names.
+
+### ABC-PROFILE-CDKTS‑R13 (SHOULD)
+
+Contracts SHOULD be co‑located with their construct modules.
+
+### ABC-PROFILE-CDKTS‑R14 (SHOULD)
+
+Generated code SHOULD mirror the ABC hierarchy in structure and composition.
+
+### ABC-PROFILE-CDKTS‑R15 (SHOULD)
+
+Construct internals SHOULD NOT be accessed except through outputs.
+
+### ABC-PROFILE-CDKTS‑R16 (SHOULD)
+
+Constructs SHOULD be generated in ABC order: Resource Groups → Logical Units →
+Application Stack.
+
+## Base ABC Classes for Typescript-CDK
+
+### Core Types
+
+```javascript
+export interface InputContract {}
+export interface OutputContract {}
+
+export interface HasOutputs<TOutputs extends OutputContract> {
+  readonly outputs: TOutputs;
+}
+```
+
+### Application Stack Base
+
+```javascript
+import { Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { OutputContract } from './core-types';
+
+export abstract class ABCApplicationStack<
+  TOutputs extends OutputContract = OutputContract
+> extends Stack {
+  public abstract readonly outputs: TOutputs;
+
+  protected constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+  }
+}
+```
+
+### Logical Unit Base
+
+```javascript
+import { Construct } from 'constructs';
+import { InputContract, OutputContract, HasOutputs } from './core-types';
+
+export abstract class ABCLogicalUnit<
+  TInputs extends InputContract,
+  TOutputs extends OutputContract
+> extends Construct implements HasOutputs<TOutputs> {
+  public abstract readonly outputs: TOutputs;
+  protected readonly inputs: TInputs;
+
+  protected constructor(scope: Construct, id: string, inputs: TInputs) {
+    super(scope, id);
+    this.inputs = Object.freeze({ ...inputs }) as TInputs;
+  }
+}
+```
+
+### Resource Group Base
+
+```javascript
+import { Construct } from 'constructs';
+import { InputContract, OutputContract, HasOutputs } from './core-types';
+
+export abstract class ABCResourceGroup<
+  TInputs extends InputContract,
+  TOutputs extends OutputContract
+> extends Construct implements HasOutputs<TOutputs> {
+  public abstract readonly outputs: TOutputs;
+  protected readonly inputs: TInputs;
+
+  protected constructor(scope: Construct, id: string, inputs: TInputs) {
+    super(scope, id);
+    this.inputs = Object.freeze({ ...inputs }) as TInputs;
+  }
+}
+```
+
+## Logical Units & Resource Groups (Canonical Example)
+
+Below is the full 3‑tier example implemented in CDK.
+
+### Data Logical Unit
+
+```default
+src/data/index.ts
+src/data/storage/index.ts
+src/data/database/index.ts
+```
+
+```javascript
+import { Construct } from 'constructs';
+import { ABCLogicalUnit } from '../abc/logical-unit';
+import { StorageGroup } from './storage';
+import { DatabaseGroup } from './database';
+
+export interface InputContract {
+  environment: string;
+  region: string;
+  storageClass: string;
+  dbEngine: string;
+  dbInstanceSize: string;
+}
+
+export interface OutputContract {
+  storageBucketName: string;
+  databaseEndpoint: string;
+}
+
+export class DataUnit extends ABCLogicalUnit<InputContract, OutputContract> {
+  public readonly outputs: OutputContract;
+
+  constructor(scope: Construct, id: string, inputs: InputContract) {
+    super(scope, id, inputs);
+
+    const storage = new StorageGroup(this, 'Storage', {
+      environment: inputs.environment,
+      region: inputs.region,
+      storageClass: inputs.storageClass,
+    });
+
+    const database = new DatabaseGroup(this, 'Database', {
+      environment: inputs.environment,
+      dbEngine: inputs.dbEngine,
+      dbInstanceSize: inputs.dbInstanceSize,
+    });
+
+    this.outputs = {
+      storageBucketName: storage.outputs.storageBucketName,
+      databaseEndpoint: database.outputs.databaseEndpoint,
+    };
+  }
+}
+```
+
+#### Storage Resource Group
+
+```default
+import { Construct } from 'constructs';
+import { ABCResourceGroup } from '../../abc/resource-group';
+
+export interface InputContract {
+  environment: string;
+  region: string;
+  storageClass: string;
+}
+
+export interface OutputContract {
+  storageBucketName: string;
+}
+
+export class StorageGroup extends ABCResourceGroup<InputContract, OutputContract> {
+  public readonly outputs: OutputContract;
+
+  constructor(scope: Construct, id: string, inputs: InputContract) {
+    super(scope, id, inputs);
+
+    this.outputs = {
+      storageBucketName: 'bucket-name-placeholder',
+    };
+  }
+}
+```
+
+#### Database Resource Group
+
+```default
+import { Construct } from 'constructs';
+import { ABCResourceGroup } from '../../abc/resource-group';
+
+export interface InputContract {
+  environment: string;
+  dbEngine: string;
+  dbInstanceSize: string;
+}
+
+export interface OutputContract {
+  databaseEndpoint: string;
+}
+
+export class DatabaseGroup extends ABCResourceGroup<InputContract, OutputContract> {
+  public readonly outputs: OutputContract;
+
+  constructor(scope: Construct, id: string, inputs: InputContract) {
+    super(scope, id, inputs);
+
+    this.outputs = {
+      databaseEndpoint: 'db-endpoint-placeholder',
+    };
+  }
+}
+```
+
+### Logic Logical Unit
+
+```default
+src/logic/index.ts
+src/logic/compute/index.ts
+src/logic/messaging/index.ts
+```
+
+Compute Resource Group and Messaging Resource Group follow the same pattern.
+
+### Presentation Logical Unit
+
+```default
+src/presentation/index.ts
+src/presentation/webapp/index.ts
+src/presentation/cdn/index.ts
+```
+
+WebApp Resource Group and CDN Resource Group follow the same pattern.
+
+## Application Stack
+
+```javascript
+import { Construct } from 'constructs';
+import { ABCApplicationStack } from './abc/application-stack';
+import { DataUnit } from './data';
+import type { InputContract as DataUnitInput } from './data';
+import { LogicUnit } from './logic';
+import type { InputContract as LogicUnitInput } from './logic';
+import { PresentationUnit } from './presentation';
+import type { InputContract as PresentationUnitInput } from './presentation';
+
+export interface InputContract {
+  environment: string;
+  region: string;
+  globalTags?: Record<string, string>;
+}
+
+export interface OutputContract {
+  frontendUrl: string;
+  apiEndpoint: string;
+}
+
+export class AppStack extends ABCApplicationStack<OutputContract> {
+  public readonly outputs: OutputContract;
+
+  constructor(scope: Construct, id: string, inputs: InputContract) {
+    super(scope, id);
+
+    const dataInputs: DataUnitInput = {
+      environment: inputs.environment,
+      region: inputs.region,
+      storageClass: 'STANDARD',
+      dbEngine: 'postgres',
+      dbInstanceSize: 'db.t3.micro',
+    };
+    const dataUnit = new DataUnit(this, 'DataUnit', dataInputs);
+
+    const logicInputs: LogicUnitInput = {
+      environment: inputs.environment,
+      region: inputs.region,
+      computeSize: 'small',
+      messageRetention: 1209600,
+      databaseEndpoint: dataUnit.outputs.databaseEndpoint,
+    };
+    const logicUnit = new LogicUnit(this, 'LogicUnit', logicInputs);
+
+    const presentationInputs: PresentationUnitInput = {
+      environment: inputs.environment,
+      region: inputs.region,
+      frontendAssetsBucket: dataUnit.outputs.storageBucketName,
+      apiEndpoint: logicUnit.outputs.apiEndpoint,
+    };
+    const presentationUnit = new PresentationUnit(this, 'PresentationUnit', presentationInputs);
+
+    this.outputs = {
+      frontendUrl: presentationUnit.outputs.frontendUrl,
+      apiEndpoint: logicUnit.outputs.apiEndpoint,
+    };
+  }
+}
+```