jaws-framework/docs/project_structure.md

JAWS is the serverless framework powered by Amazon Web Services.

# JAWS: Project Structure

All JAWS apps use the directory structure described in the diagram below.  This scaffolding can be generated by running the `jaws project create` command.

![jaws framework structural diagram](../img/jaws_files_diagram.png)

## jaws.json

See project `jaws.json` [example here](../examples/project-jaws.json)

The `jaws.json` file contains project configuration and authorship details.

### Common jaws.json attributes

The following attributes should exist in either a project or lambda `jaws.json` at the top level

* **name**: project/module or lambda action name
* **version**: project/module or lambda [Semantic Versioning](http://semver.org/) number.
* **location**: project/module or lambda scm url (if exists)
* **author**: `John Serverless <john@gmail.com> http://www.john.com`
* **description**: project/module or lambda desc.
* **stages**: map of all your stages, and regions those stages are in as well as IAM roles

## admin.env

This file tells the JAWS tooling what profile from the
[shared credentials](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Credentials_from_the_Shared_Credentials_File_____aws_credentials_)
file (`~/.aws/credentials`) is loaded when doing administrative tasks that interact with AWS.

Here is an example

```
ADMIN_AWS_PROFILE=default
```

## lambdas-cf.json

This is the JAWS lambda [CloudFormation](https://aws.amazon.com/cloudformation/) file.

It contains your lambda function topology and facilitates the deployent and mangement of your lambda functions for a given stage and region.

You can see a [`lambdas-cf.json` example here](../lib/templates/lambdas-cf.json)

## resources-cf.json

This is the JAWS [CloudFormation](https://aws.amazon.com/cloudformation/) resources file.  It contains things like the IAM roles for JAWS lambda functions and API Gateway endpoints.

[AWSM: Amazon Web Services Modules](https://github.com/awsm-org/awsm) can merge data into this file by implementing the
[`resources`,`LambdaIamPolicyDocumentStatements`,and `ApiGatewayIamPolicyDocumentStatements`](https://github.com/awsm-org/awsm/blob/master/README.md#configuration) attribute in the `awsm.json`.

The following CloudFormation Parameters are standardized JAWS project variables that all aws-module CloudFormation
templates should utilize via `Ref`.  Note: `aa` is used so they show up at top of CloudFormation web UI:

* `aaHostedZone`
* `aaStage`
* `aaProjectName`
* `aaDataModelStage` [what's this?](./best_practices.md#cloud-formation-segmentation)
* `aaNotficationEmail`
* `aaDefaultDynamoRWThroughput`

The following are CloudFormation Resource names that aws-module creators can `Ref` in their CF Templates:

* `IamRoleLambda`
* `IamRoleApiGateway`