OpsKnight Mobile Development Guide

This document provides a comprehensive overview of the OpsKnight Mobile App architecture, development workflow, and PWA capabilities.

1. Architecture Overview

The mobile application is built as a sub-path (/m) within the main Next.js application, utilizing the App Router.

File Structure

• src/app/(mobile)/m/: Root for all mobile routes.
• src/app/(mobile)/m/layout.tsx: Mobile-specific layout (shell, navigation).
• src/components/mobile/: Mobile-specific UI components.
• src/app/globals.css: Contains mobile variables and dark mode overrides.

Core Technologies

• Next.js 14+ (App Router)
• CSS Variables: For theming (Light/Dark mode).
• next-themes: Handles theme switching.
• web-push: Handles Server-side Push Notifications.
• @ducanh2912/next-pwa: Handles Service Worker generation.

2. Progressive Web App (PWA) & Push Notifications

OpsKnight Mobile is a PWA, meaning it can be installed on devices and receive Push Notifications.

Push Notification Setup

To enable Push Notifications locally or in production, you must configure VAPID keys.

1. Generate Keys: Run: npx web-push generate-vapid-keys

2. Configure Environment (.env): Add the generated keys:

   NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key
   VAPID_PRIVATE_KEY=your_private_key
   VAPID_SUBJECT=mailto:[email protected]
   

   Why these keys?

   • Public Key: Tells the browser/device that notifications from your server are legitimate.
   • Private Key: Signs the notifications on the server. Never share this!
   • VAPID_SUBJECT: A contact email (mailto:...) required by push services (like Google/Mozilla) so they can contact you if your app generates excessive errors or spam.

How it Works

1. Client: PushNotificationToggle.tsx requests permission and subscribes via the browser's Service Worker.
2. Subscription: The subscription object (containing endpoint and encryption keys) is sent to /api/user/push-subscription.
3. Storage: Saved in UserDevice table (platform: 'web', token: JSON string).
4. Sending: src/lib/push.ts uses web-push library to encrypt and send notifications to the endpoint (FCM/Mozilla/Apple).

3. Theming & Dark Mode

Mobile Dark Mode is implemented via standard CSS variables, scoped to the mobile shell.

• Variables: Located in src/app/globals.css under [data-theme='dark'] .mobile-shell.
• Usage: Always use semantic variables (e.g., var(--bg-secondary), var(--text-primary)) instead of hardcoded hex values.

Key Variables

Variable	Description
--bg-secondary	Card/Input background (Dark/Light aware)
--accent	Primary action color (Blue/Indigo)
--badge-snoozed-bg	Snoozed badge background
--badge-error-text	Critical/Error text color

4. Components Library

Located in src/components/mobile/.

• MobileCard: Standard container with border and padding.
• MobileButton: Touch-optimized button (supports variant="primary|secondary|danger").
• MobileList / MobileListItem: Standard list view components.
• PullToRefresh: High-performance touch-based referesh logic (integrated in Layout).
• MobileIncidentActions: Complex action bar for Incidents (Ack, Resolve, parameters).

5. Testing

We use Vitest for unit testing.

Running Tests

• All Tests: npm run test:all
• Mobile Tests: npm run test:unit (filters for mobile tests if specified in config, or run specific files).
• Specific File: npx vitest tests/components/mobile/MobileIncidentActions.test.tsx

Test Structure

Tests are located in tests/components/mobile/ and mock:

• next/navigation (useRouter, useSearchParams)
• next-themes (useTheme)
• Server Actions

6. Developing New Features

1. Create Page: Add page.tsx in src/app/(mobile)/m/[feature]/.
2. Use Components: Import from @/components/mobile/.
3. Add to More: If it's a root feature, add a link in src/app/(mobile)/m/more/page.tsx.
4. Test: Create a corresponding test file.

---

Generated by OpsKnight Dev Team