# Trinity Attend 🎓 A comprehensive university attendance tracking system built with Next.js 16, React 19, TypeScript, Tailwind CSS v4, and PostgreSQL. ## ✨ Features ### For Students - 📱 QR code scanning with geolocation validation (100m radius) - 📊 Real-time attendance tracking - 📈 Visual analytics and progress tracking - 📚 Multi-semester course management - 🎓 Automatic session progression - 📥 Export attendance records - 🌓 Dark/Light mode support ### For Teachers - 📝 QR code generation with location validation - 👥 Student enrollment management - 📊 Comprehensive analytics dashboard - 📈 Performance tracking and reporting - 📥 Export to Excel/PDF - 🎯 Course management - 🔍 Advanced filtering and sorting ## 🛠 Tech Stack - **Framework**: Next.js 16 (App Router) - **UI Library**: React 19 - **Language**: TypeScript - **Styling**: Tailwind CSS v4 + Shadcn UI - **Authentication**: Better Auth - **Database**: PostgreSQL (Neon) - **ORM**: Prisma - **State Management**: TanStack Query + Zustand - **Forms**: React Hook Form + Zod - **Charts**: Recharts - **QR Codes**: qrcode.react ## 📋 Prerequisites - Node.js 18.17.0 or higher - npm 9.0.0 or higher - PostgreSQL database (Neon recommended) ## 🚀 Getting Started ### 1. Install Dependencies ```bash cd c:\Users\HP\Desktop\trinity-attend npm install ``` ### 2. Environment Setup Create a `.env.local` file in the root directory: ```env # Database (Get from Neon: https://neon.tech) DATABASE_URL="postgresql://username:password@host/database?sslmode=require" # Better Auth (Generate using: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))") AUTH_SECRET="your-super-secret-key-minimum-32-characters-long" AUTH_URL="http://localhost:3000" BETTER_AUTH_SECRET="your-better-auth-secret-key" # OAuth Providers (Optional) # Google: https://console.cloud.google.com/ GOOGLE_CLIENT_ID="your-google-client-id" GOOGLE_CLIENT_SECRET="your-google-client-secret" # Apple: https://developer.apple.com/ APPLE_CLIENT_ID="your-apple-client-id" APPLE_CLIENT_SECRET="your-apple-client-secret" # Email (Resend: https://resend.com/) RESEND_API_KEY="your-resend-api-key" FROM_EMAIL="noreply@trinityattend.com" # App Config NEXT_PUBLIC_APP_URL="http://localhost:3000" NEXT_PUBLIC_APP_NAME="Trinity Attend" # File Upload (Cloudinary: https://cloudinary.com/) NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloud-name" CLOUDINARY_API_KEY="your-api-key" CLOUDINARY_API_SECRET="your-api-secret" # QR Code Security (Generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))") QR_CODE_SECRET="your-qr-code-hmac-secret-key" # Geolocation (for 100m radius validation) NEXT_PUBLIC_ENABLE_GEOLOCATION="true" NEXT_PUBLIC_MAX_DISTANCE_METERS="100" ``` ### 3. Database Setup ```bash # Push Prisma schema to database npm run db:push # Seed the database with sample data npm run db:seed # (Optional) Open Prisma Studio to view/edit data npm run db:studio ``` ### 4. Run Development Server ```bash npm run dev ``` Open [http://localhost:3000](http://localhost:3000) in your browser. ## 🔑 Environment Variables Setup Guide ### Required API Keys and How to Get Them: 1. **DATABASE_URL** (Required) - Sign up at [Neon](https://neon.tech) - Create a new project - Copy the connection string - Ensure it ends with `?sslmode=require` 2. **AUTH_SECRET & QR_CODE_SECRET** (Required) - Generate using Node.js: ```bash node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" ``` 3. **GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET** (Optional) - Go to [Google Cloud Console](https://console.cloud.google.com/) - Create a new project or select existing - Enable Google+ API - Create OAuth 2.0 credentials - Add authorized redirect URI: `http://localhost:3000/api/auth/callback/google` 4. **APPLE_CLIENT_ID & APPLE_CLIENT_SECRET** (Optional) - Go to [Apple Developer](https://developer.apple.com/) - Create a Services ID - Configure Sign in with Apple - Add return URL: `http://localhost:3000/api/auth/callback/apple` 5. **RESEND_API_KEY** (Optional, for emails) - Sign up at [Resend](https://resend.com/) - Get your API key from the dashboard - Verify your domain for production 6. **CLOUDINARY Credentials** (Optional, for file uploads) - Sign up at [Cloudinary](https://cloudinary.com/) - Get Cloud Name, API Key, and API Secret from dashboard ## 🧪 Demo Credentials After running `npm run db:seed`, you can use: **Teacher Account:** - Email: `teacher@demo.com` - Password: `Demo@1234` **Student Account:** - Matric: `2022/1/12345` OR Email: `student@demo.com` - Password: `Demo@1234` ## 📝 Available Scripts ```bash npm run dev # Start development server npm run build # Build for production npm run start # Start production server npm run lint # Run ESLint npm run db:push # Push schema changes to database npm run db:seed # Seed database with sample data npm run db:studio # Open Prisma Studio ``` ## 📁 Project Structure ``` trinity-attend/ ├── prisma/ │ ├── schema.prisma # Database schema │ └── seed.ts # Seed script ├── src/ │ ├── app/ # Next.js App Router │ │ ├── (auth)/ # Authentication pages │ │ ├── (dashboard)/ # Protected dashboard pages │ │ ├── api/ # API routes │ │ └── page.tsx # Landing page │ ├── components/ # React components │ ├── lib/ # Utility libraries │ │ ├── auth.ts # Better Auth config │ │ ├── db.ts # Prisma client │ │ ├── utils.ts # Utility functions │ │ └── validations/ # Zod schemas │ ├── actions/ # Server actions │ └── hooks/ # Custom React hooks └── public/ # Static assets ``` ## 🚧 Next Steps This is the initial setup. To complete the application, you need to: 1. ✅ Install dependencies 2. ✅ Set up environment variables 3. ✅ Initialize database 4. 📝 Create authentication pages (login/signup) 5. 📝 Build student dashboard 6. 📝 Build teacher dashboard 7. 📝 Implement QR code system with geolocation 8. 📝 Add Excel/PDF export functionality 9. 📝 Deploy to production ## 🔐 Security Features - Password hashing with bcrypt - HMAC-SHA256 QR code signatures - Geolocation validation (100m radius) - Time-limited QR codes (10 min default) - Better Auth session management - CSRF protection - Rate limiting (to be implemented) ## 📞 Support For issues or questions: - Open an issue on GitHub - Email: support@trinityattend.com --- **Made with ❤️ for educational institutions** # trinity-attend