Mobile Performance & Responsiveness — What's Broken and the Fix Plan

[LarytheLord]

Why This Discussion Exists

As the platform grows — more pages, more data, more components — mobile experience has become a real problem. The dashboard, rankings, and admin pages were built desktop-first and are showing it. This discussion covers what's broken, why it's heavy, and the plan to fix it.

---

The Core Problem

The app is doing several things that hurt mobile performance:

1. WebGL shader hero on the landing page

components/ui/animated-shader-hero.tsx is 572 lines. It runs a WebGL shader loop on every landing page visit. On low-end Android devices (which is most of India's mobile market — directly relevant given the Open Paws Bangalore context) this:

• Blocks the main thread during shader compilation
• Drains battery noticeably
• Can crash tabs on devices with <2GB RAM

The component already has a CSS gradient fallback for when WebGL fails. The fix is to also trigger that fallback on mobile/low-memory devices before attempting WebGL, not after it crashes.

2. Dashboard pages have fixed heights that break on mobile

app/dashboard/page.tsx and app/dashboard/company/quests/page.tsx use fixed heights (h-[200px], min-h-[320px]) on loading states and empty states. On a 375px wide phone these look disproportionate and waste significant viewport space.

3. Rankings table overflows horizontally

components/RankingsBoard.tsx uses min-w-[100px] on columns in a flex layout. On mobile the table scrolls horizontally with no visual indicator that more content exists. Users miss columns silently.

4. Admin pages have no mobile layout

/admin/qa-queue, /admin/quests, /admin/users — all built as desktop-only tables. The admin is Open Paws team members who may be on their phones reviewing submissions. Currently unusable on mobile.

5. Large JS bundle from unoptimized components

Three components are >500 lines and are loaded as single modules:

• CompanyPortal.tsx — 786 lines (company dashboard)
• AdminDashboard.tsx — 576 lines (admin panel)
• animated-shader-hero.tsx — 572 lines (landing page)

These aren't code-split, so the entire module is bundled even when only part of it is needed.

---

What Good Mobile Looks Like for This App

The primary mobile users are:

• Bootcamp students checking quest board and submission status on their phones
• Interns doing the same
• Open Paws admins (Sam, Divyaansh, Abid) reviewing the QA queue between meetings

The dashboard and QA queue must be fully usable on mobile. The landing page must load fast on a slow 4G connection.

---

Fix Plan

Critical (blocks mobile usability)

Issue	File	Fix
WebGL on low-end mobile	animated-shader-hero.tsx	Detect navigator.hardwareConcurrency < 4 or navigator.deviceMemory < 2 → skip to CSS fallback
Fixed heights on dashboard empty/loading states	dashboard/page.tsx, company/quests/page.tsx	Replace h-[200px] with min-h-[120px] sm:h-[200px]
Rankings table horizontal overflow	RankingsBoard.tsx	Wrap table in overflow-x-auto, add sticky first column, show fewer columns on mobile
Admin pages not usable on mobile	/admin/qa-queue/page.tsx	Card layout (already done), but needs max-w-full and responsive padding audit

High (degrades experience)

Issue	File	Fix
Rank ladder hidden entirely on mobile	app/home/page.tsx	Show a compact horizontal strip instead of hidden lg:flex
No HowItWorks connector on mobile	HowItWorks.tsx	Replace the hidden lg:block gradient line with a vertical connector for mobile
Company portal 786 lines	CompanyPortal.tsx	Split into CompanyDashboardStats, CompanyQuestList, CompanyRecentActivity

Medium (code quality)

• Extract duplicate fetch-then-toast pattern into useApiFetch() custom hook
• Status badge color logic duplicated across 3+ files → lib/status-utils.ts
• Shared <DashboardKpiGrid> component used by both adventurer and company dashboards

---

Bundle Size Quick Wins

1. animated-shader-hero.tsx — extract WebGL renderer class to lib/webgl-renderer.ts so it can be lazy-loaded
2. CompanyPortal.tsx — split so each sub-component is only loaded when that tab is active
3. Dashboard pages — the stats fetch and the quest list fetch can be parallelised instead of sequential

---

Mobile Viewport Targets

All pages must be functional at:

• 375px × 667px (iPhone SE — the floor)
• 390px × 844px (iPhone 14 standard)
• 360px × 800px (typical Android mid-range)

"Functional" means: the user can complete their primary task without horizontal scrolling or content being cut off.