Mashal - Digital Career Guidance Platform

Mashal is a browser-based education and career guidance platform built for students, parents, counselors, and government administrators. It combines public career-discovery pages, role-based dashboards, a career assessment workflow, an AI-assisted roadmap generator, CMS screens for notices and scholarships, and progressive-web-app notification support.

The project is intentionally implemented as a static web application using HTML, CSS, and vanilla JavaScript so it can be hosted on GitHub Pages, Netlify, Firebase Hosting, or any basic static server.

Project Goals

• Help students explore colleges, career paths, services, aptitude guidance, and personalized next steps.
• Give parents and counselors role-specific dashboards for tracking student progress and counseling activity.
• Provide administrators with CMS screens for notices, scholarships, exams, user management, and alerts.
• Demonstrate Firebase Authentication, Firestore, Realtime Database, Firebase Cloud Messaging, and Google Gemini API integration in a frontend-only prototype.
• Keep the repository clean and public-safe for portfolio, resume, and open-source sharing.

Core Features

Area	Description	Key Files
Marketing and discovery site	Landing page, services, college discovery, career paths, about, and contact pages.	index.html, services.html, colleges.html, career-paths.html, about.html, contact.html
Authentication and RBAC	Signup/login flows for students, parents, counselors, and government administrators with role-based dashboard routing.	login.html, student-signup.html, parent-signup.html, counselor-signup.html, admin-signup.html, scripts/firebase-config.js, scripts/rbac-protection.js
Role dashboards	Role-aware dashboard UI that changes navigation, cards, and actions based on user type.	dashboard.html, scripts/rbac-dashboard.js, profiles/
Career assessment	Multi-step assessment that captures academics, interests, aptitude answers, and recommended career options.	career-assessment/index.html, career-assessment/app.js, career-assessment/styles.css
AI career roadmap	Reads the latest assessment submission from Firebase and asks Gemini to generate a personalized career plan. Includes PDF export support.	career-roadmap/index.html, career-roadmap/script.js, career-roadmap/styles.css
CMS module	Admin-facing screens for notices, scholarships, exams, CMS overview, and user management.	cms/, admin-users.html
Notifications and PWA	Notification preferences, timeline, service worker registration, manifest metadata, and Firebase Messaging hooks.	notification-settings.html, timeline.html, scripts/notification-service.js, scripts/firebase-messaging-sw.js, manifest.json, icons/
Counselor portal	Counselor-focused scheduling, ticket, calendar, and appointment interface.	counselor-system/

Tech Stack

• Frontend: HTML5, CSS3, vanilla JavaScript
• Styling: custom CSS with Font Awesome icons
• Backend services: Firebase Authentication, Firestore, Realtime Database, Firebase Cloud Messaging
• AI integration: Google Gemini API
• PWA support: web app manifest, service worker, install metadata, notification hooks
• Export support: jsPDF for roadmap PDF generation
• Hosting model: static hosting, no Node backend required

Repository Structure

.
├── index.html
├── services.html
├── colleges.html
├── career-paths.html
├── about.html
├── contact.html
├── login.html
├── dashboard.html
├── timeline.html
├── profile.html
├── admin-users.html
├── career-assessment/
│   ├── index.html
│   ├── app.js
│   └── styles.css
├── career-roadmap/
│   ├── index.html
│   ├── script.js
│   └── styles.css
├── cms/
│   ├── dashboard.html
│   ├── exams.html
│   ├── notices.html
│   ├── scholarships.html
│   └── users.html
├── counselor-system/
│   ├── index.html
│   ├── dashboard.html
│   ├── css/
│   └── js/
├── profiles/
│   ├── admin.html
│   ├── counselor.html
│   ├── parent.html
│   └── student.html
├── scripts/
│   ├── firebase-config.js
│   ├── firebase-messaging-sw.js
│   ├── main.js
│   ├── notification-service.js
│   ├── rbac-dashboard.js
│   └── rbac-protection.js
├── styles/
│   └── main.css
├── icons/
├── manifest.json
└── LICENSE

Important Routes

After starting a local server, use these URLs:

