A comprehensive, full-stack student academic management platform that empowers students to track their grades, attendance, tasks, and career opportunities — all in one beautifully designed dashboard.
Features · Tech Stack · Getting Started · Project Structure · Usage Guide · Screenshots
AcademiFlow is a modern, feature-rich academic management portal designed for college students and administrators. Built with React 19, TypeScript, and Firebase, it provides students with a powerful personal dashboard to simulate their CGPA with what-if scenarios, track attendance with safety thresholds, manage tasks with intelligent urgency scoring, discover eligible career opportunities, monitor coding platform progress, and maintain a personal diary — all while keeping data securely synced to the cloud via Firestore. The platform also includes a unique Mentor Share Link feature that allows students to generate time-limited, shareable URLs so mentors, parents, or advisors can view their academic progress without needing an account. On the admin side, HODs and placement officers get a dedicated panel to manage students, post opportunities, and review event attendance requests. With its polished UI featuring interactive particle animations, glow-effect cards, dark mode support, and a responsive design, AcademiFlow delivers a premium experience that makes academic management feel effortless.
| Feature | Description |
|---|---|
| 🎯 CGPA Simulator | Add subjects and marks, then enter hypothetical scores for upcoming exams to simulate your projected CGPA in real time |
| 📊 Attendance Tracker | Track classes and labs per subject with automatic percentage calculation and safety indicators (≥75% Safe, ≥60% Warning, <60% Low) |
| ✅ Smart Task Manager | Create, edit, and organize tasks with an intelligent urgency scoring algorithm that auto-detects overdue items and sorts by priority |
| 💼 Opportunities Feed | Browse internships, placements, scholarships, and competitions with automatic eligibility filtering based on your CGPA, branch, and semester |
| 🤖 AI Insights | Get contextual suggestions and alerts about attendance risks, grade warnings, opportunity matches, and weekly performance summaries |
| 🔴 Weak Subject Radar | Automatically detects subjects where you're scoring below 50% and calculates the exact minimum marks needed in remaining assessments to pass |
| 🔗 Mentor Share Link | Generate a secure, time-limited URL that mentors, parents, or advisors can use to view your academic dashboard — no login required |
| 💻 Productive Score | Connect your LeetCode, HackerRank, and CodeChef profiles to track coding problem stats and overall productivity |
| 📓 Personal Diary | Journal your academic journey with mood tracking (😊 Happy, 😐 Neutral, 😰 Stressed, 🔥 Motivated) |
| 🎫 Event Attendance | Submit event attendance requests with details about venue, timing, and purpose for admin approval |
| 📄 PDF Report Generator | Generate a professional, downloadable semester report with student details, GPA summary, subject performance, attendance, and a motivational quote |
| 🌙 Dark Mode | Full dark theme with smooth transitions for comfortable viewing |
| ⚙️ Profile Settings | Edit your name, branch, semester, upload a profile photo, and manage your mentor share links |
| Feature | Description |
|---|---|
| 📈 Dashboard Overview | At-a-glance stats on total students, at-risk students, and system activity |
| 👥 Student Management | View all registered students with their branch, semester, CGPA, and risk status |
| 📢 Opportunity Posting | Post new internships, placements, scholarships, and competitions with eligibility criteria |
| 🎫 Event Ticket Review | Review, approve, or reject student event attendance requests with admin notes |
| 🔐 Admin Whitelist | Manage which email addresses have admin access to the platform |
| Layer | Technology |
|---|---|
| Frontend | React 19 · TypeScript 5.9 · Vite 7 |
| Styling | TailwindCSS 4 · Custom CSS animations |
| Authentication | Firebase Auth (Email/Password) |
| Database | Cloud Firestore |
| PDF Generation | jsPDF · jspdf-autotable |
| Icons | Lucide React |
| Utilities | date-fns · clsx · tailwind-merge · uuid |
| Deployment | Firebase Hosting |
- Node.js (v18 or later)
- npm (v9 or later)
- A Firebase project with Auth and Firestore enabled
-
Clone the repository
git clone https://github.com/yourusername/academiflow.git cd academiflow -
Install dependencies
npm install
-
Set up Firebase configuration
Copy the example environment file and fill in your Firebase credentials:
cp .env.example .env.local
Edit
.env.localwith your Firebase project values:VITE_FIREBASE_API_KEY=your_api_key VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com VITE_FIREBASE_PROJECT_ID=your_project_id VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id VITE_FIREBASE_APP_ID=your_app_id
-
Start the development server
npm run dev
-
Open in browser
Navigate to
http://localhost:5173to see the app running.
npm run build
npm run preview # Preview the production build locallyacademiflow/
│
├── index.html # Entry HTML
├── package.json # Dependencies & scripts
├── vite.config.ts # Vite config with TailwindCSS & path aliases
├── tsconfig.json # TypeScript configuration
├── firebase.json # Firebase Hosting & Firestore config
├── firestore.rules # Firestore security rules
├── firestore.indexes.json # Firestore indexes
├── .firebaserc # Firebase project mapping
├── .env.example # Environment variable template
│
└── src/
├── main.tsx # React entry point
├── App.tsx # Root component with routing & auth logic
├── firebase.ts # Firebase SDK initialization
├── index.css # Global styles, animations & dark mode
│
├── components/
│ ├── features/ # Page-level feature components
│ │ ├── Login.tsx # → Email/password login with role selection
│ │ ├── SignUp.tsx # → Multi-step sign-up with email verification
│ │ ├── Dashboard.tsx # → Student home — stats, tasks, weak subjects
│ │ ├── AdminDashboard.tsx # → Admin panel — students, opportunities, tickets
│ │ ├── MentorView.tsx # → Public read-only view for mentors (no auth)
│ │ ├── CGPASimulator.tsx # → Subject/marks manager + what-if simulator
│ │ ├── Attendance.tsx # → Per-subject class & lab attendance tracker
│ │ ├── EventAttendance.tsx # → Submit & track event attendance tickets
│ │ ├── Tasks.tsx # → Task CRUD with urgency scoring
│ │ ├── Opportunities.tsx # → Browse opportunities with eligibility filter
│ │ ├── AIInsights.tsx # → Contextual AI-generated insights
│ │ ├── ProductiveScore.tsx # → Coding platform stats (LC, HR, CC)
│ │ ├── Diary.tsx # → Personal journal with mood tracking
│ │ └── Settings.tsx # → Profile editor + share link management
│ │
│ ├── layout/ # Layout wrappers
│ │ ├── Layout.tsx # → Student sidebar + responsive shell
│ │ └── AdminLayout.tsx # → Admin sidebar with dark theme
│ │
│ └── ui/ # Reusable UI primitives
│ ├── Button.tsx # → Styled button with variants & loading state
│ ├── Card.tsx # → Card with interactive glow effect
│ ├── Badge.tsx # → Status badges (success, warning, danger, etc.)
│ ├── Toast.tsx # → Toast notification component
│ ├── Antigravity.tsx # → Particle animation (1500 capsules with physics)
│ ├── DotGrid.tsx # → Interactive dot grid background
│ ├── SpotlightCursor.tsx # → Radial glow that follows the cursor
│ └── GlowCard.tsx # → (Reserved)
│
├── context/
│ ├── AppContext.tsx # Global state, auth, Firestore sync (924 lines)
│ ├── ThemeContext.tsx # Dark/light mode toggle
│ └── ToastContext.tsx # Toast notification state
│
├── data/
│ └── mockData.ts # Default empty state for new users
│
├── types/
│ └── index.ts # TypeScript interfaces (User, Subject, Task, etc.)
│
└── utils/
├── cn.ts # Tailwind class merge helper (clsx + twMerge)
├── features.ts # Core algorithms — CGPA, urgency, eligibility, weak subjects
├── firestoreSync.ts # Firestore CRUD — save/load all user data
└── reportGenerator.ts # PDF semester report builder (jsPDF)
- Sign Up — Create an account with your name, email, branch, and semester. Verify your email to activate.
- Log In — Select the Student role and enter your credentials.
- Set Up Subjects — Go to CGPA Simulator → add your current semester subjects with credits and max scores.
- Add Marks — Enter your quiz, midterm, assignment, and final scores as they come in.
- Track Attendance — Navigate to Attendance → enter total and attended classes/labs per subject.
- Manage Tasks — Use the Tasks page to add assignments, projects, and deadlines. Tasks auto-sort by urgency.
- Check Opportunities — Visit Opportunities to see internships and placements. Eligible ones are highlighted automatically.
- Simulate CGPA — Enter hypothetical scores in remaining assessments to see your projected GPA.
- Share with Mentor — Go to Settings → generate a share link → copy and send it to your mentor or parent.
- Download Report — Click Download Report on the Dashboard to generate a PDF of your semester summary.
- Connect Coding Profiles — Go to Productive Score → add your LeetCode/HackerRank/CodeChef usernames.
- Log In — Select the Admin role (your email must be in the admin whitelist).
- View Students — See all registered students, their branches, semesters, and risk statuses.
- Post Opportunities — Add new internships, placements, or scholarships with eligibility criteria.
- Review Event Tickets — Approve or reject student event attendance requests.
- Manage Admin Access — Add or remove admin email addresses from the whitelist.
- Receive a Link — The student will share a unique URL with you.
- Open the Link — No login or account required.
- View Dashboard — See the student's profile, subjects, attendance, and task progress in a read-only format.
⚠️ Note: Share links are time-limited and can be revoked by the student at any time.
AcademiFlow uses Cloud Firestore with the following collections:
Firestore
├── users/{uid} # User profiles (name, email, role, last login)
├── students/{uid} # Student academic info (branch, semester, CGPA)
├── userData/{uid} # All student data as JSON (subjects, marks, tasks,
│ # insights, attendance, diary, coding profiles,
│ # share token, profile extras)
├── shareTokens/{token} # Public token lookup for mentor view
├── opportunities/{id} # Admin-posted opportunities
├── event_tickets/{id} # Event attendance requests
└── logins/{id} # Login event log
- Data is auto-synced to Firestore with 1-second debouncing to minimize writes.
- localStorage is used as a fast local cache for attendance, diary, and coding profile data.
- On login, all data is loaded from Firestore; on logout, all local data is cleared.
- 🌟 Glow Cards — Cards with an interactive radial glow effect that tracks your cursor
- 💡 Spotlight Cursor — A subtle ambient glow that follows your mouse across the dashboard
- ✨ Antigravity Particles — 1,500 capsule-shaped particles on the login screen with mouse-repulsion physics
- 🔵 Dot Grid — An interactive dot grid background with proximity color changes and shockwave effects
- 🎨 Custom Theme — Maroon/crimson gradient palette (
#8B1A1A→#A52422) - 📱 Fully Responsive — Collapsible sidebar with mobile hamburger menu
- 🌙 Dark Mode — Complete dark theme with smooth CSS transitions
- ⚡ Micro-Animations — Slide-ins, scale-ins, badge pulses, button shines, and smooth hover effects
| Variable | Description | Required |
|---|---|---|
VITE_FIREBASE_API_KEY |
Firebase API Key | ✅ |
VITE_FIREBASE_AUTH_DOMAIN |
Firebase Auth Domain | ✅ |
VITE_FIREBASE_PROJECT_ID |
Firebase Project ID | ✅ |
VITE_FIREBASE_STORAGE_BUCKET |
Firebase Storage Bucket | ✅ |
VITE_FIREBASE_MESSAGING_SENDER_ID |
Firebase Messaging Sender ID | ✅ |
VITE_FIREBASE_APP_ID |
Firebase App ID | ✅ |
VITE_FIREBASE_MEASUREMENT_ID |
Firebase Analytics ID | ❌ Optional |
| Command | Description |
|---|---|
npm run dev |
Start the development server on localhost:5173 |
npm run build |
Build for production (outputs to dist/) |
npm run preview |
Preview the production build locally |
⭐ Star this repo if you found it helpful!