Use cases
1. High-Level Use Case Overview
Before the specific steps, let's visualize the actors and their boundaries.
Primary Actors:
- Attendee: The consumer (Student/Guest).
- Volunteer (Scanner): The operational edge node.
- Admin (Superuser): The configuration manager (IAM/Finances).
- Domain Head (Hospitality/Events): The operational manager.
- 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:
- Onboarding:
- User logs in (via University Email or Guest Email).
- System creates a basic Profile (Role:
Attendee).
- Purchase (External Dependency):
- User selects "All Access Pass" or "Accommodation."
- User is redirected to G-Events Portal to pay.
- System State:
Payment: Pending.
- 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.
- 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:
- The Approach: Attendee walks to the gate. Opens app. No Internet? No problem. App generates QR:
[UserID + Timestamp + Signature]. - The Scan: Volunteer scans QR with the Scanner App.
- Device Validation (The "Bouncer"):
- Scanner checks Signature (Integrity).
- Scanner checks Timestamp (Freshness).
- Result: If Invalid → Red Screen immediately.
- Server Validation (The "Manager"):
- If Valid: Scanner sends
UserIDto Backend via CATS Network. - Backend runs Atomic SQL:
UPDATE checks SET in=TRUE WHERE in=FALSE.
- If Valid: Scanner sends
- The Decision:
- Backend returns
Success→ Scanner flashes GREEN + Photo of Student. - Backend returns
Fail(Already Entered) → Scanner flashes RED + "DUPLICATE ENTRY".
- Backend returns
4. Workflow C: The "Crisis Management" Journey (IAM/RBAC)
Goal: Handling last-minute permission changes without code deployment.
The Flow:
- The Trigger: A "Pro-Show" volunteer falls sick. A "Hospitality" volunteer needs to take their place at the entrance immediately.
- The Intervention:
- Admin opens SHoRE Admin Panel.
- Finds User: "Volunteer A".
- Current Role:
Hospitality Volunteer.
- The Adjustment (Option A - Quick Fix):
- Admin adds a direct permission:
events.proshow.scan. - System Action: Updates User Permissions in DB → Invalidates User Cache.
- Admin adds a direct permission:
- The Adjustment (Option B - Role Change):
- Admin changes Role to
Event Volunteer.
- Admin changes Role to
- 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:
- Actors: Hospitality Head/Lead.
- The View:
- Head opens "Accommodation Dashboard".
- Stats Widget: Shows "Accommodation provided: 240/500", "Rooms Filled: 120/500", "Available in Block A: 45".
- Grid View: Lists all registered students.
- Filtering & Sorting:
- Filters list by:
Name, Phone, City, Email, Year, Male/Female, SHORE Internal-Team/Attendee. - Can also filter by inventory:
Floor,Room.
- Filters list by:
- Venue Management:
- Head/Lead views "Venue Inventory".
- Head can add new venues, update existing venues, and delete venues.
- Assignment:
- Hospitality Head views "Paid Accommodation List" (Filter: Unassigned).
- Head selects Student → Assigns
Block A, Floor 2, Room 304. (Dropdown only shows available rooms)
- 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.
- User Visibility:
- Student opens app → "My Stay" section shows "Room 304".
- 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.
- Physical Check-out:
- Student returns key. Volunteer scans QR.
- Volunteer taps "Check-Out".
- System updates:
Occupancy: Vacant(Room becomes available in Dropdown again).
The Hospitality Dashboard (Command Center)
6. Edge Case Validation (The "What Ifs")
Let's test these workflows against reality.
- Scenario 1: The G-Events Webhook fails (server busy).
- Fix: We need a "Reconcile" button in the Admin Panel that allows us to upload a CSV from G-Events and manually mark users as "Paid."
- Scenario 2: Scanner loses CATS Network connectivity.
- Fix: Scanner switches to "Offline Mode." Validates Crypto Signature only. Queues the "Check-in" data. Syncs when network returns. (Risk: Replay attack possible, but low probability in short window).
- Scenario 3: User phone battery dies.
- Fix: "Manual Entry" mode. Volunteer types Student ID/Email. System pulls up Photo. Volunteer verifies face → Checks in manually.
6. Workflow E: Event Creation (The "Draft" Lifecycle)
Goal: Allow Admins to set up events without exposing them to the public immediately.
- Actors: Admin / Event Head.
- IAM Permission:
event.create. - The Flow:
- Drafting:
- Admin enters details: Title, Description, Venue, Capacity, Time.
- Crucial Step: Admin selects "Access Rule" (e.g., "Open to All" vs. "Pro-Pass Only").
- System saves as
Status: Draft. (Not visible in the App).
- Review (Optional):
- Admin reviews the draft.
- Publishing:
- Admin clicks "Publish."
- System updates status to
Status: Live. - Event becomes visible on the Website/App API.
- Drafting:
7. Workflow F: Event Updation & Notification
Goal: Handle changes (Venue/Time) and ensure attendees are informed.
- Actors: Admin / Event Head.
- IAM Permission:
event.update. - The Flow:
- The Change:
- Head changes Venue from "Auditorium" to "Open Air Theater."
- The Audit:
- System logs:
User: Event_Head changed Venue ID 101.
- System logs:
- The Trigger:
- Admin checks a box: "Notify Registered Attendees?"
- The Broadcast:
- If checked, System triggers a Push Notification/Email job via a background worker (Queue) to all users registered for that specific event.
- "Alert: Venue for 'Battle of Bands' changed to OAT."
- The Change:
8. Workflow G: Food & Beverage (The "Digital Coupon" Model)
Goal: Manage meal distribution efficiently and prevent double-claiming.
- Actors: Attendee, F&B Volunteer.
- Prerequisite: User purchased "Hospitality Pack" (via G-Events).
- The Flow:
- Entitlement:
- User profile has a ledger:
{ "Day1_Lunch": 1, "Day1_Dinner": 1 }.
- User profile has a ledger:
- The Exchange:
- User arrives at the Food Counter.
- Volunteer selects "Day 1 Lunch" mode on Scanner.
- The Validation (Strictly Online/CATS Network):
- Volunteer scans User QR.
- Atomic SQL Check:
UPDATE user_entitlements SET claimed = TRUE, claimed_at = NOW() WHERE user_id = '123' AND item = 'Day1_Lunch' AND claimed = FALSE;
- The Feedback:
- Success (Rows=1): Green Screen. Volunteer hands over the plate.
- Fail (Rows=0): Red Screen ("Already Ate").
- Entitlement:
The "Override" (Free Meal)
- Scenario: A Guest Lecturer/Sponsor/SHORE Internal team/Attendee needs lunch but has no ticket.
- Action: Hospitality Lead switches Scanner to "Manager Mode".
- The Flow:
- Lead scans Guest QR.
- App detects "No Entitlement".
- Lead clicks "Issue Complimentary Meal".
- System logs:
Meal: Issued,Reason: Manager_Override. - Green Screen appears.
Stats & Inventory
- Dashboard: F&B Head views "Live Consumption Stats".
- Data Points: "Day 1 Lunch: 1,240 Served".
- Benefit: Helps kitchen team manage replenishment.
9. Workflow H: Competition Participation
Goal: Handling individual and team registrations.
- Actors: Attendee.
- The Flow:
- Discovery: User views "Hackathon" event page.
- Eligibility Check:
- User clicks "Register."
- System checks: Does User have the required Pass (e.g., Pro Pass)?
- Team Logic (If applicable):
- Scenario A (Individual): System adds user to
event_participantstable. - Scenario B (Team Leader): User creates a Team Name → Generates a "Team Code."
- Scenario C (Team Member): User enters "Team Code" to join.
- Scenario A (Individual): System adds user to
- Confirmation:
- User receives a "Registered" badge on the event card.
10. Workflow I: View Check-ins (The "Command Center")
Goal: Real-time situational awareness for crowd control.
- Actors: Admin, Security Head.
- IAM Permission:
analytics.view. - The Flow:
- Dashboard Load:
- Admin opens "Live Stats."
- Data Aggregation (Cached):
- Backend queries the
registrationsandevent_logstables. - Optimization: Use a Redis counter that increments on every scan to avoid heavy SQL
COUNT(*)queries every second.
- Backend queries the
- Visualization:
- Heatmap: Shows which Gate/Venue has high traffic.
- Demographics: "1,200 GITAM Students" vs "300 Non-GITAM."
- Time Series: "Entries per minute" (Detects rush hours).
- Drill Down:
- Click on "Pro-Show" → See list of currently checked-in users.
- Dashboard Load:
11. Workflow J: Marketing Campaigns (Dynamic Content)
Goal: Creating hype without code deployments (using the Feature Flag system).
- Actors: Marketing Head, Admin.
- IAM Permission:
marketing.config. - The Flow:
- Configuration:
- Marketing team designs a "Flash Sale Banner."
- Admin uploads image to storage.
- Activation:
- Admin goes to System Config in Admin Panel.
- Sets
promo_banner_active=TRUE. - Sets
promo_image_url=.../banner.jpg. - Sets
promo_link=.../register.
- User Experience:
- User refreshes the App/Website.
- The App checks the config API.
- The Banner appears dynamically on the Home Screen.
- Configuration:
12. Workflow K: Competition Lifecycle & Judging (Granular)
Goal: Manage the flow of participants through rounds and track real-time occupancy of the venue.
- Actors: Event Volunteer, Judge, Participant.
- The Flow:
- Venue Entry (Check-In):
- Volunteer scans Participant QR.
- System updates:
status: checked_in,location: room_101. - Dashboard Update: Event Head sees "50/60 Participants present."
- The Judging Round:
- Judge logs in (Role:
Judge). - Selects "Round 1".
- Participants are listed (filtered by
checked_in). - Judge enters score/notes → Submit.
- Judge logs in (Role:
- Result Notification:
- Event Head clicks "Publish Results."
- System calculates top scorers.
- Notification: Push notification sent to Winners: "You qualified for Round 2!"
- Status Update: Losers marked
status: eliminated.
- Venue Exit (Check-Out):
- Volunteer scans QR on exit.
- System updates:
location: null. (Crucial for knowing if a team is missing before their turn).
- Venue Entry (Check-In):
13. Workflow L: Profile Management
Goal: Self-service data management.
- Actors: User.
- The Flow:
- View: User sees "My Profile" (Name, ID, Photo).
- Update:
- User edits phone number or Instagram handle.
- Constraint: Critical fields (Name, University ID, Email) are Locked after initial verification to prevent identity swapping.
- To change locked fields, they must raise a Ticket (Workflow M).
- History: User views "My Registrations" (List of Paid Events).
14. Workflow M: Support System (Ticketing)
Goal: Centralized communication for issues.
- Actors: User, Admin.
- The Flow:
- Creation:
- User clicks "Help" → "Raise Issue."
- Selects Category: (Payment, Accommodation, App Bug).
- Writes description → Submit.
- Triage:
- Admin views "Open Tickets."
- Assigns to specific Lead (e.g., Finance Lead for payments).
- Resolution:
- Lead replies: "Fixed, please retry."
- Lead changes status:
Resolved.
- Feedback: User gets notified and can reopen if not satisfied.
- Creation:
15. Workflow N: Non-GITAM Verification (The "Gatekeeper")
Goal: Security vetting for outsiders.
- Actors: Non-GITAM User, Admin (Security Team).
- The Flow:
- Upload: User registers → Uploads Gov ID / College ID photo.
- Pending State: System locks QR generation. Status:
Verification Pending. - The Review:
- Admin views "Pending Queue."
- Admin compares Name on form vs. Name on ID Card.
- Action:
- Approve: Unlocks Payment/QR. Sends "Welcome" email.
- Reject: Sends email "ID unclear, please re-upload."
16. Workflow O: IAM & Team Management
Goal: Onboarding the team.
- Actors: Super Admin.
- The Flow:
- Invite: Admin enters email
new_lead@shore.in. Selects Role:Events Lead. - Onboarding:
- System sends Email Invite.
- User clicks link → Sets Password.
- Access: User logs in. The
permissionstable automatically loads the "Events Lead" capabilities. - Offboarding: Admin clicks "Deactivate." User session is killed immediately.
- Invite: Admin enters email
17. Workflow P: Mystery QR (Gamification)
Goal: A digital scavenger hunt to drive engagement.
- Actors: Attendee.
- The Setup:
- Marketing team prints 10 unique static QRs and hides them around campus.
- Database table
mystery_qrscontains the hashes of these codes.
- The Flow:
- Scan: User finds a hidden QR → Scans with SHoRE App.
- Validation:
- App sends Hash to Server.
- Server checks: "Has this user scanned this specific QR before?"
- Reward:
- If No:
User_Points += 50. Show "You found Clue #1!" - If Yes: Show "Already Collected."
- If No:
- Leaderboard: App displays "Top Hunters."
18. Workflow Q: Instagram Integration
Goal: Social proof on the dashboard.
- Actors: System (Cron Job), Marketing Head.
- The Flow:
- Connection: Admin authenticates with "Instagram Graph API."
- Sync (Background Job):
- Every 1 hour, server fetches:
Follower Count,Latest Post Likes,Hashtag Mentions.
- Every 1 hour, server fetches:
- Display:
- Admin Dashboard shows a "Social Reach" graph.
- Public Website shows: "Join our 10K+ Community!"
19. Workflow R: Artist Lineup Management
Goal: CMS for the website.
- Actors: Event Head.
- The Flow:
- Edit: Head opens "Artist Manager."
- Update:
- Uploads Photo of "Band X".
- Adds Bio, Instagram Link, Spotify Link.
- Publish:
- API endpoint
/api/artistsupdates. - Website/App reflects the new lineup immediately.
- API endpoint
20. Workflow S: FAQ Management
Goal: Reducing support tickets.
- Actors: Content Team.
- The Flow:
- Draft: Admin adds Question & Answer. Category: "Transport."
- Publish: Instant update to the
/api/faqendpoint. - View: Users search FAQs in the app.
21. Workflow T: Countdown Timer
Goal: Hype generation.
- Actors: Admin.
- The Flow:
- Config: Admin sets
event_start_timestampin System Config. - Sync: App fetches this timestamp on launch.
- Display: App calculates
Time Now - Start Timelocally and updates the ticker every second.
- Config: Admin sets
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)
- The backend fetches the latest 20 posts tagged
#shoremachaofrom Instagram.
2. The "Consultation" (Gemini API Call)
- Instead of saving these immediately to the DB, your server sends the Image and the Caption to Gemini.
- The Persona: We tell Gemini it is the "Chief Brand Safety Officer" for a University Festival.
3. The Analysis (The Logic)
- Gemini evaluates the post against strict "College Fest Guidelines":
- NSFW/Violence: (Built-in Safety Filters).
- Substance Abuse: (Alcohol, smoking, drugs - usually strict for colleges).
- Sentiment: Is this hate speech, sarcasm, or a complaint?
- Relevance: Is it actually about the fest, or just spam using the hashtag?
- Quality: Is the image too dark/blurry to look good on the homepage?
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
- High Confidence Approval (>0.9): Auto-publish (Status:
Live). - Rejection: Auto-delete.
- Unsure (0.5 - 0.9): Send to "Manual Review" queue for a human to check (Status:
Pending).
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)
- Speed: Humans sleep; Gemini doesn't. A post tagged at 2 AM gets approved at 2:00:05 AM.
- Scale: If you suddenly get 5,000 posts during the "Pro-Show," a human moderator would drown. Gemini scales infinitely.
- 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.
- The "Kill Switch": If a bad post does get through (AI hallucination), the Admin Panel must have a "Panic Delete" button that removes it instantly and bans that Instagram user handle from future auto-approvals.
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)
- Actors: Potential Sponsors, Sponsorship Team.
- Components:
- Marquee: A scrolling list of Past Sponsors (Logos fetched from DB).
- Demographics Board: Data visualization showing "Last Year's Footfall", "Student Demographics", and "Social Reach" to prove value.
- Deliverables: List of perks current sponsors get (Stalls, Branding, etc.).
V2. The Inquiry Loop
- Action: Partner clicks "Become a Sponsor".
- Input: Fills Contact Form (Company Name, POC, Budget, Expectations).
- Response:
- System saves inquiry to DB.
- System triggers Auto-Reply Email: "Thanks for reaching out! Our team will contact you shortly."
V3. Admin Management (Sponsorship Head)
- View Responses: Head opens Admin Panel → "Sponsorship Inquiries" to see list of interested brands.
- CMS Updates:
- Head can update the Demographics numbers (e.g., if footfall expectation increases).
- Head can update the Contact Form fields if requirements change.
- Head can upload new Sponsor Logos to the Marquee section.
Phase Completion
We have now mapped 22 distinct workflows.
- Core: Registration, Payment, Ticket Generation (Crypto), Access Control (Atomic).
- Ops: Accommodation, F&B, Events, Competitions (Check-in/Result).
- Admin: IAM, Analytics, Non-GITAM Verification, Support.
- 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):
apps/web: Next.js (Admin Dashboard + Public Website)apps/api: Express.Js (The Unified Backend)apps/scanner: Flutter (Mobile App)packages/db: Prisma Schema (Shared types)packages/ui: Shared Design System (Tailwind components)
Why this wins:
- Type Safety: We can share TypeScript interfaces between Backend and Frontend instantly.
- Scaling: We handle 15k users by adding more instances of apps/api behind a Load Balancer, not by splitting the code.
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
- Cloud Provider: Google Cloud Platform (GCP) (Leveraging existing familiarity).
- Database: PostgreSQL 16+ (Hosted on Cloud SQL).
Why: Relational integrity is non-negotiable for payments and room allocation. - Caching & Queues: Redis & BullMQ.
Usage:- Caching IAM permissions, counting live check-ins, holding webhook bursts.
- Handles payment bursts. Backed by Redis. Native to Node.
Backend (The "Brain")
- Runtime: Node.js (v20 LTS) with TypeScript.
- Framework: Express.js or NestJS (NestJS recommended for structured, enterprise-grade architecture).
- ORM: Prisma or Drizzle. (Prisma is safer for atomic transactions).
- AI Integration: Google GenAI SDK (Gemini 1.5 Flash).
Frontend (The "Face")
- Web Portal (Admin/User Dashboard): Next.js 14 (App Router).
Why: SEO for the public site, Server Components for the Admin dashboard performance. - Mobile Apps (Scanner & Attendee): Flutter.
Why: Superior access to native hardware (Camera/NFC) and better performance for the "Offline Crypto Engine" compared to React Native.
Critical Libraries
- Cryptography: libsodium or tweetnacl (for Ed25519 signing/verification).
- Queues: BullMQ (Redis-based job queue for handling payment webhooks).
- Validation: Zod (Runtime schema validation).
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)
- G-Events Webhook hits
POST /webhook. - API: Pushes job to payment-queue (Time: 2ms). Returns 200 OK.
- Worker: Picks up job.
- Validates Signature.
- Updates DB (Paid).
- Generates QR Seed.
- Sends Email.
Result: The API never crashes, even if the Email service is slow.
Environments Strategy
A. Local Development (Laptop)
- DB: Local Docker container.
- Data: Seeded with 10 fake users.
- Focus: Writing code.
B. Staging (The Rehearsal)
- URL: api-staging.shore.in
- DB: Cloud SQL (Staging Instance).
- Data: Anonymized copy of production data (or massive fake data).
- Purpose:
- Load Testing: We attack this env with scripts to break it.
- UAT: The Hospitality Head logs in here to "practice" assigning rooms.
C. Production (The Show)
- URL: api.shore.in
- DB: Cloud SQL (Production High-Availability Instance).
- Data: Real User Data.
- Constraint: Read-Only access for developers. No manual DB edits allowed.
Day 1 Launch Plan (Deployment Strategy)
Target: Zero Downtime, High Availability.
Phase 1: The "Soft" Freeze (T-Minus 48 Hours)
- Code Freeze: No new features. Only critical bug fixes.
- Database Snapshot: Create a full backup of the Pre-Prod DB.
- Load Testing: Run k6 script to simulate 5,000 concurrents hitting
/eventsand/gate/verify. - Cache Warm-up: Pre-load the Redis cache with Event Details, FAQs, and Role Permissions.
Phase 2: The Infrastructure Setup (T-Minus 24 Hours)
- Scale Up: Increase Cloud SQL instance size (High CPU/RAM) to handle concurrent writes.
- Replica Setup: Spin up 2 Read Replicas for the database (offload Analytics/Dashboard queries).
- Worker Nodes: Scale up the BullMQ worker instances to handle "Payment Burst" traffic.
Phase 3: The "Go Live" (Hour 0)
- Feature Flag Check: Ensure
registrations_openis FALSE initially. - Deploy: Push Docker containers to production (Cloud Run / GKE).
- Sanity Check: Admins perform a "Test Loop" (Register -> Pay -> Generate QR -> Scan) on Production.
- The Switch: Admin toggles
registrations_opento TRUE. - Marketing Blast: Email/SMS sent to students.
Phase 4: The War Room (Monitoring)
- 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.
- 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.