# Getting Started

This guide will walk you through setting up the UF r/place project on your local machine and deploying it to AWS.

## Prerequisites

Before you begin, make sure you have:

### Required Software
- **Node.js 18 or higher** - [Download from nodejs.org](https://nodejs.org/)
- **npm** (comes with Node.js)
- **Git** - [Download from git-scm.com](https://git-scm.com/)
- **AWS CLI** - [Installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- **AWS Account** - [Create one at aws.amazon.com](https://aws.amazon.com/)

### Verify Prerequisites

```bash
# Check Node.js version (should be 18+)
node --version

# Check npm version
npm --version

# Check Git
git --version

# Check AWS CLI
aws --version
```

## Quick Start

### 1. Clone the Repository

```bash
git clone https://github.com/ufosc/UF_r-place.git
cd UF_r-place
```

### 2. Install Dependencies

```bash
# Install all dependencies for both workspaces
npm install
```

This will install dependencies for:
- Root workspace (build scripts)
- `infra/` workspace (CDK and infrastructure dependencies)
- `web/` workspace (Next.js and frontend dependencies)

### 3. Configure AWS Credentials

You need AWS credentials to deploy the infrastructure.

If you need to create an AWS account, set up IAM users, or understand AWS permissions, follow the comprehensive [AWS Configuration Guide](AWS-Configuration.md) which covers:
- Creating an AWS account
- Setting up IAM users and permissions  
- Creating access keys
- Security best practices
- Troubleshooting common issues

### 4. Set CDK Environment Variables

The CDK deployment requires some environment variables. Put these in a copy of `infra/.env.example`, calling it `infra/.env`.

```bash
# Replace with your 12-digit AWS account ID
CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1
```

### 5. Bootstrap CDK (First Time Only)

This is a one-time setup per AWS account and region:

```bash
npm run cdk:bootstrap
```

If you see an error about unable to resolve AWS account, make sure you've completed step 4 above.

### 6. Deploy the Backend Infrastructure

```bash
npm run cdk:deploy
```

This will:
- Build the TypeScript infrastructure code
- Create AWS resources (Lambda function, API Gateway)
- Deploy your stack to AWS
- Output the API URL when complete

**Important**: Save the `ApiUrl` output from this command - you'll need it in the next step.

### 7. Configure Frontend Environment

Create the environment file for the frontend by copying the example file and updating it:

```bash
# Copy the example environment file
cp web/.env.example web/.env.local
```

Then edit `web/.env.local` and replace the placeholder with your actual API URL from step 6:

```bash
# web/.env.local
NEXT_PUBLIC_API_URL=https://abc123def4.execute-api.us-east-1.amazonaws.com/prod/
```

**Important**: Make sure the URL ends with a trailing slash `/`

### 8. Run the Frontend Locally

```bash
npm run dev
```

This starts the Next.js development server at http://localhost:3000

### 9. Test the Application

1. Open your browser to http://localhost:3000
2. You should see "UF r/place" as the heading
3. Below it should display "API says: Hello from UF r/place API!"

If you see an error message instead, check:
- The API URL in `web/.env.local` is correct and ends with `/`
- The backend deployment completed successfully
- Your AWS credentials are still valid

## Development Workflow

### Making Changes to the Backend

1. **Modify Lambda functions** in `infra/lambda/`
2. **Update infrastructure** in `infra/lib/`
3. **Deploy changes**:
   ```bash
   npm run cdk:deploy
   ```

### Making Changes to the Frontend

1. **Modify components** in `web/app/`
2. **Changes are automatically hot-reloaded** when running `npm run dev`
3. **For production builds**:
   ```bash
   npm run build
   ```

### Available Scripts

From the root directory:

```bash
# Development
npm run dev          # Start frontend dev server
npm run build        # Build both frontend and backend
npm run lint         # Run linting

# Deployment
npm run deploy       # Deploy backend infrastructure
npm run cdk:deploy   # Same as above
npm run cdk:bootstrap # Bootstrap CDK (one-time setup)
```

From individual workspaces:

```bash
# Backend (from infra/ directory)
npm run build        # Compile TypeScript
npm run synth        # Generate CloudFormation templates
npm run deploy       # Deploy to AWS
npm run destroy      # Remove all AWS resources

# Frontend (from web/ directory)
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
```

## Project Structure Overview

```
UF_r-place/
├── package.json              # Root workspace & scripts
├── infra/                   # AWS Infrastructure
│   ├── bin/app.ts          # CDK app entry point
│   ├── lib/                # Infrastructure definitions
│   ├── lambda/             # Lambda function code
│   └── cdk.out/           # Generated CloudFormation (git-ignored)
└── web/                    # Next.js Frontend
    ├── app/               # App Router pages & components
    ├── .env.local        # Environment variables (git-ignored)
    └── .next/            # Next.js build output (git-ignored)
```

## Troubleshooting

### "Unable to resolve AWS account to use"

This means CDK couldn't determine your AWS account/region. Make sure you've:
1. Set up AWS credentials (step 3)
2. Exported CDK_ACCOUNT and CDK_REGION (step 4)
3. Run `aws sts get-caller-identity` to verify your credentials work

### API URL not working

- Ensure the URL in `web/.env.local` ends with `/`
- Check that the backend deployment completed successfully
- Verify the API Gateway was created in the AWS console

### "Error: NEXT_PUBLIC_API_URL not set"

You need to create `web/.env.local` with the API URL from step 7.

### CDK Bootstrap fails

Make sure you have the necessary permissions in your AWS account. You need permissions to create IAM roles, S3 buckets, and other resources.

## Next Steps

Once you have the basic setup working:

1. **Start contributing** - Read the [Contributing Guide](Contributing.md) for development workflow
2. **Explore the code** - Check out the [Project Overview](Project-Overview.md) for architecture details
3. **Set up additional AWS resources** - Follow the [AWS Configuration Guide](AWS-Configuration.md)
4. **Deploy to production** - Consider setting up CI/CD pipelines

## Getting Help

- Check the [Contributing Guide](Contributing.md) for development workflow and collaboration
- Review the [AWS Configuration Guide](AWS-Configuration.md) for detailed AWS setup
- Look at the existing code in `infra/` and `web/` directories
- Check AWS CloudWatch logs for Lambda function errors
- Use `npm run synth` to see generated CloudFormation templates