🎓 Exam Countdown App

A modern, AI-powered exam countdown application built with React, Firebase, and Google's Generative AI. Get personalized motivation and study tips tailored to your exam preparation timeline with secure user data persistence.

✨ Features

🔐 Anonymous Authentication

• Seamless Firebase anonymous authentication
• Secure user data isolation
• Cross-device synchronization with persistent user sessions
• Automatic sign-in without registration requirements

🕐 Smart Countdown Timer

• Real-time countdown display with days, hours, minutes, and seconds
• Responsive grid layout with color-coded time units
• Automatic state transitions (loading → initial → active → finished)
• Persistent countdown data with user-specific storage

🤖 AI-Powered Personalization

• Context-aware motivational messages using Google's Gemini AI
• Dynamic study tips based on remaining preparation time
• Intelligent content generation for different phases:
  • 50+ days: Long-term planning and burnout prevention strategies
  • 30-50 days: Foundation building and consistent effort motivation
  • 7-30 days: Active learning and concept mastery techniques
  • 2-7 days: Final review strategies and confidence building
  • 1 day: Last-minute preparation and stress management
  • Exam day: Confidence boosters and performance tips

📊 Firebase Integration

• Anonymous Authentication for secure user sessions
• Firestore Database for real-time data persistence
• Automatic cleanup of expired countdowns
• Cross-platform synchronization across devices
• Offline-first architecture with seamless sync

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Firebase account with Firestore enabled
• Google AI Studio API key

Installation

1. Clone the repository

   git clone https://github.com/Timmystroge/ExamCountDown-App
   cd ExamCountDown-App

2. Install dependencies

   npm install

3. Set up environment variables Create a .env file in the root directory:

   # Firebase Configuration
    VITE_FIREBASE_API_KEY=YOUR_API_KEY
   VITE_FIREBASE_AUTH_DOMAIN=YOUR_AUTH_DOMAIN
   VITE_FIREBASE_PROJECT_ID=YOUR_PROJECT_ID
   VITE_FIREBASE_STORAGE_BUCKET=YOUR_STORAGE_BUCKET
   VITE_FIREBASE_MESSAGING_SENDER_ID=YOUR_MESSAGING_SENDER_ID
   VITE_FIREBASE_APP_ID=YOUR_APP_ID
   VITE_FIREBASE_DB=YOUR_DATABASE_NAME
   VITE_FIREBASE_DB_COLLECTION=YOUR_COLLECTION_NAME
   
   VITE_LLM_API_KEY=YOUR_LLM_API_KEY
   VITE_LLM_MODEL=YOUR_LLM_MODEL

4. Configure Firebase

   • Create a new Firebase project at Firebase Console
   • Enable Firestore Database in test mode
   • Enable Anonymous Authentication
   • Copy your configuration to the .env file

5. Set up Google AI Studio

   • Visit Google AI Studio
   • Create a new API key
   • Add the key to your .env file as VITE_LLM_API_KEY

6. Start the development server

   npm run dev

📱 Usage

Starting Your First Countdown

1. Launch the app - Anonymous authentication happens automatically
2. Enter exam days (1-365 days until your exam)
3. Click "Start Countdown" or press Enter
4. Get personalized content generated by AI based on your timeline

Active Countdown Experience

• Real-time updates every second
• Daily motivational messages tailored to your preparation phase
• Contextual study tips that evolve with your timeline

Reset and Management

• Reset anytime with confirmation dialog
• Data persistence across browser sessions and devices
• Automatic cleanup when countdowns finish

🛠️ Technical Architecture

Frontend Stack

• React 19: Latest React with concurrent features
• Vite: Lightning-fast build tool and HMR
• Tailwind CSS: Utility-first styling with custom design system
• Lucide React: Beautiful, consistent iconography

Backend Services

• Firebase Firestore: NoSQL real-time database
• Firebase Auth: Anonymous authentication system
• Google Generative AI: Gemini Pro for content generation

Project Structure

src/
├── components/           # React components
│   ├── ExamCountdown.jsx    # Main application component
│   ├── ConfirmResetModal.jsx # Reset confirmation dialog
│   ├── FinishedState.jsx    # Completion celebration screen
│   └── ResetBtn.jsx         # Reset button with footer
├── services/             # Business logic services
│   ├── getLlmPrompts.js     # AI prompt generation logic
│   └── calculateTimeLeft.js # Time calculation utilities
├── lib/                  # External service configurations
│   └── firebase.js          # Firebase initialization
├── App.jsx              # Root application component
└── main.jsx             # Application entry point

State Management Philosophy

• Component-level state for UI interactions
• Firebase for persistence with real-time synchronization
• Refs for performance preventing unnecessary re-renders
• Service layer for business logic separation

🤖 AI Content Generation

Intelligent Prompting System

The app uses a sophisticated prompting system that adapts to your preparation timeline:

• Contextual Awareness: Different strategies for different timeframes
• Motivational Psychology: Evidence-based encouragement techniques
• Study Science: Research-backed learning and retention strategies
• Stress Management: Anxiety reduction and confidence building

Content Categories

• 📈 Motivational Messages: Encouraging words tailored to your phase
• 📚 Study Tips: Actionable advice for effective learning
• 🎯 Strategy Guidance: Phase-specific preparation approaches
• 💪 Confidence Building: Performance anxiety management

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   git commit -m 'Add amazing feature'

4. Push to your branch

   git push origin feature/amazing-feature

5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📧 Support

Need help or have questions?

• GitHub Issues: Report bugs and request features
• Documentation: Check this README for comprehensive guides
• Community: Join discussions in GitHub Discussions

---

Built with ❤️ by TimmyStroge

Transform your exam preparation with AI-powered motivation and smart countdown tracking! 🎓✨