Hackathon Calendar

A Next.js web application that allows users to search for hackathons and automatically sync their schedules to Google Calendar.

Features

• Google OAuth 2.0 Authentication - Sign in with Google to access Calendar features
• Email/Password Authentication - Alternative login method using credentials
• Hackathon Search - Search for hackathons by name
• Schedule Retrieval - Automatically fetch hackathon event schedules
• Google Calendar Integration - Add all events to your Google Calendar with one click
• Beautiful UI - Modern, responsive design with Tailwind CSS

Tech Stack

• Framework: Next.js 14 (App Router)
• Authentication: NextAuth.js
• Styling: Tailwind CSS
• Calendar API: Google Calendar API (googleapis)
• Language: TypeScript

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ installed
• A Google Cloud Platform account
• npm or yarn package manager

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd hackathon-calendar

2. Install Dependencies

npm install
# or
yarn install

3. Set Up Google OAuth Credentials

To enable Google sign-in and Calendar access, you need to create OAuth credentials:

1. Go to Google Cloud Console

2. Create a new project or select an existing one

3. Enable the following APIs:

   • Google Calendar API
   • Google+ API (for user info)

4. Configure OAuth consent screen:

   • Go to APIs & Services > OAuth consent screen
   • Choose External user type
   • Fill in the required fields:
     • App name: "Hackathon Calendar"
     • User support email: your email
     • Developer contact: your email
   • Add scopes:
     • .../auth/userinfo.email
     • .../auth/userinfo.profile
     • .../auth/calendar (Google Calendar access)
   • Add test users if in testing mode

5. Create OAuth credentials:

   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Application type: Web application
   • Name: "Hackathon Calendar Web Client"
   • Authorized redirect URIs:
     • http://localhost:3000/api/auth/callback/google
     • https://your-production-domain.com/api/auth/callback/google (for production)
   • Click Create
   • Copy your Client ID and Client Secret

4. Configure Environment Variables

Create a .env.local file in the root directory:

cp .env.example .env.local

Edit .env.local and add your credentials:

# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# Google OAuth Credentials
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

To generate a secure NEXTAUTH_SECRET:

openssl rand -base64 32

5. Run the Development Server

npm run dev
# or
yarn dev

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

Usage

Signing In

1. With Google:

   • Click "Sign in with Google"
   • Grant calendar permissions
   • You'll be able to add events to your Google Calendar

2. With Email/Password:

   • Enter any email
   • Use password: password123 (demo)
   • Note: Calendar features require Google sign-in

Searching for Hackathons

1. Enter a hackathon name in the search bar
2. Try these examples:
   • "MLH Hackathon"
   • "HackMIT"
   • "TreeHacks"
3. View the schedule of events

Adding Events to Calendar

1. After searching, click "Add to Google Calendar"
2. All events will be added to your primary calendar
3. You'll receive a confirmation message

Project Structure

hackathon-schedule/
├── app/
│   ├── api/
│   │   ├── auth/
│   │   │   └── [...nextauth]/
│   │   │       └── route.ts          # NextAuth configuration
│   │   ├── search/
│   │   │   └── route.ts              # Hackathon search API
│   │   └── add-to-calendar/
│   │       └── route.ts              # Calendar integration API
│   ├── auth/
│   │   └── signin/
│   │       └── page.tsx              # Sign-in page
│   ├── layout.tsx                    # Root layout
│   ├── page.tsx                      # Home page
│   ├── providers.tsx                 # Context providers
│   └── globals.css                   # Global styles
├── components/
│   ├── SearchBar.tsx                 # Search input component
│   └── EventsList.tsx                # Events display component
├── lib/
│   └── google-calendar.ts            # Google Calendar utilities
├── types/
│   └── next-auth.d.ts                # NextAuth type extensions
├── .env.example                      # Environment variables template
├── .env.local                        # Your local environment variables
├── next.config.js                    # Next.js configuration
├── tailwind.config.js                # Tailwind CSS configuration
├── tsconfig.json                     # TypeScript configuration
└── package.json                      # Project dependencies

API Routes