Route	Purpose
/index.html	Public landing page
/services.html	Platform services overview
/colleges.html	College discovery page
/career-paths.html	Career path exploration
/login.html	Role-aware login
/dashboard.html	Main role dashboard
/career-assessment/index.html	Career assessment quiz
/career-roadmap/index.html	AI-powered roadmap generator
/cms/dashboard.html	Admin CMS dashboard
/notification-settings.html	Push notification preferences
/timeline.html	Alerts and timeline view
/counselor-system/index.html	Counselor portal entry

Local Development

No package install is required for the static pages.

python3 -m http.server 3000 --bind 127.0.0.1

Open:

http://127.0.0.1:3000/

You can also use any static server:

npx serve .

Configuration

This repository does not commit real Firebase or Gemini credentials. Public source files use placeholders so the project is safe to publish.

Firebase

Create a Firebase project and enable:

• Email/password authentication
• Firestore
• Realtime Database
• Firebase Cloud Messaging, if notification testing is needed

Then replace the placeholder values in:

• scripts/firebase-config.js
• career-assessment/app.js
• scripts/firebase-messaging-sw.js, only if you plan to test background notifications

The expected config shape is:

{
  apiKey: "YOUR_FIREBASE_API_KEY",
  authDomain: "YOUR_FIREBASE_AUTH_DOMAIN",
  projectId: "YOUR_FIREBASE_PROJECT_ID",
  storageBucket: "YOUR_FIREBASE_STORAGE_BUCKET",
  messagingSenderId: "YOUR_FIREBASE_MESSAGING_SENDER_ID",
  appId: "YOUR_FIREBASE_APP_ID",
  measurementId: "YOUR_FIREBASE_MEASUREMENT_ID",
  databaseURL: "YOUR_FIREBASE_DATABASE_URL"
}

Gemini

The assessment and roadmap modules look for a browser global before making Gemini API calls:

window.MASHAL_GEMINI_API_KEY = "YOUR_GEMINI_API_KEY";

For production, route AI calls through a backend or serverless function instead of exposing API keys in the browser.

Push Notifications

For Firebase Cloud Messaging token registration, provide:

window.MASHAL_FIREBASE_VAPID_KEY = "YOUR_PUBLIC_VAPID_KEY";

Without Firebase and VAPID configuration, notification UI pages still render, but token registration and background push delivery remain disabled.

Data Flow

1. Users sign up or log in through Firebase Authentication.
2. Role and profile information is stored in Firebase and used by RBAC helpers.
3. Dashboard navigation is assembled from the authenticated user role.
4. The career assessment writes submissions to Realtime Database.
5. The roadmap generator reads the most recent submission and sends a structured prompt to Gemini.
6. CMS screens manage notices, scholarship entries, exam data, and admin views.
7. Notification preferences and timeline pages use Firebase data plus service-worker hooks for PWA behavior.

Security Notes

• Do not commit real Firebase, Gemini, or VAPID credentials.
• Browser-exposed Firebase config is not a complete secret boundary; protect data with Firebase security rules.
• For production AI calls, use a backend proxy so the Gemini API key is never exposed in client code.
• Restrict Firebase Authentication domains to known local and production origins.
• Review Firestore and Realtime Database rules before deploying beyond a demo environment.

Portfolio Highlights

This project demonstrates:

• Multi-role product thinking for students, parents, counselors, and administrators.
• Role-based access control in a static frontend application.
• Firebase-backed authentication and data modeling.
• AI-assisted career guidance workflow using assessment data.
• PWA and push-notification architecture.
• CMS-style admin surfaces for education-sector content.
• Practical cleanup for a public GitHub portfolio: sanitized secrets, professional folder names, removed debug artifacts, and documented setup.

Deployment

The app can be deployed to any static hosting provider.

GitHub Pages

1. Push the repository to GitHub.
2. Open repository settings.
3. Enable Pages for the main branch and repository root.
4. Add the GitHub Pages domain to Firebase authorized domains if auth is enabled.

Firebase Hosting

npm install -g firebase-tools
firebase login
firebase init hosting
firebase deploy

Netlify or Vercel

Use the repository root as the publish directory. No build command is required.

Known Limitations

• The project is a static frontend prototype, not a complete production backend.
• Firebase security rules are required before using real student data.
• Gemini API calls are client-side in this prototype and should be proxied for production.
• Some flows require live Firebase data and will show configuration warnings until credentials are supplied.

License

This project is released under the MIT License. See LICENSE for details.