native-update 2.0.0 → 3.1.0

package/docs/project-knowledge-base/03-tech-stack-modules-services.md

@@ -2,8 +2,8 @@
 
 ## Metadata
 
-- **Reference Date:** 2026-03-16
-- **Last Updated:** 2026-03-16
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
 
 ## Monorepo Structure
 
@@ -13,9 +13,9 @@
 | `android/` | Android native plugin implementation in Kotlin |
 | `ios/` | iOS native plugin implementation in Swift |
 | `cli/` | CLI package and commands |
-| `website/` | Marketing site and dashboard application |
-| `website/functions/` | Legacy Firebase Functions backend/reference backend |
-| `example-apps/` | Example frontend and backend projects |
+| `website/` | Marketing site and dashboard application (React 19 + Vite + Capacitor wrapper) |
+| `backend/` | Laravel 11 + Nova 5 SaaS backend (only backend; canonical persistence layer) |
+| `example-apps/` | Example frontend (`react-capacitor/`) and backend (`node-express/`) projects |
 | `docs/` | Public docs, planning, reports, and knowledge artifacts |
 
 ## Root Package Tech Stack
@@ -24,8 +24,7 @@
 - TypeScript
 - Rollup
 - Capacitor 8 ecosystem packages
-- Vitest
-- ESLint
+- ESLint (`@typescript-eslint/*` flat config; `@eslint/js` is BANNED)
 - Prettier
 - Commander
 - Express
@@ -36,20 +35,33 @@
 
 ## Website Tech Stack
 
-- React 19
-- TypeScript
+- React 19 + TypeScript
 - Vite 7
 - Tailwind CSS v4
-- Firebase Auth
-- Firestore
-- Google Identity Services
-- Google Drive API
-- Zustand
-- Framer Motion
-- Radix UI primitives
-- D3
+- Google OAuth via Laravel Socialite (backend-driven; no Firebase Auth in the SPA)
+- Sanctum bearer tokens persisted via `@capacitor/preferences` (native) / `localStorage` (web)
+- TanStack Query (data plane with hierarchical keys + URL-state pagination + keepPreviousData)
+- Axios (`src/lib/api.ts` with 401-clear-and-redirect interceptor)
+- Zustand (local UI state)
+- Framer Motion (animations)
+- Radix UI primitives (Dialog, Tooltip, etc.)
+- D3 (charts)
 - React Router
 - React Markdown
