engineering-handbook/sam-project-layout.md

# SAM Project Layout

## Standard Directory Structure

```
project-name/
├── template.yaml            # SAM template at root
├── samconfig.toml           # Deploy config (gitignored)
├── samconfig.toml.example   # Template for onboarding (committed)
├── src/
│   ├── function_name/
│   │   ├── app.py           # Lambda handler
│   │   └── requirements.txt # Per-function dependencies
│   └── shared/              # Shared layer code (if needed)
└── .gitignore
```

## File Purposes

### `template.yaml`

The SAM/CloudFormation template. Lives at the project root. Defines all Lambda functions, IAM roles, API Gateway endpoints, DynamoDB tables, and other resources.

### `samconfig.toml`

Contains real ARNs, S3 bucket names, and deploy parameters. **Gitignored** because it varies per environment and may contain account-specific values.

### `samconfig.toml.example`

A committed template showing the expected structure and parameter names. New contributors copy this to `samconfig.toml` and fill in their values.

### `src/function_name/`

One directory per Lambda function. Each contains its own handler (`app.py`) and dependencies (`requirements.txt`). This keeps functions independently deployable and avoids bloating one function with another's dependencies.

### `src/shared/`

Optional. Used for code shared across multiple functions, typically deployed as a Lambda layer.

## Standard .gitignore

```
.aws-sam/
__pycache__/
*.pyc
.env
samconfig.toml
```