Skip to content

About

An AI-powered exam seat finder and direction guide for Jahangirnagar University students | ema

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐ŸŽฏ JU SeatFinder - Smart Exam Seat & Direction Guide

JU SeatFinder Logo

An AI-powered exam seat finder and direction guide for Jahangirnagar University students

React TypeScript Tailwind CSS Vite License

๐Ÿš€ Live Demo โ€ข ๐Ÿ“– Documentation โ€ข ๐Ÿ› Report Bug โ€ข โœจ Request Feature


๐ŸŒŸ Features

๐ŸŽฏ Core Functionality

  • ๐Ÿ” Smart Search: Find exam seat details by roll number instantly
  • ๐Ÿ“ Step-by-Step Directions: Detailed navigation to exam rooms with visual guides
  • โฐ Real-Time Clock: Live time display with exam countdown timer
  • ๐Ÿ—บ๏ธ Interactive Maps: Direct Google Maps integration with live preview
  • ๐Ÿ“ฑ Fully Responsive: Optimized for all devices (mobile, tablet, desktop)
  • ๐ŸŒ™ Dark/Light Mode: Toggle between themes with smooth transitions

๐Ÿค– AI-Powered Assistant - Ema

  • ๐Ÿ’ฌ Personalized Advice: AI companion providing motivational support
  • ๐Ÿ”„ Real-Time Updates: Dynamic advice updates every 2 seconds
  • ๐ŸŽฏ Context-Aware: Personalized messages based on student name and gender
  • ๐Ÿ’ Emotional Support: Encouraging messages for exam success
  • ๐Ÿง  Smart Guidance: Intelligent responses based on exam preparation

๐ŸŽจ Modern UI/UX

  • โœจ Smooth Animations: Micro-interactions and floating dot backgrounds
  • ๐Ÿ“Š Live Status Bar: Battery, network, weather, time, and date indicators
  • ๐ŸŽญ Gender Detection: Smart student profile enhancement
  • ๐Ÿ“‹ Exam Checklist: What to bring and what to avoid sections
  • ๐Ÿ† Success Preparation: Motivational cards and countdown timers

๐Ÿ“Š Real-Time Data Integration

  • ๐ŸŒค๏ธ Weather Integration: Current weather conditions for exam day
  • โฑ๏ธ Live Clock: Real-time updates with timezone support
  • ๐Ÿ“… Date Display: Current date with full formatting
  • ๐Ÿ”‹ Device Status: Battery level and network status monitoring
  • ๐Ÿ“ก Online/Offline Detection: Connection status with visual indicators

๐Ÿš€ Quick Start

Prerequisites

  • Node.js (v18 or higher)
  • npm or yarn

Installation

  1. Clone the repository

    git clone https://github.com/afrozaema/SeatFinder.git
    cd SeatFinder
  2. Install dependencies

    npm install
    # or
    yarn install
  3. Start development server

    npm run dev
    # or
    yarn dev
  4. Open your browser

    http://localhost:5173
    

๐Ÿ—๏ธ Project Structure

ju-seatfinder/
โ”œโ”€โ”€ ๐Ÿ“ public/
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ centers.txt          # Student data database
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ robots.txt           # SEO robots configuration
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ sitemap.xml          # SEO sitemap
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ site.webmanifest     # PWA manifest
โ”‚   โ””โ”€โ”€ ๐Ÿ–ผ๏ธ favicon.svg          # App icon
โ”œโ”€โ”€ ๐Ÿ“ src/
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ App.tsx              # Main application component
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ main.tsx             # Application entry point
โ”‚   โ”œโ”€โ”€ ๐Ÿ“„ index.css            # Global styles with animations
โ”‚   โ””โ”€โ”€ ๐Ÿ“„ vite-env.d.ts        # TypeScript definitions
โ”œโ”€โ”€ ๐Ÿ“„ package.json             # Dependencies and scripts
โ”œโ”€โ”€ ๐Ÿ“„ tailwind.config.js       # Tailwind CSS configuration
โ”œโ”€โ”€ ๐Ÿ“„ vite.config.ts           # Vite configuration
โ”œโ”€โ”€ ๐Ÿ“„ tsconfig.json            # TypeScript configuration
โ””โ”€โ”€ ๐Ÿ“„ README.md                # Project documentation

๐Ÿ’พ Data Format

The student data is stored in public/centers.txt with the following format:

Roll|Name|Institution|Building|Room|Floor|ReportTime|StartTime|EndTime|Directions|MapURL
230417|Sadia Islam|NSU|Main Building|506|5th Floor|10:00 AM|12:00 PM|2:00 PM|Enter through Gate 2 โžž Walk to Main Building โžž Go to 5th Floor โžž Room 506 on your right|https://www.google.com/maps?q=23.8156,90.4253