+- Capacitor 8 (mobile wrapper for the dashboard)
+
+## Backend Tech Stack
+
+- Laravel 11
+- Laravel Nova 5 (admin UI at `/nova`)
+- Laravel Socialite (Google OAuth)
+- Laravel Sanctum (personal access tokens for the SPA)
+- `spatie/laravel-permission` (RBAC; `sanctum` guard; roles `super-admin`, `admin`, `user`)
+- MySQL (single source of persistence — no Firestore branch)
+- PHP 8.2+
+- Composer
+- Pest / PHPUnit (~136 tests at last finalization audit)
+- Google Drive PHP SDK (server-side OAuth; tokens encrypted via Laravel's encrypter)
 
 ## CLI Package
 
@@ -64,7 +76,7 @@
 - `bundle-sign`
 - `bundle-verify`
 - `keys-generate`
-- `backend-create`
+- `backend-create` (emits scaffolds with `TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY]` markers)
 - `server-start`
 - `monitor`
 
@@ -72,10 +84,10 @@
 
 - scaffolds projects
 - generates bundles
-- signs and verifies release artifacts
-- generates keys
+- signs and verifies release artifacts (RSA-2048 / RSA-4096 / EC P-256 / EC P-384)
+- generates keypairs
 - starts local server flow
-- supports deployment monitoring
+- supports deployment monitoring (interval+spinner cleanup, signal handlers, failure bail)
 
 ## Core Plugin Module Inventory
 
@@ -141,17 +153,7 @@
 - `crypto.ts`
 - `validator.ts`
 
-**Purpose:** cryptographic helpers and validation utilities.
-
-### `src/firestore/`
-
-- `firestore-client.ts`
-- `manifest-reader.ts`
-- `schema.ts`
-- `index.ts`
-- rules/indexes files
-
-**Purpose:** Firestore-backed manifest access and schema definition for update metadata.
+**Purpose:** cryptographic helpers and validation utilities (SHA-256, RSA-SHA256 verify).
 
 ### Root Entry Files
 
@@ -162,17 +164,19 @@
 
 **Purpose:** export surface, Capacitor plugin bindings, typings, and web fallback behavior.
 
+Note: `src/firestore/` was removed in v3.0.0 (2026-05-04). The plugin no longer carries any Firestore code; manifest reads happen over plain HTTPS against any user-controlled endpoint.
+
 ## Native Android Modules
 
 | File | Role |
 |------|------|
 | `NativeUpdatePlugin.kt` | Main Android plugin entry |
 | `LiveUpdatePlugin.kt` | OTA/live update Android implementation |
-| `AppUpdatePlugin.kt` | App update Android integration |
-| `AppReviewPlugin.kt` | In-app review Android integration |
+| `AppUpdatePlugin.kt` | App update Android integration (Play Core) |
+| `AppReviewPlugin.kt` | In-app review Android integration (Play Review) |
 | `BackgroundUpdatePlugin.kt` | Background update orchestration |
 | `BackgroundUpdateManager.kt` | Background scheduling/management logic |
-| `BackgroundUpdateWorker.kt` | Worker-based background task execution |
+| `BackgroundUpdateWorker.kt` | WorkManager-based background task execution |
 | `BackgroundNotificationManager.kt` | Notification support |
 | `NotificationActionReceiver.kt` | Notification action handling |
 | `SecurityManager.kt` | Android security helpers |
@@ -186,134 +190,155 @@
 | `LiveUpdatePlugin.swift` | OTA/live update implementation |
 | `WebViewConfiguration.swift` | web view config support for live updates |
 | `AppUpdatePlugin.swift` | App update iOS behavior |
-| `AppReviewPlugin.swift` | StoreKit review handling |
-| `BackgroundUpdatePlugin.swift` | background update behavior |
+| `AppReviewPlugin.swift` | StoreKit `SKStoreReviewController` handling |
+| `BackgroundUpdatePlugin.swift` | BGTaskScheduler background update behavior |
 | `BackgroundNotificationManager.swift` | notification support |
 | `SecurityManager.swift` | iOS security helpers |
 
-## Frontend Services
+## Frontend Services (`website/src/services/`)
 
 ### `auth-service.ts`
 
-- Google sign-in via Firebase popup
-- first-login user doc creation
-- existing-user last-login update
-- admin flag refresh for owner email
-- logout support
+- Initiates Laravel Socialite redirect for Google sign-in
+- handles `/auth/callback` token persistence via `lib/auth-token.ts`
+- logout flow (deletes Sanctum token, broadcasts event, clears Drive cache)
+
+### `apps-api-service.ts`
+
+- TanStack Query hooks for App CRUD against `/api/dashboard/apps/*`
 
 ### `google-drive-service.ts`
 
-- load Google Identity Services SDK
-- request Drive scopes
-- connect/disconnect Drive
-- persist token metadata in Firestore
-- fetch user info from Google
-- list files
-- create folder hierarchy
-- upload files
-- make files public
-- maintain Drive connection status
+- starts the server-side Drive OAuth flow (no browser SDK)
+- requests Drive auth URL from the backend
+- posts callback code back to the backend
+- reads Drive connection status from `/api/dashboard/me`
+- lists files via backend proxy endpoints
 
 ### `bundle-upload-service.ts`
 
-- validate bundle file
-- calculate SHA-256 checksum
-- generate file manifest from ZIP
-- upload bundle and manifest to Drive
-- write build document
-- update manifest document
-- track progress stages
+- validates ZIP file (size, type)
+- multipart POST to `/api/dashboard/apps/{app}/builds` with progress tracking
+- triggers TanStack Query cache invalidation on success
 
 ### `manifest-generator.ts`
 
-- derive per-file manifest from ZIP
-- compare old/new manifests
-- estimate delta size
-- decide if delta is worthwhile
-- extract files from ZIP
+- derives per-file manifest from ZIP (client-side, for delta hints)
+- compares old/new manifests
+- estimates delta size
+- decides if delta is worthwhile
+
+### `themeSync.ts`
+
+- syncs theme preferences to `users.preferences` JSON via `/api/dashboard/preferences`
 
 ### Other Frontend Services
 
-- `auth-service.ts`
-- `bundle-upload-service.ts`
-- `google-drive-service.ts`
-- `manifest-generator.ts`
 - capacitor service wrappers under `website/src/services/capacitor/`
 
 ## Frontend State Stores
 
 ### `appsStore`
 
-- fetch user apps
-- fetch app by ID
-- create/update/delete app
-- manage selected app and errors
+- TanStack-Query-backed cache for user apps (hierarchical keys)
+- selected-app tracking + error surface
 
 ### `buildsStore`
 
-- fetch builds per app/user/channel
-- fetch build by ID
-- fetch latest builds
-- update build status
-- delete builds
+- TanStack-Query-backed cache for builds per app/user/channel
+- pagination + filter state encoded in URL search params
 
 ### `rolloutsStore`
 
-- fetch rollout state from manifests
-- fetch rollout by app/channel
-- update rollout config
-- pause/resume/start rollout
+- fetches rollout state from Build rows
+- pause/resume/percentage mutations
 
 ### `analyticsStore`
 
-- fetch analytics batches
-- aggregate downloads, installs, errors, rollbacks
-- build platform/version summaries
-- manage date range
+- fetches aggregated events from `/api/dashboard/analytics`
+- builds platform/version summaries
+- manages date range
 
-## Website Backend Reference (`website/functions`)
+## Backend Source Tree (`backend/`)
 
-### Main Areas
+### Controllers (`app/Http/Controllers/`)
 
-- `config/firebase.ts`
-- `middleware/auth.ts`
-- `middleware/validation.ts`
-- `routes/apps.ts`
-- `routes/builds.ts`
-- `routes/users.ts`
-- `utils/errors.ts`
-- `utils/validators.ts`
-- `index.ts`
+- `Auth/OAuthController` (Socialite redirect + callback + Sanctum token issuance)
+- `Dashboard/AnalyticsDashboardController`
+- `Dashboard/ApiKeyController`
+- `Dashboard/AppController`
+- `Dashboard/BuildController`
+- `Dashboard/GoogleDriveController`
+- `Dashboard/MeController`
+- `Dashboard/PreferencesController`
+- `Dashboard/RolloutController`
+- `Dashboard/SigningKeyController`
+- `Dashboard/SubscriptionController`
+- `Api/UpdateController` (mobile `/api/v1/updates/check`)
+- `Api/BundleController` (signed `/api/v1/bundles/{build}/download`)
+- `Api/AnalyticsController` (mobile `/api/v1/analytics/*`)
 
-**Purpose:** a Firebase Functions + Express reference backend retained in the repo.
+### Eloquent Models (`app/Models/`)
+
+- `User`
+- `App`
+- `ApiKey`
+- `SigningKey`
+- `Build`
+- `Subscription`
+- `DeviceActivity`
+- `AnalyticsEvent`
+
+### FormRequest Validators (`app/Http/Requests/`)
+
+- `UpdateBuildRequest` and related Create/Update FormRequests for App, ApiKey, SigningKey
+
+### Routes
+
+- `routes/api.php` (all `/api/*` routes)
+- `routes/web.php` (Nova mounts + OAuth callback HTML stubs)
+- `routes/console.php` (Artisan commands including `native-update:role-assign`)
+
+### Policies + Gates
+
+- `User`, `App`, `Build`, `ApiKey`, `SigningKey` policies registered in `AuthServiceProvider`
+- `Gate::before` returns `true` for `super-admin` (full bypass)
+- `Nova/User.php` carries `canSee` guards for admin-only resources
 
 ## Example Apps
 
 ### `example-apps/react-capacitor/`
 
 - frontend example demonstrating plugin use in a Capacitor app
+- React 18 (stable downstream target; explained in its README "React 18 vs React 19" section)
+- capability cards: OTA basic, app-update (`getAppUpdateInfo`/`openAppStore`), app-review (`canRequestReview`/`requestReview`), background-update (toggle with `allowMeteredConnection`/`nextCheckTime`)
 
 ### `example-apps/node-express/`
 
-- backend example using Node.js + Express
-
-### `example-apps/firebase-backend/`
+- minimal Node.js + Express backend example
+- ~160 lines, dissected in `docs/backend/node-express-minimal.md`
+- demonstrates the manifest-endpoint contract without a full SaaS
 
-- Firebase-based backend example
+Note: `example-apps/firebase-backend/` was removed in v3.0.0 (2026-05-04).
 
 ## Testing Modules Present
 
-### TypeScript Tests
+### TypeScript Tests (root plugin)
 
 - bundle manager
 - config
 - delta processor
-- firestore schema
-- integration
+- integration (live-update flow)
 - manifest reader
 - rollout checker
 - security
 - version manager
+- 62/62 passing at last verification
+
+### Backend Tests (`backend/tests/`)
+
+- OAuth + Sanctum + Spatie + UpdateBuildRequest FormRequest + PayPal webhook + BundleUpload + UserLicense
+- ~136 tests passing (`php artisan test`)
 
 ### iOS Tests
 
@@ -332,16 +357,23 @@
 - live update plugin tests
 - security manager tests
 
-### E2E
+### E2E (`e2e/`)
 
 - OTA update flow
 - download progress
 - channel switching
 - error handling
 
+### Microbenchmarks (`tools/bench/`)
+
+- `verify-checksum.bench.ts` (SHA-256 over 1/5/20 MB)
+- `verify-signature.bench.ts` (RSA-2048 + RSA-4096 SHA-256 verify over 5 MB)
+
 ## Important Architectural Direction
 
 - Treat the plugin as runtime infrastructure.
 - Treat the website as management and distribution tooling.
-- Treat Firestore manifests as a key source of truth for client update checks.
-- Treat Google Drive as the preferred no-cost storage destination for uploaded artifacts in the website flow.
+- Treat Laravel + MySQL as the single source of truth for App, Build, and User data.
+- Treat Sanctum personal access tokens as the only credential the SPA holds; the dashboard reads its identity from `/api/dashboard/me`.
+- Treat Google Drive as the canonical storage destination for uploaded bundle ZIPs (server-side OAuth tokens, encrypted at rest).
+- Treat the mobile API plane (`/api/v1/*`) as a separate auth surface (per-app API keys, not Sanctum).