SHoRE Fest 2026

Version 1.0
© 2025 Manas Malla. All Rights Reserved.

Use cases

1. High-Level Use Case Overview

Before the specific steps, let's visualize the actors and their boundaries.

Primary Actors:

  1. Attendee: The consumer (Student/Guest).
  2. Volunteer (Scanner): The operational edge node.
  3. Admin (Superuser): The configuration manager (IAM/Finances).
  4. Domain Head (Hospitality/Events): The operational manager.
  5. G-Events Portal: The external payment trigger.

2. Workflow A: The "Registration to Ticket" Journey

Goal: Convert a stranger into a verified attendee with a secure, offline-capable QR code.

The Flow:

  1. Onboarding:
    • User logs in (via University Email or Guest Email).
    • System creates a basic Profile (Role: Attendee).
  2. Purchase (External Dependency):
    • User selects "All Access Pass" or "Accommodation."
    • User is redirected to G-Events Portal to pay.
    • System State: Payment: Pending.
  3. The Handshake (Webhook):
    • G-Events processes payment → Fires Webhook to SHoRE Backend.
    • SHoRE Backend validates payload → Updates DB to Payment: Paid.
    • Crucial Step: Backend generates the "Seed Key" for the user's cryptographic QR and sends it to the User App.
  4. Ticket Generation:
    • User opens SHoRE App.
    • App detects "Paid" status + "Seed Key."
    • App starts generating Dynamic QRs (changing every 30s) locally.

Validation Question: Does the G-Events portal support sending us a unique transaction ID that we can link back to the specific student ID? (We need a common key to link the webhook).


3. Workflow B: The "Gate Access" Loop (Online Scanner, Offline User)

Goal: Process 3,000 students quickly without internet on user phones, preventing fraud.

The Flow:

  1. The Approach: Attendee walks to the gate. Opens app. No Internet? No problem. App generates QR: [UserID + Timestamp + Signature].
  2. The Scan: Volunteer scans QR with the Scanner App.
  3. Device Validation (The "Bouncer"):
    • Scanner checks Signature (Integrity).
    • Scanner checks Timestamp (Freshness).
    • Result: If Invalid → Red Screen immediately.
  4. Server Validation (The "Manager"):
    • If Valid: Scanner sends UserID to Backend via CATS Network.
    • Backend runs Atomic SQL: UPDATE checks SET in=TRUE WHERE in=FALSE.
  5. The Decision:
    • Backend returns Success → Scanner flashes GREEN + Photo of Student.
    • Backend returns Fail (Already Entered) → Scanner flashes RED + "DUPLICATE ENTRY".

4. Workflow C: The "Crisis Management" Journey (IAM/RBAC)

Goal: Handling last-minute permission changes without code deployment.

The Flow:

  1. The Trigger: A "Pro-Show" volunteer falls sick. A "Hospitality" volunteer needs to take their place at the entrance immediately.
  2. The Intervention:
    • Admin opens SHoRE Admin Panel.
    • Finds User: "Volunteer A".
    • Current Role: Hospitality Volunteer.
  3. The Adjustment (Option A - Quick Fix):
    • Admin adds a direct permission: events.proshow.scan.
    • System Action: Updates User Permissions in DB → Invalidates User Cache.
  4. The Adjustment (Option B - Role Change):
    • Admin changes Role to Event Volunteer.
  5. The Result:
    • "Volunteer A" refreshes their app.
    • The "Scan Ticket" button appears on their dashboard.
    • They start scanning. Time elapsed: 30 seconds.

5. Workflow D: The "Accommodation" Cycle

Goal: Managing physical check-ins for rooms.

