Welcome to the technical documentation of the UITS Event Raiders Single Page Application (SPA). This document outlines the initiative's context, the project's technical architecture, component design, and its version change history.
Important
JavaScript Code Learning Guide: A comprehensive walkthrough of the portal's client-side JavaScript engine is available in learning.md / github/learning.md. This guide details each module's execution flow and its direct front-end user experience (UX) impact.
Repository: https://github.com/oU1TS/events
The UITS Event Raiders is a community-driven initiative organized by the oU1TS Community.
- Core Purpose: Share news about academic, tech, and cultural events (hackathons, programming contests, workshops) and gather groups of interested students to attend and compete together.
- Official Pages:
The project is built entirely on raw, lightweight, and modern web standards: HTML5, CSS3, and Vanilla JavaScript (ES6+). It is structured for zero build-time overhead and rapid loading.
events/
├── .github/
│ ├── scripts/
│ │ ├── generate-rss.js # Automated RSS 2.0 feed generator script
│ │ └── send-push.js # OneSignal REST API automated Node.js dispatch script
│ └── workflows/
│ └── notify.yml # GHA event notification and alerting pipeline
├── feed.xml # Live RSS 2.0 XML syndication feed
├── index.html # Main SPA layout and templates (with OneSignal SDK injection & RSS discovery)
├── style.css # Global stylesheet, design system, and custom toast notification CSS
├── app.js # Main router, dynamic JSON loader, caching validation, and local deadline engine
├── OneSignalSDKWorker.js # OneSignal background push message registration service worker
├── tracker.json # Metadata synchronization tracking registry
├── learning.md # Comprehensive JS code learning guide
├── raids.json # Dynamic data file storing event lists
├── render.html # Local Markdown document rendering viewer
├── render.js # Markdown parser controller & theme syncing
├── LICENSE # Repository license
├── README.md # Quick-start project readme
├── css/
│ └── render.css # Markdown viewer stylesheet (KaTeX/Highlight/TOC)
└── doc/
├── idea/
│ └── Website-Prompt-for-Event-Raiders.md # Initial specs
├── notes/
│ └── phoenix-summit-2026.md # Delegate guidelines markdown
└── prompts/
├── 1. Building Event Raiders SPA.md # Development logs
├── 1.1 implementation_plan.md # Implementation blueprint
├── 1.2 walkthrough.md # Initial release summary
└── 1.3 walkthrough.md # Updated release summary
- How it works: The application listens to
window.location.hashchanges. When a hash is modified (e.g.#raids),app.jsrunsroutePage(). - State Sync: It adds the
.activeclass to the matching section and navbar link while hiding the others. If the hash is empty or invalid, it defaults to#home. - Benefits: Natively supports browser history (back/forward buttons) and makes direct-linking to sections (e.g. sharing the onboarding guide via
#join) fully bookmarkable.
- Data Separation: Event records are kept in
raids.jsonand fetched asynchronously via the Fetch API. - Metadata Schema Expansion: Objects in
raids.jsonsupport standard metadata such as"Type"(representing categories like Hackathons, Programming, etc.),"RegEndDate"(the registration deadline date in YYYY-MM-DD format),"OutsideDhaka"(boolean flag for events hosted outside Dhaka), and"IsOnline"(boolean flag for virtual/online events). - Collapsible Dropdowns: The
subEventsproperty inraids.jsonis a reusable array of items.app.jsparses this array and renders semantic HTML5<details>and<summary>components inside the schedule card. - XSS Prevention: Elements (titles, prices, descriptions) are rendered dynamically using
textContentand basic HTML escaping to block malicious script injections. - Dynamic Registration Status:
app.jsformats the registration deadline string and dynamically compares it against the local system time. It appends a colored status indicator to the metadata group inside the dropdown—closed deadlines are shown as gray/muted with a(Closed)label, and open deadlines are highlighted in green.
- Theme Switching: Managed by toggling the
.light-themeclass on the<body>element. - CSS Custom Properties: Both dark and light themes share identical variable tokens (e.g.
--bg-primary,--accent) defined in HSL ranges for animations. - Preferences Sync: The selected theme is stored in
localStorageand synchronized automatically when loading markdown files inrender.html. It defaults to the user's system preferences (prefers-color-scheme) on initial load.
- Libraries: Uses
marked.jsfor MD parsing,DOMPurifyfor sanitizing markup,highlight.jsfor syntax highlighting, andKaTeXfor mathematical LaTeX equations. - Table of Contents (ToC): Dynamically parses headers (
h1,h2,h3,h4) and compiles a slide-out navigation panel with sticky header offsets.
- Deep Linking: SPA hash routing intercepts hashes matching
#raid-<number>(e.g.#raid-1), internally redirects the user to the#raidssection, and identifies the target raid card. - Smooth Scrolling: Once the dynamic raid data loads and renders, the page automatically performs a smooth scroll centering the targeted card in the viewport.
- Highlight Animation: Applies a brief pulse animation (
highlightPulse) which scales the card slightly, updates the border to the accent color, and casts a glowing box shadow using the theme's accent color (gold for dark, blue for light). - Copy Link Button: Each card features a highlighted copy button next to the status badge. Clicking it copies the absolute URL of the specific card to the clipboard and triggers a 2-second visual feedback (checkmark icon change).
- Campaign Calendar: An interactive modal-based calendar view matching the
"startDate"of each raid campaign. Enforces a perfectly square ratio and height of50vh(mobile) /60vh(desktop) at the body root level to bypass translation containment constraints. - Overlap & Redirection: Displays event counts at the top-right corner of highlighted day cells when multiple events overlap. Clicking a highlighted cell slides up a vertical list overlay of event titles. Clicking a title closes the modal and deep-links directly to the card using
#raid-<number>. - Past Date Cell Graying: Date cells where all campaigns have
"Status": "Past"are rendered with grayed-out muted styling (.calendar-day.highlighted.past-only). If a date cell has multiple overlapping events, it is only grayed out if every event on that date is past; dates with at least one active/future event retain full accent highlight colors. Grayed-out cells remain fully clickable.
- Category Filtering: A custom dropdown button container is placed next to the "Calendar View" button. Selecting a type filters the cards displayed in the DOM dynamically, updating based on categories: Hackathons, Programming, Conferences / Webinars, Congress, Bug Bounties / CTF, Game Jams, Idea & Bizcomps, Olympiad / Carnival.
- Deep Link Reset Integration: Navigating directly to a card via a hash link automatically resets the category filter to "All Types", ensuring the targeted card is present in the DOM and accessible for highlighting and scrolling.
- Default Visibility State: Past raids (events with
"Status": "Past"or whose"endDate"precedes the current system date) are hidden by default (showPastRaids = false), presenting users with current and upcoming campaigns first. - Toggle Controls & Dual Sync: An inline toggle button (
#toggle-past-raids-btn) and stacked floating eye action button (#floating-past-raids-btn) allow users to unhide/hide past raids dynamically. Clicking either button synchronizes active styles, eye/eye-off icons, aria attributes, and triggers re-rendering. - Deep-Link Auto-Unhide: Opening a past raid via deep-link URL (e.g.
#raid-1) automatically setsshowPastRaids = true, updates toggle UI states to "unhide", renders the target card, and scrolls to it.
- Nested
<details>Card Schema: Each raid item in#raids-containeris rendered as a parent collapsible<details class="raid-card parent-raid-card">element. - Summary View: The card's
<summary>presents a clean overview containing"dateRange","Type"tag,"Status"badge,"title", copy link button, bottom-right venue location badge, and rotating chevron indicator. - Expanded View: Opening the parent card reveals
.parent-raid-bodywith full event descriptions, mobile "See More" toggle, venue/fee/schedule details dropdown, and resource links. - Auto-Expansion on Deep-Link:
scrollToRaid()setscard.open = trueautomatically when deep-linking to a campaign.
- Corner Badge Placement: Positioned at the bottom-right corner of each raid card summary header (
.parent-raid-summary) using absolute positioning (.raid-venue-corner-badge). - Online Badge: Renders a blue/cyan pill tag with text
"Online"when"IsOnline": trueinraids.json. - Dynamic OutsideDhaka Badge: Renders an interactive
<a>element linking directly to Google Maps (https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(raid.venue)}). Uses an automated 2-second interval (setInterval) with smooth fade transitions toggling betweenDhaka(strikethrough text) and📍(borderless, backgroundless location pin SVG icon only). Prevents card collapse on click viae.stopPropagation(). - Static Dhaka Physical Venue Badge: Renders a clean borderless & backgroundless location pin icon
📍linked to Google Maps for in-person events in Dhaka ("OutsideDhaka": false&"IsOnline": false). - Protruding Copy Link Button: Relocated
.copy-raid-link-btnto hang protruded outside the top-right corner (top: -10px; right: -10px) attached to.parent-raid-summary(<summary>), ensuring the button remains permanently visible even when the parent card and all nested dropdowns are collapsed. Styled with a 32px circular shape, theme elevation shadows, and hover scale interactions.
- Synchronization & Caching: The static site loads
tracker.jsonwith{ cache: 'no-cache' }upon DOM load, comparing it againstlocalStorage(key:ev_tracker). If new events exist (e.g.eventsCountis greater), it forces a cache-bypassing reload ofraids.jsonusing{ cache: 'no-cache' }. - On-Screen Toast alerts: A premium glassmorphic toast notification slide-in warning is rendered dynamically if the client clock is exactly 1 day prior to any
RegEndDateparsed fromtracker.json'sactiveReminderslist. Commits a unique token tolocalStorage(e.g.ev_alert_sent_[raidNum]) to block duplicate triggers. - OneSignal Web Push Integration: A pre-built
OneSignalSDKWorker.jsservice worker and CDN SDK are loaded to facilitate native background push subscriptions across mobile and desktop devices. - Automated CI/CD Workflows: When merges occur on
raids.json, GitHub Actions launches a Node.js processsend-push.jsusing repository credentials (ONESIGNAL_APP_ID,ONESIGNAL_REST_API_KEY) to push alerts. The same pipeline scans deadlines daily at06:00 AM UTC, sends alerts for tomorrow's deadlines, and pushes updatedtracker.jsonstates back to git.
- RSS 2.0 Specification Compliance: Generates a standard XML feed (
feed.xml) fromraids.jsonfeaturing active/upcoming campaigns with full metadata, sub-event breakdowns, dates, registration deadlines, and deep links. - Automated Feed Generation Script:
.github/scripts/generate-rss.jsparsesraids.json, evaluates event statuses dynamically against the system clock, escapes XML entities, formats RFC 822 timestamps, and compiles valid RSS 2.0 channels with<atom:link rel="self" ...>discovery. - Browser Auto-Discovery: Added
<link rel="alternate" type="application/rss+xml" title="UITS Event Raiders RSS Feed" href="feed.xml">inindex.html<head>for native browser and RSS reader detection. - CI/CD Integration: The GitHub Actions workflow (
.github/workflows/notify.yml) runsnode .github/scripts/generate-rss.json every push toraids.jsonor daily cron run, automatically committing and pushing the updatedfeed.xmlto GitHub Pages. - Cross-Platform Syndication: Allows third-party platforms (e.g., Discord webhooks via Zapier/MonitoRSS, Telegram broadcast bots, RSS aggregators, or the sister project
b1t-Sched) to consume active campaigns in real-time.
- Features:
- Central Database User Management: Connected the portal to the central Supabase database (
ou1ts.github.io). Integrated@supabase/supabase-js@2andenv-config.jsto handle user registration, logins, persistent session tracking, password reset, and profile management (with Student ID, Department, and Blood Group attributes). - Floating Desktop & Mobile Sidebar Auth Buttons: Added a floating action button for desktop viewports (
#desktop-auth-btn) and a dedicated button at the bottom of the mobile sidebar drawer (#mobile-auth-btn). Both dynamically toggle from "Login" to "Dashboard" with member avatar and role badges upon authentication. - Form Modal for Proposing & Updating Events: Implemented
#event-form-modalfor authenticated members to submit new events or propose updates to existingraids.jsonentries (supporting title, dates, deadlines, venues, fee, descriptions, dynamic sub-events repeaters, and links). - In-Card Suggest Edit Controls: Dynamically injected a "✏️ Edit" button onto each raid card summary for logged-in users, pre-populating the proposal modal with the clicked raid's full dataset for instant editing.
- Staff Review Dashboard Console: Built
#review-dashboard-modalrestricted to Admins and Moderators. Displays pending submissions with submitter metadata, side-by-side visual diff comparisons, and one-click Approve/Reject actions with optional feedback notes. - Raids JSON Export & Sync Engine: Integrated single-click "Download raids.json" and "Copy JSON" tools in the Review Dashboard to compile and export approved proposals ready for git commit.
- Admin Moderator Management: Developed
#mod-management-modalallowing Guild Admins to query registered community members and appoint or revoke Moderator roles (event_roles). - Database Migration Schema: Created
doc/db/event_raids_schema.sqldefiningpublic.event_rolesandpublic.event_submissionstables with Row Level Security (RLS) policies and security-definer helper functions.
- Central Database User Management: Connected the portal to the central Supabase database (
- Features:
- Live RSS 2.0 Syndication Feed: Generated
feed.xmladhering to RSS 2.0 and Atom standards to broadcast active campaigns across external platforms. - Automated Generator Script: Built
.github/scripts/generate-rss.jsto dynamically filter active events, build CDATA-encapsulated HTML descriptions (sub-events, fees, venues, deadlines), and compile RFC 822 publication dates. - HTML Auto-Discovery Tag: Integrated
<link rel="alternate" type="application/rss+xml" ...>intoindex.htmlheader for seamless reader client detection. - Automated Workflow Synchronization: Extended
.github/workflows/notify.ymlto automatically executegenerate-rss.jsand commitfeed.xmlon data changes and daily cron cycles. - b1t-Sched Integration Architecture: Documented step-by-step native JSON and RSS parsing guides for integrating Raider events into the
b1t-Scheddashboard sidebar.
- Live RSS 2.0 Syndication Feed: Generated
- Features:
- Venue Location Metadata Schema: Introduced
"OutsideDhaka","IsOnline", and"city"fields inraids.jsonto classify physical venue locations and online events. - Dynamic OutsideDhaka Map Badge: Created an interactive location badge for outside-Dhaka events cycling every 2 seconds between
Dhakaand borderless/backgroundless📍(icon only), opening the venue on Google Maps in a new tab when clicked. - Static Borderless Location Badge for Dhaka Venues: Rendered a static borderless/backgroundless
📍location pin icon linked to Google Maps for physical Dhaka events ("OutsideDhaka": false). - Protruding Copy Button: Relocated copy raid link button to
<summary>protruding outside top-right corner (top: -10px; right: -10px) for permanent visibility regardless of card collapse state.
- Venue Location Metadata Schema: Introduced
- Features:
- Past Raids Visibility Toggle: Past campaigns are hidden by default (
showPastRaids = false). Added#toggle-past-raids-btnand viewport-tracking#floating-past-raids-btnto toggle past campaigns visibility on demand. - Deep-Link Auto-Unhide: Direct navigation to past raid URLs (e.g.
#raid-1) automatically unhides past raids and updates toggle button states. - Parent Collapsible Raid Cards: Refactored raid cards into native
<details class="raid-card parent-raid-card">structures. Summary view displays"dateRange","Type","Status","title", copy button, and chevron; expanding reveals full event specifications, schedule drawers, and resources. Auto-expands (open = true) upon deep-link navigation. - Past Calendar Date Cell Graying: Date cells in the calendar view containing past-only campaigns are rendered in grayed-out muted tones (
.past-only), while multi-event dates with active events preserve vibrant highlight styles. All click interactions remain active. - Floating Action Stack: Stacked
#floating-past-raids-btnabove#floating-calendar-btnat the bottom-right corner withIntersectionObserverscroll visibility and dual-button state synchronization. - Mobile Icon-Only Past Raids Button: Configured
#toggle-past-raids-btnto display as a compact centered icon button on mobile viewports while preserving text labels for Calendar and Event Type controls.
- Past Raids Visibility Toggle: Past campaigns are hidden by default (
- Features:
- Central Database Integration: Connected
eventsto the centralized Supabase instance (ou1ts.github.io) usingenv-config.jsand@supabase/supabase-js. - Google OAuth Sign-In: Integrated one-click Google OAuth via
supabaseClient.auth.signInWithOAuth({ provider: 'google' })with automatic token/code URL cleanup, profile picture rendering in dashboard, and file protocol guard. - Responsive Auth Controls: Desktop floating pill button (
#desktop-auth-btn) positioned bottom-left; Mobile sidebar button (#mobile-auth-btn) pinned at the very bottom of#main-nav. State automatically switches between "Login" and "Dashboard" upon sign-in/out. - Event Proposal & Edit Form: Modal
#event-form-modalallows logged-in members to propose new events or click the in-card "✏️ Edit" button on any raid card to submit proposed updates with custom sub-events and links. - Review Dashboard Modal (
#review-dashboard-modal): Accessible exclusively by guild Admins and Moderators. Features side-by-side diff viewers showing proposed vs current values, status filtering tabs (Pending, Approved, Rejected), one-click approval/rejection with reviewer notes, and export tools (Download raids.json&Copy JSON). - Moderator Management Console (
#mod-management-modal): Admin-only modal to search all logged-in community members and appoint or revoke moderator roles dynamically inpublic.event_roles. - Database Schema & RLS: Created
doc/db/event_raids_schema.sqldefiningpublic.event_rolesandpublic.event_submissionswith Row Level Security policies and helper functions (is_event_admin(),is_event_staff()).
- Central Database Integration: Connected
- Features:
- Local Caching Registry: Added
tracker.jsonto monitor total event count and tracking deadlines.app.jsruns a cache-first validation engine checking remote state using{ cache: 'no-cache' }and flushing staleraids.jsoncache parameters asynchronously when new events are pushed. - Registration Deadline Alerts: Added check logic exactly 1 day prior to upcoming registration end dates, displaying system push notifications and custom on-screen glassmorphic UI toast alerts. Prevents redundant notifications via
localStoragetoken flags. - OneSignal Web Push Integration: Configured OneSignal page SDK block in
index.htmland service workerOneSignalSDKWorker.jsat root. - Automated GHA Workflows: Added a Node.js dispatch script (
.github/scripts/send-push.js) executing on pushes (new raid dispatches) or cron schedule (0 6 * * *daily deadline checks), making POST requests to OneSignal REST API and committing tracker sync updates back to git.
- Local Caching Registry: Added
- Features & Bugfixes:
- Optimized Mobile Button Sizing: Reduced padding, font size, and gap on the Calendar and Event Type filter buttons on mobile viewports to prevent layout overflow.
- Hiding Mobile Descriptions: Hidden the
#raidssection description on mobile viewports to maximize vertical scrolling area. - Restored Native Momentum Scrolling: Removed the custom JS swipe/scroll multiplier (
initMobileScrollMultiplier) to eliminate scrolling lag and stutter on mobile touch screens, returning scroll control fully to native browser momentum engines.
- Features:
- Event Type Metadata & Tags: Added a
"Type"field to the JSON schema. Renders a category pill tag (.raid-type-tag) at the top of each campaign card. - Registration Deadline Display: Introduced a
"RegEndDate"field. Uses a dynamic formatter to display readable deadlines. Compares against system time to display red/gray(Closed)tags or green active deadlines inside details drawers. - Custom Dropdown Filter: Built a custom filter dropdown menu containing preset event categories next to the calendar button. Selecting a type instantly filters visible campaigns.
- Narrow Breakpoint Row Wrapping: Standardized styling so both buttons align on a single row down to a very narrow mobile screen size of
380px, where they stack vertically. - Routing Resets: Programmed SPA hash routing to reset active filters to "All Types" whenever deep links (e.g.
#raid-3) are resolved, preventing target element resolution failures. - Event Notes Section: Added a new SPA page section (
#notes) that dynamically queries all event notes listings fromraids.jsonand renders interactive cards, linking them to local markdown pages and deep-linking back to their Campaign Roadmap cards. - Same-Tab Note Links: Configured all local
"notes"links to open in the same tab so that the back button inside the markdown renderer correctly returns the user to the portal without leaving residual tabs open.
- Event Type Metadata & Tags: Added a
- Features:
- Interactive Campaign Calendar: Built a month-by-month square calendar view that retrieves event
"startDate"values. Highlights active days and features previous/next navigation. - Event Overlap Counter: Renders a badge indicating event counts on days where multiple events start simultaneously (e.g. July 10).
- Direct Redirection Overlay: Implemented a slide-up vertical list overlay within the calendar. Clicking event items automatically redirects the user to the corresponding card layout with highlights.
- Body-Root Modal Positioning: Fixed scroll viewport-centering by positioning the modal at the root level of
<body>, isolating it from layout translations. - Dedicated Floating Button: Added an icon-only circular floating calendar button at the viewport corner that is controlled by an
IntersectionObservertracking the inline button's scroll state. - Mobile Spacing Optimization: Compressed card padding (
1.15rem), grid gaps (1rem), and header typography on mobile to fit more cards and reduce vertical scrolling height. - Velo-Boost Scroll Multiplier: Added flick gesture recognition on touchscreens that adds smooth, velocity-proportional scrolling offsets to enhance mobile traversal speed.
- Interactive Campaign Calendar: Built a month-by-month square calendar view that retrieves event
- Features:
- Deep Linking to Raids: Extended SPA hash routing to support
#raid-<number>paths. The portal auto-routes to "Raid Campaigns", smooth-scrolls to the target card, and triggers a highlight effect. - Copy Link Button: Added a dedicated copy icon button next to the status badge on each card. Clicking copies the direct deep link (e.g.
index.html#raid-1) to the user's clipboard. - Interactive Feedback: Implemented visual success state where the copy icon turns into a checkmark for 2 seconds.
- Highlight Pulse Animation: Created
@keyframes highlightPulseto animate the border-color and box-shadow with the theme-specific accent color glow upon deep-link activation. - Data Layer Variables: Added sequential
"Raid_Num"properties to all objects inraids.jsonmatching card positions.
- Deep Linking to Raids: Extended SPA hash routing to support
- Features:
- Collapsible Details: Wrapped Venue, Fee, and subEvents (Schedule) inside a single premium-styled, collapsible
<details>element labeled "Details". Styled it with dynamic theme-accented borders, custom carets, left-side indicator bars, and hover scaling. - Raid Roadmap Context: Updated the main portal context from "Past Raids" to "Raid Campaigns" and changed the hero CTA button to "View Raid Plans".
- Dynamic Status Badges: Added
"Status"and"endDate"tags toraids.json. Implemented dynamic status checks inapp.jsthat automatically shift status from"Future"to"Past"once the current date passesendDate, rendering matching badge chips. - Mobile Layout Polish: Decreased title size on mobile viewports to
1.3rem, placed the main description above the Details dropdown, and added a line-clamped description box with a highlighted See More toggle button for screens< 768px. - Tab Behaviors: Standardized target attributes so all links in
raids.json(including the local"notes"markdown rendering link) open in a new browser tab.
- Collapsible Details: Wrapped Venue, Fee, and subEvents (Schedule) inside a single premium-styled, collapsible
- Features:
- Integrated a local Markdown reader (
render.html,render.js, andcss/render.css) into the workspace to view campaign reports locally. - Added a
syncThememethod torender.jsto automatically match the viewer's theme with the homepage choice saved inlocalStorage. - Created
doc/notes/phoenix-summit-2026.mdcontaining safety guidelines, session advice, and delegation schedules. - Integrated
"notes"key underraids.jsonlink listings, mapping to local documents and rendering them insiderender.htmlwith a sheet document icon.
- Integrated a local Markdown reader (
- Features:
- Refactored
subEventsinraids.jsonfrom a flat string into a reusable array of collapsible summary/detail items. - Added HTML
<details>rendering template inapp.jsto support multi-day schedule drawers. - Styled details drawers in
style.csswith transition controls and custom rotation arrows. - Fixed line breaks not rendering in
"fee"metadata values by mapping.raid-info-valuetowhite-space: pre-linein CSS.
- Refactored
- Features:
- Updated
raids.jsonto feature the Phoenix Summit 2026 as the flagship event. - Populated the file with detailed pricing data (Student Conference/Workshop rates, Regular Passes, and Early Birds) and schedules.
- Updated
- Features:
- Established index.html markup featuring Home, Past Raids, Join Us, and Learn More tabs.
- Implemented responsive mobile-first grids, custom navigation animations, and slide-in hamburger headers.
- Created theme toggle controls with a Gold/Silver dark mode palette and sky-blue light mode palette.
- Separated data into a mock list inside
raids.json.