# Rajalakshmi Institute of Technology (RIT) Events Hub — System Documentation

Welcome to the comprehensive system documentation for the **RIT Events Hub**, a premium, high-fidelity academic event management, tracking, and auditing portal designed for Rajalakshmi Institute of Technology. 

This document provides a complete breakdown of the website's architecture, user roles, file structures, database schema, operational workflows, and features, accompanied by a detailed site map.

---

## 1. Overview & Core Mission

The **RIT Events Hub** is an institutional web application designed to digitize and manage the entire lifecycle of college events. It replaces manual event scheduling, paper registrations, physical ticket checks, and fragmented certificate auditing with a unified, secure portal.

### Key Objectives:
*   **Decentralized Event Creation:** Enable faculty members to coordinate, schedule, and estimate budgets for departmental activities.
*   **Hierarchical Approvals:** Ensure events undergo appropriate institutional oversight through a HOD-to-Admin approval pipeline.
*   **Intelligent Resource Management:** Prevent venue conflicts and respect departmental/sectional seat quotas.
*   **Continuous Verification for Students:** Link student attendance, certificate uploads, and On-Duty (OD) approvals step-by-step.
*   **Security & Accessibility:** Provide separate, secure authentication models for internal students, external students, coordinators (faculty/HOD), and administrators.

---

## 2. Technology Stack & Integrations

The platform is built using a modern, fast, and secure web development stack:

| Layer | Technology | Description |
| :--- | :--- | :--- |
| **Frontend Framework** | React (v19), TypeScript, Vite | Multi-page single-page application (SPA) state-managed structure. |
| **Styling & Icons** | Tailwind CSS (CDN), FontAwesome | Curated responsive styling using professional color palettes (Deep Blue `#004a99` and Academic Orange `#f97316`). |
| **Backend & Auth** | Supabase (PostgreSQL, Storage, Auth) | Manages authentication, row-level security (RLS), document uploads, and database queries. |
| **PDF Generation** | `jspdf` & `jspdf-autotable` | Compiles detailed, printable event proposals containing budget sheets, schedules, and resource details. |
| **Layout Tools** | `html2canvas` | Used to capture ticket layouts for student downloads. |
| **Fonts** | Google Fonts (Inter, Playfair Display) | Custom typography reflecting academic elegance. |

---

## 3. Database Schema

The database relies on a PostgreSQL schema managed via Supabase. Below are the primary tables and relations:

### `Studentusers` (Internal Students)
*   `id` (UUID, Primary Key, references auth.users)
*   `name` (Text)
*   `email` (Text, Unique)
*   `reg_no` (Text, Unique)
*   `phone` (Text)
*   `department` (Text)
*   `year` (Text)
*   `section` (Text)
*   `college_name` (Text - Default: 'RAJALAKSHMI INSTITUTE OF TECHNOLOGY')
*   `updated_at` (Timestamp)

### `externalusers` (External Students)
*   `id` (UUID, Primary Key, references auth.users)
*   `name` (Text)
*   `email` (Text, Unique)
*   `reg_no` (Text)
*   `phone` (Text)
*   `department` (Text)
*   `year` (Text)
*   `section` (Text)
*   `college` (Text)
*   `college_location` (Text)
*   `gender` (Text)
*   `updated_at` (Timestamp)

### `Facultyusers` (Coordinators & HODs)
*   `id` (UUID, Primary Key, references auth.users)
*   `name` (Text)
*   `email` (Text, Unique)
*   `dept` (Text)
*   `role` (Text - e.g., 'Faculty', 'HOD', 'System Admin')
*   `phone` (Text)
*   `profile_photo` (Text - URL)
*   `updated_at` (Timestamp)

### `Adminusers` (Principal / Director / Administrators)
*   `id` (UUID, Primary Key, references auth.users)
*   `name` (Text)
*   `email` (Text, Unique)
*   `dept` (Text - 'Administration')
*   `updated_at` (Timestamp)

### `events`
*   `id` (UUID, Primary Key)
*   `title` (Text)
*   `location` (Text - Venue name)
*   `date` (Text - Standard format)
*   `category` (Text - 'TECHNICAL' \| 'NON-TECHNICAL' \| 'WORKSHOP' \| 'CENTRE-ACTIVITY')
*   `domain` (Text - references domains.name)
*   `pricing_type` (Text - 'FREE' \| 'PAID')
*   `coordinator` (Text - Coordinator Name)
*   `club` (Text)
*   `image` (Text - Supabase storage URL)
*   `status` (Text - 'Scheduled' \| 'Event Ongoing' \| 'Completed')
*   `max_participants` (Integer)
*   `registration_deadline` (Timestamp)
*   `duration_days` (Integer)
*   `event_summary` (Text)
*   `is_team_event` (Boolean)
*   `team_size_limit` (Integer)
*   `team_composition` (Text - 'MIXED' \| 'INTER_DEPT')
*   `participant_type` (Text - 'INTERNAL' \| 'EXTERNAL' \| 'BOTH')
*   `verification_status` (Text - 'PENDING' \| 'PENDING_HOD' \| 'PENDING_ADMIN' \| 'APPROVED' \| 'REJECTED')
*   `refreshment_expense` (Numeric)
*   `transportation_expense` (Numeric)
*   `session_coverage_fee` (Numeric)
*   `total_expense` (Numeric)
*   `conducting_dept` (Text)
*   `created_by` (UUID, references auth.users)
*   `request_by_faculty` (Timestamp)
*   `request_by_hod` (Timestamp)