POST /api/search

Search for a hackathon and retrieve its schedule.

Request:

{
  "query": "MLH Hackathon"
}

Response:

{
  "hackathonName": "MLH Hackathon 2024",
  "events": [
    {
      "title": "Opening Ceremony",
      "description": "Welcome address and event kickoff",
      "startDateTime": "2024-11-15T18:00:00-05:00",
      "endDateTime": "2024-11-15T19:00:00-05:00"
    }
  ]
}

POST /api/add-to-calendar

Add events to Google Calendar.

Request:

{
  "hackathonName": "MLH Hackathon 2024",
  "events": [...],
  "calendarId": "primary"
}

Response:

{
  "success": true,
  "addedCount": 7,
  "message": "Successfully added 7 events to your Google Calendar!"
}

GET /api/add-to-calendar

Get list of user's calendars.

Response:

{
  "calendars": [
    {
      "id": "primary",
      "summary": "My Calendar"
    }
  ]
}

Authentication Flow

1. User clicks "Sign in with Google"
2. NextAuth redirects to Google's OAuth consent screen
3. User grants permissions (profile + calendar access)
4. Google redirects back with authorization code
5. NextAuth exchanges code for access token
6. Access token stored in session (via JWT)
7. Token used for subsequent Calendar API calls

Google Calendar Integration

The application uses the Google Calendar API to:

• Validate tokens - Ensure the user's access token is valid
• Retrieve calendars - Get list of user's calendars
• Insert events - Add hackathon events to calendar

Key files:

• lib/google-calendar.ts - Utility functions for Calendar API
• app/api/add-to-calendar/route.ts - API route handling calendar operations

Future Enhancements

Planned Features

1. Real Web Scraping

   • Integrate Puppeteer or Cheerio for live scraping
   • Parse Devpost hackathon pages
   • Extract schedules from official websites
   • Handle various date/time formats

2. Advanced Features

   • Choose which calendar to add events to
   • Customize event reminders
   • Batch processing for multiple hackathons
   • Event conflict detection
   • Calendar sync status tracking

3. Database Integration

   • Store user preferences
   • Cache hackathon schedules
   • Track added events
   • User history

4. Enhanced UI

   • Calendar preview before adding
   • Event customization
   • Timezone selection
   • Mobile app

Deployment

Deploy to Vercel

1. Push your code to GitHub
2. Go to Vercel
3. Import your repository
4. Add environment variables:
   • NEXTAUTH_URL (your production URL)
   • NEXTAUTH_SECRET
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
5. Update Google OAuth redirect URIs with your production URL
6. Deploy!

Important Notes

• Update NEXTAUTH_URL to your production domain
• Add production URL to Google OAuth authorized redirect URIs
• Keep your secrets secure and never commit them to version control

Troubleshooting

Common Issues

"Unauthorized - Please sign in"

• Make sure you're signed in
• Check that your session hasn't expired

"Google sign-in required"

• Sign out and sign back in with Google
• Email/password auth doesn't support Calendar features

"Access token is invalid or expired"

• Sign out and sign back in
• Check Google OAuth credentials are correct

No events found

• Try the example hackathon names
• Check spelling of hackathon name
• Note: Only mock data is available in current version

Events not added to calendar

• Verify Google Calendar API is enabled
• Check OAuth scopes include calendar access
• Ensure you granted calendar permissions during sign-in

Development Notes

Mock Data

Currently, the application uses mock data for hackathon schedules. The following hackathons are available:

• "MLH Hackathon"
• "HackMIT"
• "TreeHacks"

To add real scraping, implement the scraping logic in app/api/search/route.ts.

Environment Variables

Never commit .env.local to version control. Always use .env.example as a template.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - feel free to use this project for your own purposes.

Support

For issues or questions:

• Open an issue on GitHub
• Check the troubleshooting section
• Review Google Calendar API documentation

Acknowledgments

• Built with Next.js
• Authentication by NextAuth.js
• Styled with Tailwind CSS
• Calendar integration via Google Calendar API

---

Made with ❤️ for hackathon enthusiasts