AWS Kiro BuildFest 2026 Hackathon.

SyncCircle is a student collaboration web app built for the AWS Kiro BuildFest 2026 hackathon. It helps university students sync timetables, share notes, manage tasks, and study together with real-time friend connections.

Frontend (React + Vite)  →  API Gateway  →  Lambda (Node.js 20)  →  DynamoDB
                              ↓
                        Cognito Auth
                              ↓
                        SES (emails)

The AI Planner page features a conversational chatbot powered by Groq (Llama 3.3 70B) that can read and modify your timetable with permission-based actions.

1. Context-aware — the AI sees your full timetable + friends' timetables + free slots
2. Conflict detection — checks for time overlaps before proposing any action
3. Confirmation required — shows a "Confirm" button; nothing changes without your approval
4. Real modifications — confirmed actions update localStorage + sync to DynamoDB backend
5. Friend availability — cross-references both schedules for accurate mutual free time

User message → Groq API (Llama 3.3 70B) → AI response with [ACTION] blocks
                                                    ↓
                                          Frontend parses action
                                                    ↓
                                          Shows "Confirm" button
                                                    ↓ (user clicks)
                                          Executes: saveClass() / deleteClass()
                                                    ↓
                                          localStorage + backend sync

Add to apps/frontend/.env:

VITE_GROQ_API_KEY=gsk_your_key_here

Get a free key from console.groq.com (30 req/min, 14,400/day free tier).

• Add classes manually, via .ics file import, or by pulling from Google Calendar
• Sync to Google Calendar — pushes your classes to your personal Google Calendar (OAuth2 popup)
• Friend timetable overlay — Filter View lets you check friends' names to overlay their schedule on your grid
• Free slot detection — green highlighted cells show times everyone selected is free
• Backend sync — class changes auto-save to DynamoDB so friends see your latest timetable

• OAuth Client ID created in Google Cloud Console
• Authorized origin: http://localhost:5173
• Calendar API enabled
• Publishing status: Testing (teammates need to be added as test users)

Set VITE_DEV_BYPASS_AUTH=true in .env to skip Cognito login. Seed data (3 friends + 5 classes) auto-loads on first run.

cd SyncCircle
pnpm install

cd apps/frontend
pnpm dev

Open http://localhost:5173 — register with a real email to get started.

cd apps/backend
npx cdk deploy --require-approval never

Requires AWS credentials configured at ~/.aws/credentials.

VITE_API_BASE_URL=https://951chm3o9k.execute-api.ap-southeast-1.amazonaws.com/prod
VITE_COGNITO_USER_POOL_ID=ap-southeast-1_pTCWS6fRL
VITE_COGNITO_CLIENT_ID=djuh7mtqdl2hudmmdk1veigsq

• USER_PROFILES_TABLE — DynamoDB table name
• FRIEND_REQUESTS_TABLE — DynamoDB table name
• FRIENDSHIPS_TABLE — DynamoDB table name
• SES_SENDER_EMAIL — Verified SES sender
• FRONTEND_BASE_URL — For invitation email links
• EMAIL_ADAPTER — Set to "local" to skip SES (logs email instead)

All endpoints require Authorization: Bearer {id_token} (Cognito ID token).

SyncCircle/
├── apps/
│   ├── frontend/          React + Vite + TailwindCSS
│   │   └── src/app/
│   │       ├── hooks/     useAuth, useFriends, useFriendRequests, useGoogleCalendar
│   │       ├── pages/     Auth, Friends, Invitation, Dashboard, Timetable, etc.
│   │       └── lib/       api-client, google-calendar, ics-parser, sgt, storage, seed-data
│   └── backend/           AWS CDK + Lambda handlers
│       ├── src/
│       │   ├── handlers/  Lambda function handlers (friend-requests/, friends/, timetable/, triggers/)
│       │   ├── services/  validation, token, email services
│       │   ├── repositories/  DynamoDB data access layer
│       │   └── utils/     response helpers, logger, canonical pair
│       └── cdk/           CDK infrastructure code
│           └── lib/       Stack + constructs (DynamoDB, Cognito, Lambda, API, SES)
└── packages/
    └── shared/            TypeScript interfaces, API types, error codes

Backend built and wired into CDK. Needs cdk deploy to go live.

• PUT /timetable — saves your classes to UserTimetables DynamoDB table
• GET /friends/{friendId}/timetable — fetches a friend's timetable (checks friendship first)
• Frontend auto-PUTs on every class change (when real auth is active)
• Filter View fetches from API when toggling friends

To deploy: run corepack pnpm exec cdk deploy --require-approval never from apps/backend with AWS credentials configured.

Full conversational AI chatbot with timetable actions:

• Groq API (Llama 3.3 70B) — free tier, 30 req/min
• Actionable chat — add, delete, move, extend classes with confirmation
• Conflict detection — warns about time overlaps, suggests free alternatives
• Friend availability — cross-checks both timetables for mutual free slots
• Group scheduling — creates events + sends email notifications
• Backend infrastructure — 14 new Lambda handlers, 4 DynamoDB tables, CDK construct (ready to deploy)
• 157 passing tests — availability calculator, planning service, privacy enforcement

To use: Add VITE_GROQ_API_KEY to frontend .env and run npm run dev.

To enable real invitation emails:

1. Verify sender email in SES console (or request production access)
2. Change EMAIL_ADAPTER from 'local' to '' in cdk/lib/lambda-construct.ts
3. Redeploy

# Deploy backend changes
cd apps/backend && npx cdk deploy --require-approval never

# Run frontend
cd apps/frontend && pnpm dev

# Type check everything
cd apps/backend && npx tsc --noEmit
cd apps/frontend && npx tsc --noEmit

# Run backend tests
cd apps/backend && npx vitest run

# CDK synth (preview CloudFormation without deploying)
cd apps/backend && npx cdk synth