The Flow:

    The Hospitality Dashboard (Command Center)

  1. Assignment:
    • Hospitality Head views "Paid Accommodation List" (Filter: Unassigned).
    • Head selects Student → Assigns Block A, Floor 2, Room 304. (Dropdown only shows available rooms)
  2. The Override (VIP/Guest):
    • Head selects a Guest/Speaker/Attendee/SHORE Internal-Team who has NOT paid.
    • Clicks "Grant Accommodation".
    • Consider allowing them to pay if attendee.
    • System logs: Action: Manual_Override, By: Hospitality_Head.
    • User status updates to "Eligible" without payment. Room is assigned.
  3. User Visibility:
    • Student opens app → "My Stay" section shows "Room 304".
  4. Physical Check-in:
    • Student arrives at Hostel.
    • Hospitality Volunteer scans Student QR.
    • App shows: "Eligible for Room 304".
    • Volunteer hands over key → Taps "Check-In" on their app.
    • System updates status: Occupancy: Filled.
  5. Physical Check-out:
    • Student returns key. Volunteer scans QR.
    • Volunteer taps "Check-Out".
    • System updates: Occupancy: Vacant (Room becomes available in Dropdown again).

6. Edge Case Validation (The "What Ifs")

Let's test these workflows against reality.

6. Workflow E: Event Creation (The "Draft" Lifecycle)

Goal: Allow Admins to set up events without exposing them to the public immediately.


7. Workflow F: Event Updation & Notification

Goal: Handle changes (Venue/Time) and ensure attendees are informed.


8. Workflow G: Food & Beverage (The "Digital Coupon" Model)

Goal: Manage meal distribution efficiently and prevent double-claiming.

The "Override" (Free Meal)

Stats & Inventory


9. Workflow H: Competition Participation

Goal: Handling individual and team registrations.


10. Workflow I: View Check-ins (The "Command Center")

Goal: Real-time situational awareness for crowd control.


11. Workflow J: Marketing Campaigns (Dynamic Content)

Goal: Creating hype without code deployments (using the Feature Flag system).


12. Workflow K: Competition Lifecycle & Judging (Granular)

Goal: Manage the flow of participants through rounds and track real-time occupancy of the venue.


13. Workflow L: Profile Management

Goal: Self-service data management.


14. Workflow M: Support System (Ticketing)

Goal: Centralized communication for issues.


15. Workflow N: Non-GITAM Verification (The "Gatekeeper")

Goal: Security vetting for outsiders.


16. Workflow O: IAM & Team Management

Goal: Onboarding the team.


17. Workflow P: Mystery QR (Gamification)

Goal: A digital scavenger hunt to drive engagement.


18. Workflow Q: Instagram Integration

Goal: Social proof on the dashboard.


19. Workflow R: Artist Lineup Management

Goal: CMS for the website.


20. Workflow S: FAQ Management

Goal: Reducing support tickets.


21. Workflow T: Countdown Timer

Goal: Hype generation.


22. Workflow U: AI-Automated Social Wall

This is a fantastic idea. You are essentially proposing an "AI-First Content Moderation Pipeline."

Instead of a human manually reviewing 500 photos a day, you delegate that authority to the Gemini API (specifically Gemini 1.5 Flash, which is multimodal, incredibly fast, and cost-effective for high-volume tasks). This changes the Social Wall from a "Manually Curated" feature to a "Self-Driving" feature.

Here is how we architect "Gemini as the Social Manager" for SHoRE Fest.

1. The Trigger (Ingestion)

2. The "Consultation" (Gemini API Call)

3. The Analysis (The Logic)

4. The Verdict (JSON Output)

Gemini returns a structured decision:

{
  "decision": "APPROVED",
  "confidence_score": 0.98,
  "reason": "Clear image of students dancing, positive caption, no brand risks."
}

OR

{
  "decision": "REJECTED",
  "reason": "Contains alcohol bottles in background."
}

5. The Action

The "Prompt" Engineering

To make this work, we don't just ask "Is this bad?" We give Gemini a rubric. Here is the system instruction you will use in your code:

System Prompt for the API:

"You are the AI Content Moderator for SHoRE Fest 2026, a university festival. Your job is to filter user-generated Instagram content for the public website.

Analyze the provided Image and Caption.