### `event_schedule` (Session/Batch Slots)
*   `id` (UUID, Primary Key)
*   `event_id` (UUID, references events.id)
*   `day_idx` (Integer)
*   `batch_idx` (Integer)
*   `date` (Text)
*   `start_time` (Text)
*   `end_time` (Text)

### `resource_persons` (Guest Details)
*   `id` (UUID, Primary Key)
*   `event_id` (UUID, references events.id)
*   `day_idx` (Integer)
*   `batch_idx` (Integer)
*   `schedule_id` (UUID, references event_schedule.id)
*   `type` (Text - 'INTERNAL' \| 'EXTERNAL')
*   `name` (Text)
*   `dept` (Text)
*   `college_name` (Text)
*   `phone` (Text)
*   `email` (Text)

### `event_dept_limits` (Departmental Seat Allocations)
*   `id` (UUID, Primary Key)
*   `event_id` (UUID, references events.id)
*   `department` (Text)
*   `max_seats` (Integer)
*   `section_limits` (JSONB - Maps sections (A, B, C...) to integer limits)

### `registrations` (Student Bookings)
*   `id` (Text, Primary Key - Structured as `${userId}_${eventId}`)
*   `user_id` (UUID, references auth.users)
*   `event_id` (UUID, references events.id)
*   `user_email` (Text)
*   `user_name` (Text)
*   `reg_no` (Text)
*   `phone` (Text)
*   `gender` (Text)
*   `dept` (Text)
*   `section` (Text)
*   `year` (Text)
*   `college` (Text)
*   `payment_status` (Text - 'PENDING' \| 'COMPLETED')
*   `registered_at` (Timestamp)
*   `team_code` (Text)
*   `team_name` (Text)
*   `is_team_leader` (Boolean)
*   `certification_url` (Text)
*   `certification_status` (Text - 'PENDING' \| 'APPROVED' \| 'REJECTED')
*   `od_url` (Text)
*   `od` (Boolean - OD approval)

### `announcements` (Notice Board)
*   `id` (UUID, Primary Key)
*   `title` (Text)
*   `message` (Text)
*   `type` (Text - 'DELAY' \| 'INFO' \| 'URGENT' \| 'ENDED' \| 'ONGOING')
*   `event_id` (UUID, references events.id)
*   `timestamp` (Timestamp)
*   `expires_at` (Timestamp)

### `special_events` (Symposiums & External Links)
*   `id` (UUID, Primary Key)
*   `title` (Text)
*   `description` (Text)
*   `link` (Text)
*   `created_by` (UUID)
*   `is_active` (Boolean)
*   `verification_status` (Text - 'PENDING' \| 'APPROVED' \| 'REJECTED')

### `domains`
*   `id` (UUID, Primary Key)
*   `name` (Text, Unique)
*   `category` (Text)
*   `image` (Text)
*   `status` (Text - 'PENDING' \| 'APPROVED' \| 'REJECTED')
*   `description` (Text)

---

## 4. Operational Workflows & Key Logic

### A. Core Blockage (Preventing Registration Overhead)
To maintain academic integrity, a student **cannot register for any new events** if they have an unfinalized event from the past.
*   **Condition:** If a student is registered for an event that has completed (`status === 'Completed'`), they must upload their certificate and obtain coordinator approval (`certification_status === 'APPROVED'`) and OD status before the system allows them to click "Register" on any future catalog events.

### B. Overlap Prevention (Intelligent Venue Booking)
During event creation, coordinates are validated against active bookings:
*   **Conflict Condition:** When a coordinator selects a venue and date, the system queries existing approved/pending events. If another event occupies the same location, and the date ranges overlap based on the `durationDays`, that venue will be flagged as "Booked" or "Under Verification" in the dropdown, disabling selection.

