documentation: Updated README, USER_GUIDE

refactor: cleaned package.json files up. Resolved lint findings

Improved linting and documentation too

re: #46
re: #45

Author: flamingquaks

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+## Code of Conduct
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+[email protected] with any additional questions or comments.

CONTRIBUTING.md

@@ -1,4 +1,59 @@
-# Contributing
+# Contributing Guidelines
 
-There are no contribution guidelines yet as this is still under initial development.
-If you'd like to get involved, contact [email protected]
+Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
+documentation, we greatly value feedback and contributions from our community.
+
+Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
+information to effectively respond to your bug report or contribution.
+
+
+## Reporting Bugs/Feature Requests
+
+We welcome you to use the GitHub issue tracker to report bugs or suggest features.
+
+When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
+reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+
+* A reproducible test case or series of steps
+* The version of our code being used
+* Any modifications you've made relevant to the bug
+* Anything unusual about your environment or deployment
+
+
+## Contributing via Pull Requests
+Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
+
+1. You are working against the latest source on the *main* branch.
+2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
+3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
+
+To send us a pull request, please:
+
+1. Fork the repository.
+2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
+3. Ensure local tests pass.
+4. Commit to your fork using clear commit messages.
+5. Send us a pull request, answering any default questions in the pull request interface.
+6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+
+GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
+[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+
+## Finding contributions to work on
+Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
+
+
+## Code of Conduct
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+[email protected] with any additional questions or comments.
+
+
+## Security issue notifications
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
+
+
+## Licensing
+
+See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.

README.md

@@ -1,33 +1,98 @@
-# Generative AI Powered Newsletters
+# Generative AI Newsletter Application
 
-This goal of this project is to create a sample application that showcases AWS Serverless and GenAI technology to subscribe to news feeds and publications, accurately summarize the data and generate visually appealing newsletters for end-user consumption.
+The Generative AI Newsletter Application sample is a ready-to-use serverless solution designed to allow users to create rich newsletters automatically with content summaries that are AI-generated. 
 
-The project is currently in the initial design phase with a PRFAQ in the works.
+The application offers users the ability to influence the generative AI prompts to customize how content is summarized such as the tone, intended audience, and more. Users can stylize the HTML newsletter, define how frequently newsletters are created and share the newsletters with others. 
 
-This document will be filled out more as the project evolves.
+## Deploying the Solution
 
-### Some High-Level Thoughts for the Project
+The solution is developed using AWS Cloud Development Kit (CDK), TypeScript, & NodeJS
 
-- Leverage serverless technology as much as possible, avoid provisioned resources like SageMaker endpoints, to reduce cost of running the sample
-- Leverage Bedrock for LLM for summarization, text embedding, etc.
-- Aim to provide methods to reduce hallucination and enable the user to validate information. This can be, for example, including links to sources
-- Develop a Front-End UI that leverages [Cloudscape](https://cloudscape.design) React framework
-- Aim to leverage newer technology that may not have samples, such as Bedrock Agents
-- Enable Newsletter subscriptions (users could get an emailed newsletter, a text with a link to a newsletter, a slack notification, etc)
+### Prerequisites
+* You will need an [AWS Account](https://repost.aws/knowledge-center/create-and-activate-aws-account).
 
-## Deploying the Solution
+* Either an [IAM User](https://console.aws.amazon.com/iamv2/home?#/users/create) or [IAM Identity Center User](https://aws.amazon.com/iam/identity-center/) with `AdministratorAccess` policy granted to your user. *Not recommended for a production environment.*
+* [AWS CLI](https://aws.amazon.com/cli/) installed and configured to use with your AWS account.
+* [NodeJS 16 or 18](https://nodejs.org/en/download/) installed
+* The `ARN` of your [verified email identity](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-manage-verify.html) that you will send newsletter emails from. You will also be asked to provide an email address that will be the sender, which must be associated with the verified email identity.
+
+
+### Deployment
+
+1. Clone the repository
+	```
+	git clone https://gitlab.aws.dev/awsrudy/genai-newsletter/
+	```
+1. Change directory into the cloned repository
+	```
+	cd genai-newsletter
+	```
+1. Install the project dependencies & build the project
+	```
+	npm install && npm run build
+	```
+1. Run the configuration wizard to create a deployment configuration file.
+	```
+	npm run config manage
+	```
+	The configuration wizard will generate a configuration file in `bin/config.json`. This file will be used during the deployment. Unless you need to change the configuration file, you do not need to run the configuration wizard for future deployments. If you change the **Stack Name**, it will cause a new deployment to occur. 
+
+1. [*Optional*] Bootstrap AWS CDK on the target AWS Account & Region. 
+	> Note: This is required if you have never used AWS CDK on this account and region combination. ([More information on CDK bootstrapping](https://docs.aws.amazon.com/cdk/latest/guide/cli.html#cli-bootstrap)).
+
+1. Deploy the solution
+	```
+	npx cdk deploy
+	```
+	You can view the progress of your CDK deployment in the [CloudFormation console](https://console.aws.amazon.com/cloudformation/home) in the selected region.
+
+1. Once the deployment is complete, CDK should show outputs that resemble the following. (Note: terms in brackets represents a generated/dynamic value)
+	```
+	...
+	Outputs:
+	[stackName].AppLink = https://dxxxxxxxxxxxxx.cloudfront.net/
+	[stackName].UserPoolLink = https://[region].console.aws.amazon.com/cognito/v2/idp/user-pools/xxxxx_XXXXX/users?region=[region]
+	...
+	```	
+	If you need these outputs again, you can view the deployment in the [CloudFormation console](https://console.aws.amazon.com/cloudformation/home) by navigating to the deployed stack and visiting the "Outputs" tab.
+
+### Creating Users
+
+User accounts for the application are managed using [Amazon Cognito](https://aws.amazon.com/cognito/).
+
+1. Navigate to the Amazon Cognito in the AWS Console and select the User Pool deployed with the solution. Alternatively, you can navigate directly to the user pool by navigating to the `UserPoolLink` provided in the CDK output/CloudFormation output. 
+1. In the **Users** box, click the **Create user** button.
+1. Complete the user information form. 
+	It is recommended to select "Send an email invitation".
+	The Email address is required. 
+1. Once the form is complete, click the **Create user** button.
+
+### First Time Login
+
+1. Navigate to the `AppLink` URL provided in the CDK or CloudFormation output. This is the main URL for the application. 
+1. Login with the email and temporary password.
+1. If login is successful, you will be asked to provide your name and update your password.
+1. After you complete the name and password update, you will be logged into the application and can get started.
+
+
+### User Guide
+To learn how to start ingesting data with Data Feeds and creating dynamic Newsletters, visit the [User Guide](./USER_GUIDE.md).
+
+## Author
+
+* [Addie Rudy](https://www.linkedin.com/in/addierudy/)
 
-The following steps will guide you through deploying the CDK Application to your environment.
+## Threat Model
 
-1. In your project root folder, install package dependencies: `npm install --save-dev`
-2. After all packages are installed, you will need to build the solution by running `npm run build`. This will trigger amplify codegen to create the API files from the `schema.graphql` file. If generated files exist, they will simply be regenerated. Once the generation is complete, `tsc` will compile the typescript project.
-3. Run the configuration CLI to setup the necessary CDK context file. To run the configuration creation CLI, run `npm run config create`. This will will you through setting up your configuration. If a config exists, you can optionally update values. If you'd like to view the existing config, you can run `npm run config show`
-4. Deploy the stack to AWS. `npm run deploy`
+Review the threat model developed for the solution [here](documentation/ThreatModel.md). Additionally, you can download the [Threat Model JSON](documentation/GenAINewsletter_ThreatComposer.json) and view the visualized threat model by importing the JSON into [Threat Composer](https://awslabs.github.io/threat-composer/workspaces/default/dashboard).
 
-### Project Leads
+## License
 
-This project is currently lead by Addie Rudy ([awsrudy@](https://phonetool.amazon.com/users/awsrudy)) and Pete Conrad ([peteconr@](https://phonetool.amazon.com/users/peteconr))
+This library is licensed under the MIT-0 License. See the LICENSE file. 
 
-### Additional Documentation
+## Additional Resources
 
-To find additional documentation, please visit the `documentation/` directory from the root of the repo.
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE)
+- [Code of Content](CODE_OF_CONDUCT.md)
+- [Contributing](CONTRIBUTING.md)

USER_GUIDE.md

@@ -0,0 +1,87 @@
+# **AWS Serverless Feed Summarizer and Newsletter Solution**
+
+## Table of Contents
+
+- [User Guide](#user-guide)
+  - [Setting up Data Feeds](#setting-up-data-feeds)
+  - [Subscribing to Newsletters](#subscribing-to-newsletters)
+  - [Flagging Bad Data](#flagging-bad-data)
+  - [Deleting Data](#deleting-data)
+
+## User Guide
+
+### Setting up Data Feeds
+Data Feeds automate ingesting data and summarizing the content for use within Newsletters. All Newsletters will require at least one Data Feed. Currently, only RSS & ATOM feeds are supported Data Feed types. 
+
+To create your data feed:
+
+1. Click **Create Data Feed** from the side panel menu.
+
+1. Complete the details of the data feed form including a title, optional description, URL of the ATOM or RSS feed.
+
+1. The **Summarization Prompt** instructs the Data Feed ingestion process on how to summarize the articles it consumes. Because this makes Data Feed summaries unique, you can create multiple Data Feeds for the same source and prompt each one to summarize differently. 
+![Data Feed Create](./documentation/DataFeed-Create-Image.png)
+
+1. Click **Add** to create the Data Feed. 
+You will be navigated to the Data Feed Details page. 
+
+Once a Data Feed is created, the first run of ingestion will begin. Generally within 5 minutes, all articles currently on the RSS feed will have been ingested and summarized. You can revist the Data Feed page or simply refresh the page if you haven't navigated away. 
+
+### Creating Newsletters
+
+1. To create a newsletter, go to the Newsletters Dashboard and click **Create Newsletter**.
+1. In the Newsletter Wizard, completed the newsletter details and click **Next** to proceed. 
+![Newsletter Create Wizard](./documentation/Newsletter-Create-Image.png)
+1. Add one or more data feeds to your newsletter. If you don't have any data feeds, you will need to create at least one first. See [Setting up Data Feeds](#setting-up-data-feeds).
+![Newsletter Create Wizard](./documentation/Newsletter-Create-AddDataFeeds-Image.png)
+1. *Optionally* add a Newsletter Introduction Prompt. This prompt will be used to influence how the each Newsletter publication's introduction will be written. 
+![Newsletter Create Wizard - Prompt](./documentation/Newsletter-Create-Prompt-Image.png)
+1. *Optionally* customize the style of the newsletter to have a unique look and feel. Click the **Show Preview** button to live preview a sample newsletter with your custom style.
+![Newsletter Create Wizard - Style](./documentation/Newsletter-Create-Style-Image.png)
+1. Finally, review the newsletter settings to confirm everything is correct. Then click the **Create Newsletter** button to create your newsletter. 
+![Newsletter Create Wizard - Style](./documentation/Newsletter-Create-Review-Image.png)
+1. Once the newsletter is successfully created, you will be taken to the Newsletter detail page. By default **you are not subscribed** to the newly created Newsletter. 
+![Newsletter Details](./documentation/Newsletter-Details-Image.png)
+
+
+### Subscribing to Newsletters
+
+Subscribing to a newsletter allows you to receive the newsletter automatically in your email on the set schedule. Newsletters, by default, have no subscribes, including the newsletter owner. If a Newsletter has no subscribes, the Newsletter will still be generated and viewable in the application, but won't be emailed out. 
+
+To subscribe to a Newsletter:
+
+1. Go to the Newsletter Dashboard. The Dashbaord shows newsletters that you have access to, including your private and non-private newsletters, and newsletters created by others that are non-private. 
+1. *Optionally,* you can use the *Filter Newsletters* search box to filter the table results. 
+1. Click the Newsletter Name of the Newsletter you'd like to view or subscribe to.
+1. Below the Newsletter details, the number of subscribes and your current suibscription status will be shown. If you are not subscribed, you can click the **Subscribe** button. If you are already subscribed, the button will show **Unsubscribe**.
+
+*All emails include a footer unique to the recipient that allows them to unsubscribe from the newsletter without having to login to the application*
+
+### Viewing My Subscriptions
+To view Newsletters that you are currently subscribed to, simply click **My Newsletter Subscriptions** from the side panel. This will show you all Newsletters that you are currently subscribed to. 
+> *Note: If a Newsletter owner decides to make their Newsletter private, it will no longer be visible to you. In this case, you will see a notice on the **My Subscriptions Page** indicating how many Newsletters are no longer visible.* 
+
+From the page, click on the desired Newsletter to view the details and past publications.
+
+### Unsubscribing From a Newsletter
+To unsubscribe from a Newsletter, simply navigate to the Newsletter in the application and click the **Unsubscribe** button.
+
+Alternatively, users can unsubscribe from any Newsletter using the **Unsubscribe from this newsletter** link in the footer of all Newsletter emails. This is a unique-to-the-user link.
+
+> *Note: In the event that a newsletter is no longer visible, but you are still subscribed, the unsubscribe link in the email is the only way to unsubscribe. If you unsubscribe from a Newsletter you no can view, you will not be able to resubscribe to the Newsletter unless the owner updates the privacy.*
+
+### Flagging Bad Data
+Occassionally, a summary may not be generated in a way that is deemed accurate. To create transparency that data has been deemed inaccurate, users can opt to flag a summary. Below are the ways to flag data.
+
+- Data Feed Article Summary
+  - From the Data Feed Details page, click the flag on the row of the article summary that is incorrect
+  - From the Newsletter Details page, when looking at generated Newsletter, if the "Flag this summary" link is available under an article, you can click the link to flag the article summary.This is a deep-link directly to the Data Feed detail page that will mark the article summary as flagged.
+  - From the Newsletter email a user receives. Below the summary, users can select "Flag this summary". This is a deep-link directly to the Data Feed detail page that will mark the article summary as flagged.
+
+- Newsletter Intro Summary
+  - Flagging not yet available
+
+
+### Deleting Data
+Deleting newsletters, feeds, articles, summaries, etc. does not natively exist in the solution at this point. If you require data to be removal, please contact us for support. 
+