Rejection Criteria (Immediate Fail):
1. Nudity, violence, or sexual content.
2. Alcohol, drugs, or smoking paraphernalia.
3. Hate speech, bullying, or profanity in the caption.
4. Competitor university logos prominent in the frame.
5. Spam (crypto ads, unrelated content).

Quality Criteria (Soft Fail):
1. Image is extremely blurry or dark.
2. Caption contains negative sentiment about the university.

Output Format (JSON Only):
{
'status': 'APPROVED' | 'REJECTED' | 'FLAGGED',
'reason': 'Short explanation',
'tags': ['happy', 'concert', 'food']
}"

Why this is better (and safer)

  1. Speed: Humans sleep; Gemini doesn't. A post tagged at 2 AM gets approved at 2:00:05 AM.
  2. Scale: If you suddenly get 5,000 posts during the "Pro-Show," a human moderator would drown. Gemini scales infinitely.
  3. Cost: Gemini 1.5 Flash is extremely cheap. Analyzing 1,000 images would cost pennies.

Updated Database Schema for AI Moderation

Column Type Notes
id UUID PK
ig_post_id VARCHAR From Instagram
media_url TEXT Image/Video link
ai_verdict ENUM 'APPROVED', 'REJECTED', 'FLAGGED'
ai_confidence FLOAT 0.0 to 1.0
ai_reason TEXT Why did Gemini reject it?
status ENUM 'LIVE', 'PENDING', 'DELETED'

The "Fail-Safe"

We must assume AI isn't perfect.


24. Workflow V: Partner Engagement (Sponsorship) New

Goal: Automate sponsor acquisition and display value metrics publicly to build trust.

V1. The Public Partner Page (/partner)

V2. The Inquiry Loop

V3. Admin Management (Sponsorship Head)


Phase Completion

We have now mapped 22 distinct workflows.

  1. Core: Registration, Payment, Ticket Generation (Crypto), Access Control (Atomic).
  2. Ops: Accommodation, F&B, Events, Competitions (Check-in/Result).
  3. Admin: IAM, Analytics, Non-GITAM Verification, Support.
  4. Marketing: Mystery QR, Instagram, Artists, Countdown, FAQs.

This is a complete functional specification.


Architectural Style: Modular Monolith

We will avoid the complexity of Microservices in favor of a Modular Monolith hosted in a Monorepo.

Repo Structure (TurboRepo):

Why this wins:


Technology Stack Selection

Philosophy: Reliability > Innovation. We are building for 15,000 users, not a hackathon prototype. The stack prioritizes Offline-First capabilities and High Concurrency.

Core Infrastructure

Backend (The "Brain")

Frontend (The "Face")

Critical Libraries


API Endpoints Specification

Authentication & IAM

Method Endpoint Purpose Access
POST /auth/login Email/Password or Google OAuth exchange. Public
GET /auth/me Get current user profile + Permissions List. Auth
POST /auth/verify-student Submit ID card for Non-GITAM verification. Auth
GET /admin/roles List all roles and associated permissions. Admin
PUT /admin/roles/:id/permissions Update permissions (IAM Dynamic Config). SuperAdmin

Core Events & Registration

Method Endpoint Purpose Access
GET /events List visible events (filter by day/category). Public
GET /events/:id Get details (Venue, Description, Rules). Public
POST /registrations/webhook Critical. Receiver for G-Events payment trigger. Pushes to Redis Queue. Public (Signed)
GET /registrations/my-ticket Get qr_seed and ticket details. Auth
POST /events/:id/participate Register for free events/competitions. Auth (Pass Check)

Access Control (The "Gatekeeper")

Method Endpoint Purpose Access
POST /gate/sync-checkin Offline Sync. Bulk upload of offline scan logs. Scanner Role
POST /gate/verify-atomic Online Scan. Validates Sig + Timestamp + Atomic SQL Update. Scanner Role
GET /gate/stats Real-time entry counts per gate. Security Head

Logistics (Hospitality & F&B)