### C. Quota-Constrained Bookings (Sectional & Departmental Caps)
The event organizer can set constraints for RIT students:
1.  **Department Limits:** Limits registration to `X` seats per department.
2.  **Section Limits:** Further restricts seats down to individual sections (e.g., CSE section `A` gets 10 seats, section `B` gets 5 seats).
3.  **Validation:** When a student attempts registration, the system evaluates their profile (department, section) and checks the respective quota counts in the `registrations` table. If the quota is full, booking is blocked.

### D. Team play Alliance (Team Registrations)
*   For team events, the first student registers and clicks "Form Team", which inserts a random 6-character alphanumeric code (`team_code`) and designates them as `is_team_leader`.
*   Subsequent students register for the event, click "Join Team", and input the code. The system verifies the team is not full (respecting `teamSizeLimit`) and matches `INTER_DEPT` composition requirements before assigning the `team_code` to their registration.

### E. Proposal PDF Compile
Coordinators and Admin can generate a standardized PDF proposal containing:
1.  General overview (departments, clubs, metadata).
2.  Logistical details (location, dates, capacity, formats).
3.  Day-by-day itineraries mapped to guest resource persons and timings.
4.  Departmental seat allocation tables.
5.  Financial projections (Refreshment + Transportation + Session Fees = Total projected budget).
6.  Signature/Verification box showing HOD & Admin approval timestamps.

---

## 5. Portal Flow & Visual Site Map

### A. Navigational Site Map Structure

```
[WELCOME GATEWAY]
 │
 ├── STUDENT PORTAL ────► [STUDENT AUTH (Login / Sign Up)]
 │                         │
 │                         ├── HOME DASHBOARD (Notices, Banner, Stats)
 │                         ├── EVENTS CATALOG (Details, Booking, Team Play)
 │                         ├── REGISTRATIONS (QR Tickets, Track Progress)
 │                         ├── STATUS TRACKER (Detailed Lifecycle Step Visualizer)
 │                         └── PROFILE VIEW (Update Info, Uploaded Credentials)
 │
 ├── FACULTY PORTAL ────► [COORDINATOR AUTH (Faculty / HOD)]
 │                         │
 │                         ├── OVERVIEW (Metrics & Quick Gateways)
 │                         ├── GENERATE EVENTS (Normal, Special, Domains)
 │                         ├── CREATIONS REGISTRY (Manage Owned Events, Edit/Delete)
 │                         ├── STATUS TRACKER (Verify Certificates, Audit ODs)
 │                         ├── EVENT STATUS CONTROL (Announcements, Status Updates)
 │                         ├── ATTENDANCE CONSOLE (Mark Student Attendance)
 │                         ├── PARTICIPANTS console (Download Rosters)
 │                         ├── PROFILE / LOG OUT
 │                         └── HOD VERIFICATION (HOD only - Review Departmental Proposals)
 │
 └── ADMIN PORTAL ──────► [ADMIN AUTH (Principal / Director / System Admin)]
                           │
                           ├── OVERVIEW (System Metrics)
                           ├── VERIFICATION QUEUE (Standard Events, Special Events, Domains)
                           ├── USER MANAGEMENT CONSOLE (Update Profiles, Change Roles)
                           ├── VENUE TRACKER CALENDAR (Visual Schedule & Collision Map)
                           ├── STATUS TRACKER (Audit all college certifications)
                           ├── GLOBAL NOTICES (Institutional notices)
                           └── PROFILE / LOG OUT
```

### B. High-Fidelity Mermaid Routing Diagram

```mermaid
graph TD
    %% Base Gateways
    Welcome[Welcome Screen] -->|Select STUDENT| StudentAuth[Student Authentication]
    Welcome -->|Select COORDINATOR| FacultyAuth[Faculty / HOD Authentication]
    Welcome -->|Select ADMIN| AdminAuth[System Admin Authentication]

    %% Student Pathways
    StudentAuth -->|Authenticated| StudentDash[Student Dashboard]
    StudentDash --> SHome[Home Dashboard]
    StudentDash --> SEvents[Events Catalog]
    StudentDash --> SRegs[Registrations & QR Tickets]
    StudentDash --> STrack[Event Status Tracker]
    StudentDash --> SProfile[Student Profile]

    SEvents -->|Register & Form/Join Team| STrack
    SRegs -->|Verify Status / Upload Certificate| STrack

    %% Faculty Pathways
    FacultyAuth -->|Select Access Level| FacultyLvl{Access Level}
    FacultyLvl -->|Faculty| FacultyOverview[Faculty Dashboard]
    FacultyLvl -->|HOD| HODOverview[Faculty Dashboard + HOD Verification]

    FacultyOverview --> FHome[Overview & Statistics]
    FacultyOverview --> FCreate[Create Event Form]
    FacultyOverview --> FCreations[Manage Creations]
    FacultyOverview --> FTracker[Status Tracker - Certificate Audit]
    FacultyOverview --> FStatus[Event Status & Notices]
    FacultyOverview --> FAttendance[Attendance Console]
    FacultyOverview --> FParticipants[Participants Console]
    FacultyOverview --> FProfile[Faculty Profile]

    HODOverview --> HVerify[HOD Verification Panel]
    HVerify -->|Accept Department Request| FTracker
    HVerify -->|Reject Request| FCreations

    %% Admin Pathways
    AdminAuth --> AdminOverview[Admin Hub]
    AdminOverview --> AHome[System Overview]
    AdminOverview --> AVerifyQueue[Verification Queue - Events/Domains/Special]
    AdminOverview --> AUsers[User Management Console]
    AdminOverview --> AVenue[Venue Tracker Calendar]
    AdminOverview --> ATracker[Status Tracker]
    AdminOverview --> ANotices[Global Announcements]
    AdminOverview --> AProfile[Admin Profile]

    %% Cross-Links
    FCreations -->|Submit Proposal| HVerify
    HVerify -->|Send to Admin Queue| AVerifyQueue
    AVerifyQueue -->|Approve Event| SEvents
```

