# Command & Configuration Reference

Complete reference for all commands, scripts, and configuration options.

## Makefile Commands

### LocalStack Management

| Command | Description |
|---------|-------------|
| `make start` | Start LocalStack container |
| `make stop` | Stop LocalStack container |
| `make logs` | View LocalStack container logs (follows) |
| `make status` | Check if LocalStack services are ready |
| `make verify` | Show all deployed resources (S3, Lambda, Step Functions, SQS, SNS) |
| `make clean` | Stop LocalStack and remove all data, state, and volumes |

### Terraform Operations

| Command | Description |
|---------|-------------|
| `make tf-init` | Initialize Terraform (creates provider override symlink) |
| `make tf-plan` | Plan Terraform changes (shows what will change) |
| `make tf-apply` | Apply Terraform configuration (deploy resources) |
| `make tf-destroy` | Destroy all Terraform resources for current PROJECT |
| `make tf-output` | Show Terraform outputs for current PROJECT |
| `make tf-clean` | Remove Terraform state and cache for current PROJECT |

### Combined Workflows

| Command | Description |
|---------|-------------|
| `make deploy-all` | Start LocalStack + deploy all projects in dependency order |
| `make up` | Start LocalStack + deploy current PROJECT |

### Utilities

| Command | Description |
|---------|-------------|
| `make check` | Check prerequisites (Docker, Terraform, AWS CLI) |
| `make projects` | List available Terraform projects |
| `make help` | Show all available commands with descriptions |

### Using PROJECT Variable

```bash
make tf-apply PROJECT=<name>   # Specific project
make tf-apply                   # Use default from .env
make projects                   # List all projects
```

## Scripts Reference

### `scripts/check-prerequisites.sh`

Checks: Docker, Terraform, AWS CLI, .env file, projects

```bash
make check
```

### `scripts/awslocal.sh`

AWS CLI wrapper (auto-adds `--endpoint-url=http://localhost:4566`)

```bash
./scripts/awslocal.sh s3 ls
./scripts/awslocal.sh lambda list-functions
./scripts/awslocal.sh stepfunctions list-state-machines
```

### `scripts/deploy-all.sh`

Deploys all projects in dependency order. Edit to customize order.

```bash
make deploy-all
```

### `scripts/deploy-project.sh`

Deploy single project with validation.

```bash
./scripts/deploy-project.sh <project-name>
```

### `scripts/clean.sh`

Interactive cleanup with confirmation. Preserves Terraform configs.

```bash
./scripts/clean.sh
```

## Environment Variables

### Using Environment Variables

Simplify ARNs with `${AWS_DEFAULT_REGION}` and `${AWS_ACCOUNT_ID}`:

```bash
arn:aws:states:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT_ID}:stateMachine:my-machine
```

## Terraform Configuration

### Provider Override

Located at: `terraform/_shared/provider_override.tf`

Automatically symlinked to each project as `_override.tf` by `make tf-init`.

**Key configurations:**
- LocalStack endpoints (localhost:4566)
- Test credentials (access_key/secret_key = "test")
- Local backend (terraform.tfstate files)
- S3 path-style addressing
- Skip AWS validation checks

## Resource Naming Convention

All resources use `local-` prefix:

| Resource Type | Naming Pattern | Example |
|--------------|----------------|---------|
| S3 Buckets | `local-{name}` | `local-abacus-flowthrough` |
| Lambda Functions | `local-{name}` | `local-lambda-av-scan-containerized` |
| Step Functions | `local-{name}` | `local-file-upload-workflow` |
| SNS Topics | `local-{name}` | `local-abacus-file-upload-events` |

This makes it clear resources are for local development.

## Useful Commands

### Check What's Deployed

```bash
# Quick overview
make verify

# Specific resources
./scripts/awslocal.sh s3 ls
./scripts/awslocal.sh lambda list-functions --query 'Functions[*].[FunctionName,Runtime]' --output table
./scripts/awslocal.sh stepfunctions list-state-machines --query 'stateMachines[*].name' --output text
```

### Debug Terraform

```bash
# See what Terraform will do
make tf-plan PROJECT=<your-project>

# Enable Terraform debug logging
TF_LOG=DEBUG make tf-apply

# Check Terraform state
cd terraform/<your-project>
terraform state list
terraform state show <resource>
```

### Monitor LocalStack

```bash
# Follow logs in real-time
make logs

# Check container status
docker ps

# Check container resources
docker stats localstack

# Execute commands in container
docker exec -it localstack bash
```

## External Resources

- [LocalStack Documentation](https://docs.localstack.cloud/)
- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
- [AWS CLI with LocalStack](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
- [LocalStack GitHub](https://github.com/localstack/localstack)