hitam.app / Docs

Documentation

How hitam.app works - app by app

Overview

  • hitam.app is a unified platform for everyone at HITAM - one app, every need.
  • Built as a progressive web app (PWA) for instant access without app stores.
  • Designed for speed, simplicity, and a consistent dark glass-morphism aesthetic.

Tech Stack

  • Next.js 15 + React + TypeScript for the frontend.
  • Tailwind CSS v3 with custom design tokens for styling.
  • Radix UI primitives for accessible components.
  • Serwist for service worker and offline PWA capabilities.

Auth & Security

  • Google Sign-In restricted to @hitam.org email addresses.
  • 4-digit OTP verification via email for beta sign-ups and feedback.
  • HMAC-signed tokens - stateless, no OTP storage in database.
  • Firestore security rules enforce authenticated access.

Data

  • Firebase Firestore for real-time data and user submissions.
  • Student directory synced from official HITAM records.
  • Beta sign-ups and feedback stored with email-as-document-ID for deduplication.

PWA

  • Installable on iOS and Android from the browser.
  • Offline-ready with service worker caching.
  • Standalone display mode for a native app feel.
  • Auto-updates on refresh when new versions are deployed.
App Architecture

Social

  • Feed: Chronological post stream with text, images, and polls. Firestore collection 'posts' with real-time listeners.
  • Stories: 24h ephemeral content using Firebase Storage + Firestore expiry timestamps. Auto-delete via Cloud Functions.
  • DMs: One-to-one and group chats. Firestore subcollection 'messages' under each 'chat' document. Real-time via onSnapshot.
  • Student Discovery: Searchable directory from official HITAM CSV. Indexed by name, roll number, branch.
  • Notifications: Firebase Cloud Messaging for new DMs, story replies, and post mentions. Topics per user.
  • Moderation: Report flow writes to 'reports' collection. Superadmin dashboard for review and action.

ERP

  • Data Source: Scrapes HITAM ERP portal via authenticated HTTP sessions. Caches in Firestore with 15-min TTL.
  • Student Mode: Attendance tracking with visual bars, target calculator, GPA/CGPA calculator, schedule, and performance trends.
  • Faculty Mode: Teachers log in with WebSpro credentials to mark attendance, view class rosters, and browse student attendance profiles.
  • Grades: GPA/CGPA calculator from internal marks. Firestore document per semester with subject breakdown.
  • Schedule: Parses timetable HTML into structured slots. Supports daily/weekly views. Push notifications 10 min before class.
  • Performance Analytics: Trend graphs over semesters. Identifies weak subjects and suggests study groups.
  • Offline Mode: Last-fetched data cached locally via service worker. Syncs when connection returns.

Faculty ERP

  • Mode Toggle: Student/Teacher switch inside the ERP app. Different UI per role.
  • Auth: Teacher logs in with WebSpro ERP credentials. Password AES-encrypted client-side (key/IV: 8701661282118308).
  • Proxy Architecture: hitam.app proxies requests to WebSpro. Session maintained server-side. Password never stored.
  • Flow: Login with WebSpro credentials → View assigned classes → Select class → See student roster → Mark attendance → Submit to WebSpro.
  • Attendance: Present/Absent per student. Submitted directly to WebSpro portal via form POST proxy.
  • Investigation: WebSpro portal analyzed via Playwright headless browser (read-only). Full flow documented in docs/faculty-erp.md.

Canteen

  • Menu: Firestore 'menu' collection with categories, prices, availability flags, and prep-time estimates.
  • Cart: Client-side React state + localStorage backup. Persists across sessions until checkout or expiry.
  • Pre-order: Select pickup time slot. Order writes to 'orders' collection with status: pending / preparing / ready.
  • UPI Payments: Razorpay/UPI intent flow. Webhook updates order status. Receipt generated as PDF via jsPDF.
  • Queue Skip: Orders are batched by time slot. Canteen staff sees kitchen display system (KDS) sorted by prep time.
  • Order History: Per-user subcollection. Reorder in one tap. Spending analytics per month.

Bus Tracker

  • Driver Tracking: Every bus driver installs the app with location enabled while driving. Background GPS uploads lat/lon to Firestore every 30 seconds.
  • Interim Data Source: Until full driver rollout, location data is crowdsourced from the bus transportation WhatsApp community where students share live bus locations each day.
  • Backend: Firestore collection 'bus_locations' with geo-hashed coordinates for efficient spatial queries. TTL cleanup for stale data.
  • Schematic Map: SVG radial projection. Buses plotted by angle (route) and distance (progress). No external map tiles.
  • ETA Engine: Haversine distance + historical average speed per route segment. Updates every 30 seconds.
  • Driver App: Lightweight PWA for drivers. One-tap 'arrived at college' / 'leaving college' status updates.
  • Alerts: Push notifications when saved bus is 10 min away. Delay alerts if ETA slips by >5 min.

hitam.app