# {{name}} — Setup Guide

## Prerequisites

- [Node.js](https://nodejs.org/) v{{node_version}}+ (required for CDK)
- [AWS CLI](https://aws.amazon.com/cli/) configured with appropriate credentials
- [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) (`npm install -g aws-cdk`)
{{#if backend_runtime_go}}
- [Go](https://golang.org/) v{{go_version}}+
{{/if}}
{{#if backend_runtime_python}}
- [Python](https://python.org/) v{{python_version}}+
{{/if}}
{{#if auth}}
- AWS Cognito User Pool (created via `cdk deploy` or manually — see [Auth Setup](#auth-setup))
{{/if}}
{{#if billing}}
- [Stripe](https://stripe.com) account and API keys (see [Billing Setup](#billing-setup))
{{/if}}

## Local Development

{{#if has_frontend}}
### Frontend

```bash
{{#if is_fullstack}}
cd apps/web
{{/if}}
npm install
npm run {{frontend_dev_script}}
```

{{/if}}
{{#if has_backend}}
### Backend

{{#if backend_runtime_go}}
```bash
{{#if is_fullstack}}
cd apps/api
{{/if}}
go mod tidy
make dev
```
{{/if}}
{{#if backend_runtime_node}}
```bash
{{#if is_fullstack}}
cd apps/api
{{/if}}
npm install
make dev
```
{{/if}}
{{#if backend_runtime_python}}
```bash
{{#if is_fullstack}}
cd apps/api
{{/if}}
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
make dev
```
{{/if}}

### Environment variables

```bash
{{#if is_fullstack}}
cp apps/api/.env.example apps/api/.env
{{else}}
cp .env.example .env
{{/if}}
```

Edit the `.env` file and fill in the required values.

{{/if}}
{{#if is_fullstack}}
### Run everything

From the project root:

```bash
make dev       # starts frontend and backend concurrently
make dev-web   # frontend only
make dev-api   # backend only
```

{{/if}}
## CDK Infrastructure

### Bootstrap (first time only per AWS account/region)

```bash
cd cdk
npm install
npx cdk bootstrap
```

### Preview changes

```bash
cd cdk && npx cdk synth
```

### Deploy

```bash
cd cdk && npx cdk deploy --all
```

{{#if auth}}
## Auth Setup

This project uses AWS Cognito for authentication. The CDK stack provisions a User Pool automatically on first deploy.

After deploying, add the following to your environment:
{{#if has_frontend}}

**Frontend** (`.env`{{#if is_fullstack}} inside `apps/web/`{{/if}}):
```
VITE_COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
VITE_COGNITO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX
VITE_COGNITO_DOMAIN=https://your-domain.auth.us-east-1.amazoncognito.com
```
{{/if}}
{{#if has_backend}}

**Backend** (`.env`{{#if is_fullstack}} inside `apps/api/`{{/if}}):
```
COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
COGNITO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX
AWS_REGION=us-east-1
```
{{/if}}

{{/if}}
{{#if billing}}
## Billing Setup

This project uses Stripe for payments.

1. Obtain your API keys from the [Stripe Dashboard](https://dashboard.stripe.com/apikeys).
2. Add the following to your environment:
{{#if has_frontend}}

**Frontend** (`.env`{{#if is_fullstack}} inside `apps/web/`{{/if}}):
```
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXX
```
{{/if}}
{{#if has_backend}}

**Backend** (`.env`{{#if is_fullstack}} inside `apps/api/`{{/if}}):
```
STRIPE_SECRET_KEY=sk_test_XXXXXXXXXX
STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXX
```
{{/if}}

3. For local webhook testing, use the [Stripe CLI](https://stripe.com/docs/stripe-cli):

```bash
stripe listen --forward-to localhost:8080/webhooks/stripe
```

{{/if}}
## CI/CD

Two GitHub Actions workflows are included under `.github/workflows/`:

| Workflow | Trigger | What it does |
|----------|---------|--------------|
| `ci.yml` | Pull request → `main` | Lint, build, test, CDK synth |
| `deploy.yml` | Push → `main` | Build artifacts, CDK deploy |

### Required GitHub secrets and variables

| Name | Type | Description |
|------|------|-------------|
| `AWS_DEPLOY_ROLE_ARN` | Secret | IAM role ARN for OIDC-based deployment |
| `AWS_REGION` | Variable | Target AWS region (e.g. `us-east-1`) |

Configure these under **Settings → Secrets and variables → Actions** in your repository.

The deploy workflow uses OpenID Connect (OIDC) — no long-lived AWS credentials are stored in GitHub.
