# {{projectName}}

A serverless web application powered by [Runtime Web](https://runtimeweb.com/docs/getting-started).

## Getting Started

### Prerequisites

- Node.js >= 18.0.0
- AWS CLI configured with credentials
- Yarn or npm

### Installation

Install dependencies:

```bash
npm install
# or
yarn install
```

### Development

Start the local development server:

```bash
npm run dev
# or
yarn dev
```

The application will be available at `http://localhost:3000`.

### Building

Build all targets (Lambda, CDK, React):

```bash
npm run build
# or
yarn build
```

### Deployment

Deploy to AWS:

```bash
# Deploy to dev stage (default)
npm run deploy:dev

# Deploy to staging
npm run deploy:staging

# Deploy to production
npm run deploy:prod
```

### Environment Diagnostics

Check your development environment and project configuration:

```bash
npm run doctor
# or
yarn doctor
```

### Project Information

Display version and configuration information:

```bash
npm run info
# or
yarn info
```

## Project Structure

```
.
├── src/
│   ├── index.tsx               # Application entry point
│   ├── App.tsx                 # Root component
│   ├── routes.tsx              # Route configuration 
│   ├── pages/                  # Page components
│   │   ├── HomePage.tsx
│   │   ├── AboutPage.tsx
│   │   └── UsersPage.tsx
│   ├── handlers/               # Lambda handlers (with JWT auth)
│   │   └── users/
│   │       └── users.handlers.ts
│   ├── services/               # Business logic services
│   │   └── users.service.ts
│   ├── ties/                   # Service ties and DI
│   │   └── users.ties.ts 
├── public/
│   └── index.html              # HTML template
├── runtime.config.ts           # Runtime framework configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Project dependencies

```

## API Authorization

This template includes JWT authorization for API endpoints. API Gateway validates tokens **before** your Lambda runs — invalid requests are rejected at the edge with zero Lambda cost.

### Quick Setup

1. Open `src/handlers/users/users.handlers.ts`
2. Find the `jwtAuthConfig` object at the top
3. Replace placeholder values with your identity provider settings:

```typescript
const jwtAuthConfig = {
  type: 'jwt' as const,
  issuer: 'https://your-tenant.auth0.com/',      // Your IdP issuer URL
  audience: ['https://api.yourapp.com'],          // Your API identifier
};
```

### Supported Identity Providers

| Provider | Issuer URL Format |
|----------|-------------------|
| Auth0 | `https://YOUR_TENANT.auth0.com/` |
| Okta | `https://YOUR_DOMAIN.okta.com/oauth2/default` |
| Cognito | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}` |
| Keycloak | `https://YOUR_HOST/realms/YOUR_REALM` |

### Endpoint Authorization

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/api/users` | POST | Public | User registration |
| `/api/users` | GET | JWT | List users (paginated) |
| `/api/users/{id}` | GET | JWT | Get user by ID |
| `/api/users/{id}` | PUT | JWT | Update user |
| `/api/users/{id}` | DELETE | JWT | Delete user |

### Testing Protected Endpoints

```bash
# Without token → 401 Unauthorized
curl https://your-api.execute-api.us-east-1.amazonaws.com/dev/api/users

# With valid token → 200 OK
curl -H "Authorization: Bearer eyJhbG..." \
  https://your-api.execute-api.us-east-1.amazonaws.com/dev/api/users
```

### Learn More

- [HTTP API Authorization Guide](https://runtimeweb.com/docs/runtime-web/http-api-authorization)

## Configuration

Edit `runtime.config.ts` to customize:

- Project name
- Deployment stages (dev, staging, prod)
- AWS regions and profiles
- Custom domains
- Feature flags (SEO, manifest, warmup)

## Learn More

- [Runtime Web Documentation](https://runtimeweb.com/docs/getting-started)
- [AWS Lambda](https://aws.amazon.com/lambda/)
- [AWS CDK](https://aws.amazon.com/cdk/)
