Bloom Refresh is an event-driven web application designed to connect volunteers and organizers for local cleanup events. It simplifies event coordination, facilitates community participation, and quantifies environmental impact.

• Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS v4, Radix UI, shadcn/ui, Lucide, react-hook-form, zod
• Backend (AWS): CDK v2 (TypeScript), API Gateway (REST), Lambda (Python 3.12), DynamoDB, EventBridge, SQS, SNS, Cognito, S3

• Node.js 18.18+ (recommended 20+)
• Package manager: pnpm (preferred) or npm
• AWS account + credentials configured (for backend deploy)
• AWS CDK: npm i -g aws-cdk (optional; you can run via npx)

frontend/   # Next.js app (App Router) and API route proxies
backend/    # AWS CDK app (TypeScript) + Lambda sources (Python)

cd frontend
# Using pnpm (preferred)
pnpm install
# or using npm
npm install

pnpm dev   # or: npm run dev

Open http://localhost:3000 in your browser.

pnpm build  # or: npm run build
pnpm start  # or: npm start

pnpm lint   # or: npm run lint

• BACKEND_API_BASE_URL (optional): When set, the Next.js API routes proxy to the deployed AWS backend instead of the local mock DB.
  • Example: https://{restApiId}.execute-api.{region}.amazonaws.com
  • Important: Do not include the stage segment (the app appends /v1/...). If you use the CDK output ApiBaseUrl (which includes /v1/), remove the trailing /v1.

Without this variable, the frontend uses an in-memory mock data layer for local development.

The backend is defined with AWS CDK (TypeScript) under backend/ and deploys:

• DynamoDB tables: Users, Events, RSVPs, VolunteerReports, OrganizerReports, AggregateImpact (+ GSIs)
• S3 bucket for photos
• Cognito User Pool + User Pool Client
• EventBridge Event Bus + rules
• SQS queues (notification, impact) with DLQs
• SNS topics (organizer, volunteer)
• API Gateway REST API (/v1) with Lambda integrations
• Lambda functions (Python 3.12): API handler, Notifications processor, Impact processor

cd backend
npm install

# First time in an account/region
npx cdk bootstrap

# Deploy the stack
npm run deploy

After deployment, note the CloudFormation outputs:

• ApiBaseUrl: e.g., https://xxxx.execute-api.us-east-2.amazonaws.com/v1/
• UserPoolId, UserPoolClientId
• EventBusName, PhotosBucketName

Configure the frontend to use the backend:

# frontend/.env.local
BACKEND_API_BASE_URL=https://xxxx.execute-api.us-east-2.amazonaws.com

# From backend/
npm run synth
npm run diff
npm run deploy
npm run destroy

• Cognito is provisioned, but the current frontend uses a mock auth path for RSVP creation.
• When wiring Cognito on the frontend, send the Authorization: Bearer <JWT> header; protected routes in API Gateway will validate JWTs via the User Pool authorizer.

• The frontend calls its Next.js API routes (under frontend/app/api/*).
• Those routes proxy to the backend when BACKEND_API_BASE_URL is set, adapting response shapes where needed.
• Without the env var, the routes use a local in-memory store to enable offline development.