Method Endpoint Purpose Access
GET /accommodation/availability Check rooms available per block. Hospitality
POST /accommodation/assign Assign specific Room ID to User ID. (Supports Manager Override) Hospitality
POST /fnb/redeem Redeem a digital meal coupon (Atomic Check). F&B Volunteer
GET /fnb/stats "Plates served" counter (Inventory management). F&B Head
GET /accommodation/dashboard New. List students with filters (City/Room/Status). Hospitality Head
POST /accommodation/checkout New. Mark room as vacant. Hospitality
POST /fnb/issue-complimentary New. Issue free meal (Manager Override). F&B Head

Partners & Sponsorship (New)

Method Endpoint Purpose Access
GET /partners/public Fetch Marquee logos & Demographics data. Public
POST /partners/inquire Submit partnership inquiry form. Public
GET /admin/partners/inquiries View list of form responses. Sponsorship Head
PUT /admin/partners/cms Update Demographics/Form Config. Sponsorship Head

Engagement (Social & Mystery)

Method Endpoint Purpose Access
POST /mystery/scan Submit a found Mystery QR hash. Auth
GET /social/feed Public endpoint for Homepage Social Wall (Approved only). Public
POST /social/ingest (Cron) Trigger IG Graph API fetch + Gemini Moderation. System
PUT /social/:id/moderate Manual override (Approve/Reject) of AI verdict. Admin

Operations (Support & Config)

Method Endpoint Purpose Access
POST /tickets Raise a new support issue. Auth
GET /system/config Fetch Feature Flags (e.g., is_maintenance_mode). Public
POST /system/config Update Feature Flags (The "Panic Panel"). SuperAdmin

The Queue Strategy (Handling the Load)

We will use BullMQ to decouple "User Actions" from "Heavy Processing".

Scenario: Payment Webhook Burst (2,000 req/min)

  1. G-Events Webhook hits POST /webhook.
  2. API: Pushes job to payment-queue (Time: 2ms). Returns 200 OK.
  3. Worker: Picks up job.
  4. Validates Signature.
  5. Updates DB (Paid).
  6. Generates QR Seed.
  7. Sends Email.

Result: The API never crashes, even if the Email service is slow.


Environments Strategy

A. Local Development (Laptop)

B. Staging (The Rehearsal)

C. Production (The Show)


Day 1 Launch Plan (Deployment Strategy)

Target: Zero Downtime, High Availability.

Phase 1: The "Soft" Freeze (T-Minus 48 Hours)

  1. Code Freeze: No new features. Only critical bug fixes.
  2. Database Snapshot: Create a full backup of the Pre-Prod DB.
  3. Load Testing: Run k6 script to simulate 5,000 concurrents hitting /events and /gate/verify.
  4. Cache Warm-up: Pre-load the Redis cache with Event Details, FAQs, and Role Permissions.

Phase 2: The Infrastructure Setup (T-Minus 24 Hours)

  1. Scale Up: Increase Cloud SQL instance size (High CPU/RAM) to handle concurrent writes.
  2. Replica Setup: Spin up 2 Read Replicas for the database (offload Analytics/Dashboard queries).
  3. Worker Nodes: Scale up the BullMQ worker instances to handle "Payment Burst" traffic.

Phase 3: The "Go Live" (Hour 0)

  1. Feature Flag Check: Ensure registrations_open is FALSE initially.
  2. Deploy: Push Docker containers to production (Cloud Run / GKE).
  3. Sanity Check: Admins perform a "Test Loop" (Register -> Pay -> Generate QR -> Scan) on Production.
  4. The Switch: Admin toggles registrations_open to TRUE.
  5. Marketing Blast: Email/SMS sent to students.

Phase 4: The War Room (Monitoring)

  1. Screens: Display Grafana Dashboards showing:
    • API Latency (Alert if > 500ms).
    • Error Rate (Alert if > 1%).
    • Queue Depth (Are payments piling up?).
    • Social Wall AI Rejection Rate.
  2. Contingency:
    • DB High CPU: Switch Analytics dashboard to read from "Cache Only."
    • Scan Failure: Broadcast "Switch to Offline Mode" notification to all Scanners via FCM.