native-update 1.4.9 → 3.1.0

package/docs/project-knowledge-base/02-routes-pages-forms-users.md

@@ -0,0 +1,352 @@
+# Native Update Routes, Pages, Forms, and Users
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+
+## Route Inventory
+
+### Public Marketing and Info Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/` | HomePage | Public | Main landing page and primary product pitch |
+| `/features` | FeaturesPage | Public | Feature breakdown across OTA, app updates, and reviews |
+| `/pricing` | PricingPage | Public | Pricing/beta/commercial positioning page |
+| `/docs` | DocsPage | Public | Docs hub and guided docs entry |
+| `/docs/*` | DocsMarkdownPage | Public | Render markdown docs pages from public docs set |
+| `/examples` | ExamplesPage | Public | Code snippets + sample-app links |
+| `/about` | AboutPage | Public | Mission, project story, differentiators, creator profile |
+| `/contact` | ContactPage | Public | Contact methods, support info, FAQ |
+| `/privacy` | PrivacyPage | Public | Privacy policy |
+| `/terms` | TermsPage | Public | Terms of service |
+| `/data-deletion` | DataDeletionPage | Public | Data/account deletion policy |
+| `/cookies` | CookiePolicyPage | Public | Cookie policy |
+| `/security` | SecurityPage | Public | Security messaging and practices |
+| `/sitemap` | SitemapPage | Public | Human-friendly route explorer/search |
+| `/feed` | FeedPage | Public | Human-facing public content feed/search |
+
+### Auth Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/login` | LoginPage | Public | Sign in with Google (redirects to Laravel Socialite) |
+| `/signup` | SignupPage | Public | Same OAuth flow as `/login`; account auto-created on first callback |
+| `/auth/callback` | CallbackPage | Public | Receives the Sanctum token from Laravel's OAuth callback and persists it |
+| `/oauth/google-drive/callback` | DriveCallbackPage | Public | Receives Drive OAuth code and posts it to the Laravel backend |
+
+### Protected Dashboard Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/dashboard` | DashboardOverview | Authenticated user | Main dashboard metrics and quick actions |
+| `/dashboard/apps` | AppsPage | Authenticated user | Create, edit, delete, and browse owned apps |
+| `/dashboard/apps/:appId` | AppDetailPage | Authenticated user | Per-app details, builds, channels, and rollout state |
+| `/dashboard/builds` | BuildsPage | Authenticated user | Browse/filter builds |
+| `/dashboard/builds/:buildId` | BuildDetailPage | Authenticated user | Detailed build record view |
+| `/dashboard/upload` | UploadPage | Authenticated user | Publish ZIP bundle, write manifest |
+| `/dashboard/drive` | GoogleDrivePage | Authenticated user | Connect/disconnect Drive and review storage footprint |
+| `/dashboard/config` | ConfigPage | Authenticated user | Show recommended backend/config integration guidance |
+| `/dashboard/settings` | SettingsPage | Authenticated user | Account preferences, account deletion |
+| `/dashboard/rollouts` | RolloutsPage | Authenticated user | Manage rollout percentages and pause/resume rollouts |
+| `/dashboard/analytics` | AnalyticsPage | Authenticated user | View aggregated update analytics |
+
+### Admin Routes (SPA)
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/admin` | AdminOverview | `admin` or `super-admin` role | Admin overview metrics |
+| `/admin/users` | AdminUsersPage | `admin` or `super-admin` role | Search/browse user accounts |
+| `/admin/apps` | AdminAppsPage | `admin` or `super-admin` role | Search/browse all apps |
+| `/admin/builds` | AdminBuildsPage | `admin` or `super-admin` role | Search/filter all builds |
+
+### Admin Routes (Nova)
+
+Laravel Nova 5 lives at `/nova` on the backend host. Same MySQL store, separate UI. Resources include User, App, ApiKey, SigningKey, Build, Subscription, AnalyticsEvent. Custom Nova actions exist for rotating signing keys, promoting builds, etc.
+
+## Access and Guard Behavior
+
+### ProtectedRoute (SPA)
+
+- Requires a Sanctum token stored in `@capacitor/preferences` (native) or `localStorage` (web)
+- The 401-handling axios interceptor clears the token and event-broadcasts a logout, redirecting to `/login`
+- Token is sent as a `Bearer` header on every `/api/dashboard/*` and `/api/admin/*` request
+
+### AdminRoute (SPA)
+
+- Requires a Sanctum token AND the SPA-side cached `me.roles` to include `admin` or `super-admin`
+- Backend enforcement: every Laravel admin route also carries `auth:sanctum` + `can:<permission>` middleware; an unauthorized request returns 403 regardless of SPA state
+
+### Backend gate model
+
+- `auth:sanctum` middleware on `/api/dashboard/*` and `/api/admin/*`
+- `can:<permission>` middleware on every dashboard/admin route (per-permission, not per-role)
+- `Gate::before` returns `true` for any user with the `super-admin` role (full bypass)
+- First sign-in assigns the `user` role; emails in `ADMIN_EMAILS` env auto-assign `super-admin`
+
+## User Types and Permissions
+
+### Public Visitor
+
+- Can view product, docs, legal, sitemap, feed, and contact pages
+- Cannot access dashboard or admin
+
+### Signed-In Product User
+
+- Signs in via Google (Laravel Socialite redirect)
+- has a MySQL `users` row keyed by `google_id`
+- holds a Sanctum personal access token (default 7-day TTL, configurable via `SANCTUM_TOKEN_EXPIRATION`)
+- carries the `user` role by default
+- can manage their own apps/builds/settings
+- can connect Google Drive (server-side OAuth — tokens encrypted at rest on the User row)
+
+### Admin User
+
+- Same as signed-in user plus `admin` or `super-admin` role
+- can access SPA admin pages and Nova admin
+- super-admin bypasses every `can:` gate
+
+### App Runtime Consumer
+
+- Uses plugin APIs and manifest endpoints
+- authenticates with a per-app API key (separate `ValidateApiKey` middleware on `/api/v1/*`)
+- not a website operator account
+
+## Page-Level Notes
+
+### HomePage
+
+- Hero positioning: complete update solution for Capacitor
+- Calls to action: get started, view docs
+- Highlights three core pillars: OTA updates, native app updates, in-app reviews
+
+### FeaturesPage
+
+- Feature cards for OTA, native app updates, and reviews
+- Messaging includes delta updates, rollback, channels, encryption, analytics, priority levels, and rate limiting
+
+### AboutPage
+
+- Includes project mission
+- explains why project exists
+- highlights open-source positioning
+- includes creator profile and contact links
+
+### ContactPage
+
+- No typed form submission flow
+- Uses direct contact methods: email, WhatsApp, LinkedIn, portfolio, docs, NPM link
+- Includes support-hour information and FAQ
+
+### DocsPage / DocsMarkdownPage
+
+- DocsPage acts as a rich docs landing surface
+- DocsMarkdownPage renders markdown docs pages from the public docs payload
+
+### ExamplesPage
+
+- Hero + quick-start code snippets (OTA basic, React hook, background, app-store, self-hosted backend pattern)
+- Two canonical example-app cards (React + Capacitor, Node.js + Express)
+
+### SitemapPage and FeedPage
+
+- Search/filter style discovery experiences
+- use Input fields for route/content lookup
+- intended as human-friendly content navigation surfaces
+
+### DashboardOverview
+
+- Shows owned app/build summary state
+- includes CTA to upload first build
+
+### AppsPage
+
+- Central app management page
+- create/edit/delete dialog workflows (URL-state driven: `?formMode`, `?editId`, `?deleteId`)
+- stores package id, description, platforms, and generates an API key on creation
+
+### AppDetailPage
+
+- per-app management view
+- shows builds and rollout state
+- links to upload and rollout workflows
+
+### BuildsPage / BuildDetailPage
+
+- list and inspect build history
+- filter by app/channel/status/platform
+- build detail includes upload time, uploader, duration, and release metadata
+
+### UploadPage
+
+- Core publish UI
+- requires Google Drive connection (server-side OAuth must be completed)
+- multipart-POST ZIP to Laravel `/api/dashboard/apps/{app}/builds`
+- Laravel computes SHA-256, signs with the app's signing key, stages in user's Drive, persists Build row in MySQL
+
+### GoogleDrivePage
+
+- starts the Drive OAuth flow (`/api/dashboard/google-drive/auth-url` → full-window Google redirect → `/oauth/google-drive/callback` → POST code to backend)
+- shows Drive connection status, connected email, folder list, file count, and total size
+
+### ConfigPage
+
+- instructional/configuration surface
+- presents the recommended path: dashboard publishes through the Laravel backend; plugin polls the Laravel manifest endpoint
+
+### SettingsPage
+
+- account profile details
+- preferences (`users.preferences` JSON column via `/api/dashboard/preferences`)
+- appearance/theme controls
+- account deletion confirmation flow (Sanctum tokens revoked, MySQL row soft-deleted, encrypted Drive tokens cleared)
+
+### RolloutsPage
+
+- percentage controls
+- pause/resume actions
+- edit modal with numeric and range input
+- rollout best practices guidance
+
+### AnalyticsPage
+
+- filters by app and channel
+- aggregates analytics data across time range from `analytics_events` table
+- intended for download/install/error/rollback analysis
+
+### Admin Pages
+
+- AdminOverview aggregates cross-system metrics
+- AdminUsersPage supports user search/filtering
+- AdminAppsPage supports app search/filtering
+- AdminBuildsPage supports build search/filtering by multiple fields
+- Full admin tooling (resource editors, custom actions) lives in Nova at `/nova`
+
+## Form and Input Inventory
+
+### LoginPage
+
+- **Action:** Google sign-in button → SPA navigates to `${VITE_API_URL}/auth/google/redirect`
+- **Inputs:** No text input fields
+- **Errors handled:** popup blocked (unlikely with full-window redirect), generic OAuth failure displayed on `/auth/callback`
+
+### SignupPage
+
+- **Action:** Same Google flow as LoginPage; backend auto-provisions the User row + assigns `user` role
+- **Inputs:** No text input fields
+- **Purpose:** fast account creation for beta onboarding
+
+### AppsPage Create/Edit App Dialog
+
+- **Fields:**
+  - App name
+  - Package ID
+  - Description
+  - Platforms: Android, iOS, Web
+- **Validation:**
+  - app name required, minimum length
+  - package ID required and regex-validated
+  - at least one platform required
+- **Backend side effects on create (Laravel `AppController` + `UpdateBuildRequest`):**
+  - inserts row in `apps` table (RBAC-gated by `can:apps.create`)
+  - generates an API key, inserts row in `api_keys` table
+  - increments user `apps_count`
+
+### AppsPage Delete Dialog
+
+- **Purpose:** destructive app deletion
+- **Backend side effects:** soft-deletes app row, revokes related API keys, decrements user `apps_count`, optionally archives builds
+
+### UploadPage Publish Form
+
+- **Fields:**
+  - file picker / drag-drop ZIP
+  - app select
+  - channel select
+  - platform select
+  - version input
+  - build number input
+  - release notes textarea
+- **Validation (server-side `UpdateBuildRequest` FormRequest):**
+  - app_id required + ownership-checked
+  - version required + semver-validated
+  - build_number required + numeric
+  - ZIP file required + max-size enforced
+  - Drive connection required (backend rejects otherwise)
+- **Flow:**
+  - browser multipart POST → Laravel `/api/dashboard/apps/{app}/builds`
+  - Laravel validates, computes SHA-256, signs with RSA-SHA256 using the app's signing key
+  - Laravel uploads the ZIP to the user's Drive folder (server-side OAuth tokens)
+  - Laravel writes the Build row, updates the App's active manifest pointer
+  - SPA navigates to app detail
+
+### SettingsPage Preferences
+
+- **Fields:**
+  - email notifications toggle
+  - update notifications toggle
+  - theme select
+  - language select
+- **Action:** PATCH `/api/dashboard/preferences` → updates `users.preferences` JSON column
+
+### SettingsPage Delete Account
+
+- **Field:** confirmation input requiring exact `DELETE`
+- **Action:** DELETE `/api/dashboard/me` → revokes Sanctum tokens, soft-deletes user row, clears encrypted Drive tokens, cascades to apps/builds
+
+### RolloutsPage Edit Modal
+
+- **Fields:**
+  - rollout percentage numeric input
+  - rollout percentage range slider
+- **Action:** PATCH `/api/dashboard/builds/{build}/rollout` → updates rollout config on the Build row
+
+### BuildsPage Filters
+
+- search input
+- app filter
+- channel filter
+- platform filter
+- status filter
+- URL-state driven (`?q=`, `?app=`, `?channel=`, `?platform=`, `?status=`, `?page=`)
+
+### AdminBuildsPage Filters
+
+- search input
+- app filter
+- user filter
+- channel/status/platform filters
+
+### AdminUsersPage Filters
+
+- search input
+
+### AdminAppsPage Filters
+
+- search input
+
+### FeedPage and SitemapPage
+
+- search input for route/content discovery
+
+## Contact and Support Surfaces
+
+### ContactPage URLs
+
+- `mailto:aoneahsan@gmail.com`
+- `https://www.npmjs.com/package/native-update`
+- `https://wa.me/923046619706`
+- `https://linkedin.com/in/aoneahsan`
+- `https://aoneahsan.com`
+- internal docs link: `/docs`
+
+## Important UX and Product Notes
+
+- Dashboard is clearly owner/operator tooling, not consumer UI
+- Google sign-in is the only auth path
+- Google Drive is central to the publishing workflow (server-side OAuth, not browser SDK)
+- App creation is a prerequisite for upload
+- Drive connection is a prerequisite for upload
+- Rollouts are edited on the Build row, not from a separate dedicated rollout service
+- All user-visible state that should survive refresh (modal open, edit/delete dialogs, filters, tabs) is encoded in URL search params via the shared `useUrlState` hooks