From e7e85ec4c8bec77365f4d57e0708065af7e5697f Mon Sep 17 00:00:00 2001 From: Austen Collins Date: Sun, 20 Sep 2015 19:38:30 -0700 Subject: [PATCH] readme: update --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index e3a02d549..82eb34d57 100755 --- a/README.md +++ b/README.md @@ -82,6 +82,43 @@ This will create a new jaws project, create a lambda function and endpoint (and `jaws dash`. After deployment is complete, you will be given a url. In the above example, you can access your deployed lambda at `your_url/users/list`. +## Overview: + +JAWS is mostly a CLI that provides structure, automation and optimization to help you build and maintain your serverless apps. JAWS uses AWS services exclusively, since it relies on AWS's Lambda service to provide event-driven compute resources, and lots of AWS services integrate nicely with Lambda. + +In JAWS V1, we made a strong effort to not only make a groundbreaking serverless framework, but to build the best framework for building applications with AWS in general (that is also serverless!). As a result, JAWS V1 incorporates years of expertise in AWS, giving you best practices out-of-the-box. + +A JAWS app can be simply a group of lambda functions to accomplish some tasks, or an entire back-end comprised of hundreds of lambda functions. All JAWS apps use the directory structure described in the diagram below. This scaffolding can be generated by running the `jaws new project` command. + +![jaws framework structural diagram](img/jaws_files_diagram.png) + +Web, mobile and IoT applications can be built on JAWS, primarily since JAWS is mostly a back-end focused framework. JAWS comes with a `front` folder, but only for your convenience. In the future, JAWS will provide more automation for front-end development. + +As you may see in the diagram, JAWS relies heavily on AWS Cloudformation to keep track of all of the AWS resources your application requires in each stage/region. This way, you can easily provision/replicate your AWS resources at once, and roll back to previous deployments, for every stage/region your application uses. + +JAWS applications' back-end runs on AWS Lambda functions which can be seen in the `back` folder. To encourage the development of re-usable, standardized and optimized lambda functions, JAWS keeps all of your app's lambda functions in the **AWS-Module** format. This format was created exclusively for JAWS, and the JAWS CLI features a lot of commands to help you generate scaffolding for your aws_modules. + +Possibly the best feature of aws_modules is that they help developers publish and share their lambda functions and encourage a module ecosystem. Hopefully, in the future, you will be able to select from a large variety of pre-written lambda functions, designed by the JAWS community for re-use, optimization, easy installation and deployment! + + + + + + + + + + + + +The purpose of the jaws cli is to make the serveress workflow easy. This involves automation to help manage CloudFormation, multiple regions and stages, deployment of Lambda functions, AWS API Gateway endpoints. + + + +![anatomy of a jaws deployment on aws](img/jaws_deployment_diagram.png) + + + ## Where do I go from here? We're currently working on our [docs](./docs/), [wiki](https://github.com/jaws-framework/JAWS/wiki), [best practices](https://github.com/jaws-framework/JAWS/wiki/Best-practices) and [FAQ](https://github.com/jaws-framework/JAWS/wiki/FAQ) pages.