---

## 6. Directory Layout & Components Guide

### File & Component Inventory

*   `App.tsx`: Main routing and authentication portal manager. Resolves session state, verifies metadata credentials, performs portal security checks, and loads global states.
*   `supabase.ts`: Supabase client configuration, administrative client helper, and helper functions for uploading media (images, certificates) directly to Supabase storage.
*   `types.ts`: TypeScript interfaces defining `Event`, `AppState`, `UserRole`, `StudentRequest`, `Ticket`, `ResourcePerson`, `EventSchedule`, `Announcement`, and `UserProfile`.
*   `constants.tsx`: Lists static categories, default college domain mappings, clubs, and default showcase events.
*   `utils/pdfGenerator.ts`: Handles compiling and exporting the official document proposals for verified events using `jspdf`.

#### Components Directory (`/components/`):
1.  `WelcomeScreen.tsx`: Entrance portal page displaying entry gates for students, faculty coordinators, and admins.
2.  `LoginForm.tsx`: sliding dual-panel login and sign up form handling internal/external student data collection and role checks.
3.  `Dashboard.tsx`: Base container routing student pages.
4.  `HomeDashboard.tsx`: Displays active announcements, stats, special events, and links to catalogs.
5.  `Hero.tsx`: Dynamic slide search and welcome banner for students.
6.  `UpcomingEventsSlider.tsx`: Auto-scrolling showcase slider displaying upcoming events.
7.  `AboutHubSection.tsx`: Summary presentation card describing the Events Hub platform.
8.  `StatsSection.tsx`: Shows real-time totals of events, participants, and clubs.
9.  `AboutSection.tsx`: Institutional overview details, college details, and guidelines.
10. `ContactSection.tsx`: Map coordinates, support addresses, and telephone details for college portals.
11. `EventList.tsx`: Searchable list displaying approved events by domain filter and category.
12. `EventCard.tsx`: Display card for events containing metadata triggers, register commands, and status links.
13. `RegistrationsView.tsx`: Displays registered ticket vouchers. Generates ticket QR code cards capturing registration details, allowing downloading ticket PDFs.
14. `StatusTrackerView.tsx`: visual step progress checker showing the student their certificate review, attendance logs, and OD approvals.
15. `ProfileView.tsx`: Form for students to edit profile settings and view academic transcripts.
16. `AdminLandingPage.tsx`: Base dashboard routing all Coordinator actions.
17. `CreateEventForm.tsx`: Multi-step event proposal compiler managing budgets, itineraries, and quotas.
18. `CreateSpecialEventsView.tsx`: Allows coordinators to publish external program links.
19. `CreateDomainView.tsx`: Form to submit new technical/non-technical domains for college audit.
20. `AdminStatusTrackerView.tsx`: Review board for coordinators/admins to check student certificate uploads, verify details, and approve OD statuses.
21. `AdminEventStatusView.tsx`: Controls notifications, notice updates, and events status transitions.
22. `FacultyParticipantsView.tsx`: Table listing students registered for an event with search/filter.
23. `FacultyAttendanceView.tsx`: Logs session-by-session student attendance check-ins.
24. `FacultyProfileView.tsx`: Base profile for faculty.
25. `FacultyDashboard.tsx`: Console routing Admin actions.
26. `UserManagementView.tsx`: Table displaying all registered users. Admins can edit profile metadata, manually add students, or alter roles.
27. `TicketVerificationView.tsx`: Camera/code scanner allowing organizers to scan student ticket QR codes and update status in real-time.
28. `Footer.tsx`: Institutional styled footer.
29. `PortalAnimation.tsx`: Page transitions and loading animation overlays.