Data Fields:

  • Roll: Student roll number (unique identifier)
  • Name: Full student name
  • Institution: University/Institution code
  • Building: Exam building name
  • Room: Room number
  • Floor: Floor information
  • ReportTime: Exam reporting time
  • StartTime: Exam start time
  • EndTime: Exam end time
  • Directions: Step-by-step navigation (separated by โžž)
  • MapURL: Google Maps link with coordinates

๐ŸŽจ Design System

๐ŸŽจ Color Palette

  • Primary: Blue to Purple gradient (from-blue-600 to-purple-600)
  • Secondary: Purple to Pink gradient (from-purple-500 to-pink-500)
  • Success: Green shades (green-50 to green-900)
  • Warning: Yellow to Orange gradient (from-yellow-50 to-orange-50)
  • Error: Red shades (red-50 to red-900)
  • Info: Cyan to Blue gradient (from-cyan-500 to-blue-500)

๐Ÿ“ฑ Responsive Breakpoints

  • Mobile: < 640px (sm) - Optimized for phones
  • Tablet: 640px - 1024px (md) - Perfect for tablets
  • Desktop: > 1024px (lg) - Full desktop experience

๐ŸŽญ Animation System

  • Floating Dots: Multi-layer animated background patterns
  • Micro-interactions: Hover effects and button animations
  • Loading States: Smooth loading indicators
  • Transitions: Seamless theme switching and state changes

๐Ÿ”ง Configuration

Environment Variables

Create a .env file in the root directory:

VITE_APP_TITLE=JU SeatFinder
VITE_API_BASE_URL=https://api.example.com
VITE_WEATHER_API_KEY=your_weather_api_key

Tailwind CSS

The project uses Tailwind CSS for styling. Configuration is in tailwind.config.js:

module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      animation: {
        'float': 'float 6s ease-in-out infinite',
        'pulse-slow': 'pulse 3s ease-in-out infinite',
      }
    },
  },
  plugins: [],
}

๐Ÿš€ Deployment

Build for Production

npm run build
# or
yarn build

Deploy to Netlify

  1. Build the project: npm run build
  2. Upload the dist folder to Netlify
  3. Configure redirects for SPA routing

Deploy to Vercel

npm install -g vercel
vercel --prod

Deploy to GitHub Pages

npm run build
npm run deploy

๐Ÿค– Ema Assistant Features

๐Ÿ’ฌ Personalized Messages

  • Uses student's first name for personalization
  • 15+ unique motivational messages
  • Updates every 2 seconds for dynamic experience
  • Gender-aware messaging for better connection

๐ŸŽฏ Message Categories

  • Confidence Boosters: "You are stronger than you think!"
  • Preparation Reminders: "You've prepared well for this!"
  • Stress Relief: "Take deep breaths and stay confident!"
  • Success Motivation: "Your hard work will definitely pay off!"
  • Exam Day Tips: "Remember to stay hydrated and focused!"

๐Ÿ”„ Real-Time Features

  • Automatic message rotation every 2 seconds
  • Live status indicator showing "Live" updates
  • Smooth animations and transitions
  • Context-aware advice based on exam timing

๐Ÿ“Š API Integrations

๐ŸŒ External APIs Used

  1. World Time API: Real-time clock and date

    https://worldtimeapi.org/api/timezone/Asia/Dhaka
  2. Quotable API: Motivational quotes

    https://api.quotable.io/random?tags=motivational,success
  3. Genderize API: Gender detection from names

    https://api.genderize.io?name={firstName}
  4. OpenWeatherMap API: Weather information

    https://api.openweathermap.org/data/2.5/weather?q=Dhaka
  5. Google Maps API: Interactive maps and directions

    https://www.google.com/maps?q={latitude},{longitude}

๐ŸŽฏ Usage Examples

Basic Search

// Search for a student by roll number
const rollNumber = "230417";
const student = centersData.find(s => s.roll === rollNumber);

if (student) {
  console.log(`Found: ${student.name} in ${student.building} Room ${student.room}`);
}

Ema Advice Generation

// Generate personalized advice
const firstName = studentData.name.split(' ')[0];
const randomAdvice = emaAdviceMessages[Math.floor(Math.random() * emaAdviceMessages.length)];
const personalizedAdvice = randomAdvice.replace('{name}', firstName);

Live Status Updates

// Update live time every second
useEffect(() => {
  const interval = setInterval(() => {
    const now = new Date();
    setLiveTime(now.toLocaleTimeString('en-US', {
      hour: '2-digit',
      minute: '2-digit',
      second: '2-digit',
      hour12: true
    }));
  }, 1000);
  return () => clearInterval(interval);
}, []);

๐Ÿ› ๏ธ Development

Available Scripts

  • npm run dev - Start development server with hot reload
  • npm run build - Build for production with optimizations
  • npm run preview - Preview production build locally
  • npm run lint - Run ESLint for code quality

