fix: enhance boilerplate infra & update docs (#552)

- tweak getting started docs
- update infra sample code to apply cognito authrole permissions to call deployed sample API

Author: agdimech

CONTRIBUTING.md

@@ -54,7 +54,7 @@ export class MyPackageProject extends PDKProject {
       authorAddress: "<your email>",
       defaultReleaseBranch: "mainline",
       name: "your-package",
-      repositoryUrl: "https://github.com/aws/aws-prototyping-sdk",
+      repositoryUrl: "https://github.com/aws/aws-pdk",
       devDeps: ["projen"],
       deps: [
         "projen",
@@ -215,11 +215,11 @@ From the root directory run: `npx projen upgrade-deps`. This will bump all depen
 If you run into an issue that resembles:
 
 ```bash
-Type 'import(".../aws-pdk/node_modules/aws-prototyping-sdk/node_modules/projen/lib/ignore-file").IgnoreFile' is not assignable to type 'import(".../aws-pdk/node_modules/projen/lib/ignore-file").IgnoreFile'.
+Type 'import(".../@aws/pdk/node_modules/aws-prototyping-sdk/node_modules/projen/lib/ignore-file").IgnoreFile' is not assignable to type 'import(".../@aws/pdk/node_modules/projen/lib/ignore-file").IgnoreFile'.
 Types have separate declarations of a private property '_patterns'.
 ```
 
-This means there are two conflicting versions of a package in the monorepo. To resolve this, from the root directory run: `npx projen upgrade-deps`. This will bump all dependencies to be the same/latest versions and update the `yarn.lock` file accordingly.
+This means there are two conflicting versions of a package in the monorepo. To resolve this, from the root directory run: `pdk upgrade-deps`. This will bump all dependencies to be the same/latest versions and update the lock file accordingly.
 
 ### Build hangs due to NPX waiting for user input
 

NOTICE

@@ -1,2 +1,2 @@
-aws-prototyping-sdk
+aws-pdk
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

README.md

@@ -1,100 +1,6 @@
-# aws-prototyping-sdk
+# aws-pdk
 
-## Introduction
-
-The AWS Prototyping SDK (PDK) aims to accelerate the development of prototypes on AWS. To achieve this, it provides building blocks for common patterns together with development tools to manage and build your projects. The constructs are based on [AWS CDK](https://github.com/aws/aws-cdk) and implement an expanding number of common application/infrastructure patterns, such as the ability to generate complete client and infrastructure code for a REST API from an OpenAPI specification. The project and build tools the PDK provide allows you manage the configuration of multiple related projects in a language-agnostic way, and to efficiently execute parallel incremental builds.
-
-This combination of project management, build execution, and CDK constructs reduce the effort involved in prototyping new ideas on AWS, and allow developers to seamlessly grow these ideas beyond the prototype phase without requiring a complete re-implementation of the original solution. In addition to the foundation of project configuration and build dependency management provided by the monorepo project, PDK also provides a number of other projen projects (some of which implement common infrastructure patterns using CDK) and stand-alone CDK constructs, which are described below. Note: PDK is currently pre-release, targeting version 1.0 for mid-2023.
-
-## Core Modules
-
-### [monorepo](./packages/monorepo/README.md)
-
-Modern applications are often implemented across multiple packages or libraries, each potentially implemented in a different language. To help manage the complexity that arises from this, PDK provides a [Projen](https://github.com/projen/projen) project called 'monorepo' to support dependency management and builds across packages. Together with the project-as-code provided by Projen, this project utilises [Nx Build](https://nx.dev/) to give developers the ability to manage a collection of different projects within a single repository. Nx Build allows for explicit and implicit dependency management between polyglot projects, and provides shared caching and parallel task execution for super fast builds across multiple languages with ease. By combining Projen and NX Build, 'monorepo' reduces the effort involved in maintaining and building related projects implemented in a mix of languages.
-
-### [static-website](./packages/static-website/README.md)
-
-This module provides a high-level CDK construct that is able to deploy your pre-packaged static website content into an S3 Bucket, fronted by Cloudfront. This module uses an Origin Access Identity to ensure your Bucket can only be accessed via Cloudfront and is configured to only allow HTTPS requests by default.
-
-### [cloudscape-react-ts-website](./packages/cloudscape-react-ts-website/README.md)
-
-This module provides a projen project that has a default directory structure and resources for an empty React website that utilises the Cloudscape design system. This can be used in tandem with the 'static-website' and 'identity' modules to deploy infrastructure to host and provide identity management to host and secure the website content.
-
-### [type-safe-api](./packages/type-safe-api/README.md)
-
-This module provides a projen project that allows you to define an API using either Smithy or OpenAPI v3, and a construct which manages deploying this API in API Gateway, given an integration (eg a lambda) for every operation. It generates type-safe CDK constructs, client, and server code to help you rapidly implement and integrate with your API.
-
-### [pipeline](./packages/pipeline/README.md)
-
-This module provides a projen project that uses a construct based on CDK's CodePipeline construct, named PDKPipeline, to deploy a CI/CD pipeline. It additionally creates a CodeCommit repository and by default is configured to build the project assuming monorepo is being used (although this can be changed). A Sonarqube Scanner can also be configured to trigger a scan whenever the synth build job completes successfully. This Scanner is non-blocking and as such is not instrumented as part of the pipeline.
-
-### [pdk-nag](./packages/pdk-nag/README.md)
-
-This module provides a helper utility that automatically configures [CDKNag]('https://github.com/cdklabs/cdk-nag') within your application, which validates that the state of constructs within a given scope comply with a given set of rules. Additionally, cdk-nag provides a rule suppression and compliance reporting system. cdk-nag validates constructs by extending [AWS CDK Aspects]('https://docs.aws.amazon.com/cdk/v2/guide/aspects.html').
-
-### [cdk-graph](./packages/cdk-graph/README.md)
-
-This module provides a core framework for supporting additional CDK based automation and tooling, such as diagramming, cost modeling, and security and compliance. Currently, it delivers the following functionality:
-
-1. Synthesizes a serialized graph (nodes and edges) from CDK source code.
-1. Provides runtime interface for interacting with the graph (in-memory database-like graph store).
-1. Provides plugin framework for additional tooling to utilize and extend the graph.
-
-### [identity](./packages/identity/README.md)
-
-This module provides a CDK derived construct that can be added to existing CDK project to deploy a configurable Identity Provider with a default Cognito User Pool. It does not depend on projen and can be utilised as an import in an existing CDK application.
-
-## Prerequisites
-
-Ensure you have the following packages installed globally:
-
-- [pnpm](https://pnpm.io/installation)
-- [node > 14](https://nodejs.org/en/download/package-manager/) (or use [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to install)
-- [Python >= 3.7](https://www.python.org/downloads/)
-- [Java >= 8](https://aws.amazon.com/fr/corretto/) and [Maven >= 3.6](https://maven.apache.org/download.cgi)
-
-```bash
-# from root directory of this package
-pnpm i
-```
-
-## Quickstart
-
-The [README for the 'monorepo'](./packages/monorepo/README.md) projen project provides an example of how to get started with PDK.
-
-## Usage of projen/nx
-
-This package is built using [projen](https://github.com/projen/projen) and [nx](https://nx.dev/getting-started/intro) as such all tasks should be invoked
-via either:
-
-- `pnpm nx run-many --target=<task> --all` - executes the `<task>` on every package, in dependency order.
-- `pnpm nx run <package_name>:<task>` - executes the `<task>` on the specified `<package_name>`.
-
-To build the full project, run `pnpm nx run-many --target=build --all`
-
-Any change to `projects/*` or `.projenrc.ts` requires a synth to be executed. To do this, run: `pnpm projen` from the root directory.
-
-## Nx workspace script alias
-
-In addition to the above `pnpm nx <command>` format to execute commands, the workspace package contains useful alias for common tasks.
-
-Executing `pnpm <task>` for common tasks will execute `pnpm nx run-many --target=<task> --output-style=stream --nx-bail`, such as `pnpm build` will execute `pnpx nx run-many --target=build --output-style=stream --nx-bail` across all packages.
-
-All nx run-many alias scripts access additional arguments, such as to only run on specific projects you can use `pnpm build --projects=proj1,proj2`.
-
-> See [Nx Run-Many options](https://nx.dev/packages/nx/documents/run-many#options) for details.
-
-## Documentation
-
-For documentation including examples and a full API reference, visit: [https://aws.github.io/aws-prototyping-sdk/](https://aws.github.io/aws-prototyping-sdk/)
-
-## Contributing
-
-See [CONTRIBUTING](CONTRIBUTING.md) for more information.
-
-## Security
-
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+https://aws.github.io/aws-pdk
 
 ## License
 

docs/content/api/index.md

@@ -1,7 +1,7 @@
 # API Reference
 
-The AWS Prototyping SDK (PDK) is organized into several packages. Each package can contain a combination of either (or both) CDK and Projen constructs.
+The AWS PDK is organized into submodules. Each submodules can contain a combination of either (or both) CDK and Projen constructs.
 
-Packages which are experimental will have an experimental banner to indicate that breaking changes are not subject to major version bumps.
+Submodules which are experimental will have an experimental banner to indicate that breaking changes are not subject to major version bumps.
 
-Language specific API docs can be navigated to by selecting your desired language and then selecting the package you wish to view.
+Language specific API docs can be navigated to by selecting your desired language and then selecting the submodule you wish to view.

docs/content/assets/images/boilerplate_source.png

@@ -1,5 +1,3 @@
 # Developer Guides
 
-Developer Guides are poignant guides for how to interact with certain features provided by the associated constructs. Developer guides are intended to be used as a 'cheat sheet' when configuring your constructs.
-
-The Developer Guides are broken down by package on the left hand navigation bar, with the package item on the left containing a broad getting started/overview of the package, with each specific developer guide linked out from here. Snippets are provided to you in each of the supported languages at your convenience.
+Provides a conceptual overview and practical examples to help you understand the features provided by the AWS PDK and how to use them in detail.

docs/content/assets/images/java/java_monorepo.png

@@ -13,7 +13,7 @@ myPackage.compileTask.reset("tsc --build --verbose");
 #### Links
 
 - [Cross stack values do not work with Source.data/jsonData [CDK github]](https://github.com/aws/aws-cdk/issues/19257)
-- [Nested stack runtime-config.json properties [PDK github]](https://github.com/aws/aws-prototyping-sdk/issues/84)
+- [Nested stack runtime-config.json properties [PDK github]](https://github.com/aws/aws-pdk/issues/84)
 
 #### TLDR;
 
@@ -79,7 +79,7 @@ myPackage.tsconfig?.addInclude("src/**/*.js");
 // myPackage.tsconfig?.addInclude("src/**/@lambda/**/*.js");
 ```
 
-#### Option #2 - with `rsync` ([example](https://github.com/aws/aws-prototyping-sdk/blob/392fb8c483a99123d4e8a8b6b95b5aa7ecb014b8/private/projects/monorepo-project.ts#L39))
+#### Option #2 - with `rsync` ([example](https://github.com/aws/aws-pdk/blob/392fb8c483a99123d4e8a8b6b95b5aa7ecb014b8/private/projects/monorepo-project.ts#L39))
 
 ```ts
 this.compileTask.exec(

docs/content/assets/images/py/py_monorepo.png

@@ -1,5 +1,7 @@
 ---
 nav:
   - index.md
-  - "Your first AWS PDK project": your_first_aws_pdk_project.md
-  - "TODO App Workshop": "todo_app_workshop.md"
+  - "Migration guide": "migration_guide.md"
+  - "Learning Series":
+    - "1. Your first AWS PDK project": your_first_aws_pdk_project.md
+    - "2. Shopping List application": "shopping_list_app.md"

docs/content/assets/images/ts/ts_monorepo.png

@@ -101,7 +101,49 @@ The AWS PDK lets you define your project structure as code in one of its support
 
 The AWS PDK has first-class support for Typescript, Python, & Java.
 
-To facilitate supporting so many languages, the AWS CDK is developed in one language (TypeScript). Language bindings are generated for the other languages through the use of a tool called [JSII](https://aws.github.io/jsii/).
+To facilitate supporting multiple languages, the AWS PDK is developed in one language (TypeScript). Language bindings are generated for the other languages through the use of a tool called [JSII](https://aws.github.io/jsii/).
+
+The distributables for each language can be used directly as follows:
+
+=== "TYPESCRIPT"
+    === "NPM"
+        ```
+        npm i @aws/pdk
+        ```
+
+    === "PNPM"
+        ```
+        pnpm i @aws/pdk
+        ```
+
+    === "YARN"
+        ```
+        yarn add @aws/pdk
+        ```
+
+=== "PYTHON"
+    === "PIP"
+        ```
+        pip install aws-pdk
+        ```
+
+    === "POETRY"
+        ```
+        poetry add aws-pdk
+        ```
+
+=== "JAVA"
+    === "MAVEN"
+    ```bash
+    <dependency>
+        <groupId>software.aws</groupId>
+        <artifactId>pdk</artifactId>
+        <version>LATEST</version>
+    </dependency>
+    ```
+
+!!!tip
+    Whilst the AWS PDK can be used directly via these package managers, we recommend bootstrapping via the `pdk new` command which negates the need to interact directly with these package managers. The package managers will still need to be installed however, refer to [prerequisites](index.md#prerequisites) for more information.
 
 ## Prerequisites
 
@@ -130,7 +172,7 @@ Other prerequisites depend on the language in which you develop AWS PDK projects
 
 Install the AWS PDK Toolkit globally using the following Node Package Manager command:
 
-`npm install -g aws-pdk`
+`npm install -g @aws/pdk`
 
 Run the following command to verify correct installation and print the version number of the AWS PDK.