Code Style

  • TypeScript: Strict mode enabled with comprehensive type checking
  • ESLint: React and TypeScript rules for consistent code
  • Prettier: Code formatting (recommended setup)
  • Conventional Commits: Standardized commit messages

Git Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit changes: git commit -m 'feat: add amazing feature'
  4. Push to branch: git push origin feature/amazing-feature
  5. Open a Pull Request with detailed description

๐Ÿ› Troubleshooting

Common Issues

1. API Calls Failing

# Check network connection
ping google.com

# Verify API endpoints are accessible
curl https://worldtimeapi.org/api/timezone/Asia/Dhaka

2. Data Not Loading

  • Ensure centers.txt is in the public folder
  • Check file format and encoding (UTF-8)
  • Verify data structure matches expected format

3. Responsive Issues

  • Clear browser cache and cookies
  • Check Tailwind CSS classes for responsive prefixes
  • Test on different devices and browsers

4. Build Errors

# Update Node.js to latest LTS version
nvm install --lts
nvm use --lts

# Clear cache and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check TypeScript errors
npm run type-check

5. Performance Issues

  • Optimize images and assets
  • Check for memory leaks in useEffect hooks
  • Monitor API call frequency and implement caching

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Ways to Contribute

  • ๐Ÿ› Bug Reports: Report issues and bugs with detailed reproduction steps
  • โœจ Feature Requests: Suggest new features with use cases
  • ๐Ÿ“ Documentation: Improve documentation and examples
  • ๐ŸŽจ Design: UI/UX improvements and design suggestions
  • ๐Ÿ’ป Code: Bug fixes, new features, and performance improvements
  • ๐ŸŒ Translations: Help translate the app to other languages

Development Setup

  1. Fork and clone the repository
  2. Install dependencies: npm install
  3. Create a feature branch: git checkout -b feature/your-feature
  4. Make your changes with proper testing
  5. Commit with conventional commit format
  6. Push and submit a pull request

Code Review Process

  1. All PRs require at least one review
  2. Automated tests must pass
  3. Code coverage should not decrease
  4. Follow existing code style and patterns
  5. Update documentation if needed

๐Ÿ“„ License

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

MIT License

Copyright (c) 2025 Afroza Akter Ema

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

๐Ÿ‘ฅ Team

๐Ÿ’ Created with Love by

Afroza Akter Ema

Full Stack Developer & UI/UX Designer

Portfolio LinkedIn GitHub Twitter


๐Ÿ™ Acknowledgments

  • Jahangirnagar University - For inspiration and educational excellence
  • React Team - For the amazing framework and ecosystem
  • Tailwind CSS - For the utility-first CSS framework
  • Lucide React - For beautiful and consistent icons
  • Vite - For lightning-fast development experience
  • TypeScript - For type safety and developer experience
  • Netlify - For seamless deployment and hosting
  • Open Source Community - For continuous inspiration and support

๐Ÿ“ˆ Project Stats

GitHub stars GitHub forks GitHub watchers GitHub issues GitHub pull requests GitHub last commit

Made with โค๏ธ for JU Students


๐Ÿ”ฎ Future Roadmap

๐Ÿš€ Upcoming Features

  • ๐Ÿ“ฑ Progressive Web App (PWA): Offline support and app installation
  • ๐Ÿ”” Push Notifications: Exam reminders and important updates
  • ๐ŸŒ Multi-language Support: Bengali and English language options
  • ๐Ÿ“Š Analytics Dashboard: Usage statistics and insights
  • ๐ŸŽฏ Advanced Search: Filter by building, time, or institution
  • ๐Ÿ“ Exam Notes: Personal notes and reminders feature
  • ๐Ÿ‘ฅ Student Community: Chat and discussion features
  • ๐Ÿ“ฑ Mobile App: Native iOS and Android applications

๐ŸŽจ Design Enhancements

  • ๐ŸŽญ Custom Themes: Multiple color schemes and themes
  • โœจ Advanced Animations: More sophisticated micro-interactions
  • ๐Ÿ“ฑ Better Mobile UX: Enhanced mobile-first design
  • ๐ŸŽจ Accessibility: WCAG 2.1 AA compliance
  • ๐Ÿ–ผ๏ธ Visual Improvements: Better graphics and illustrations

๐Ÿ”ง Technical Improvements

  • โšก Performance: Code splitting and lazy loading
  • ๐Ÿ”’ Security: Enhanced data protection and privacy
  • ๐Ÿ“Š Monitoring: Error tracking and performance monitoring
  • ๐Ÿงช Testing: Comprehensive test coverage
  • ๐Ÿ“š Documentation: Interactive API documentation

๐Ÿš€ Ready to find your exam seat? Get Started Now!


โญ If this project helped you, please give it a star! โญ

About

An AI-powered exam seat finder and direction guide for Jahangirnagar University students | ema

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages