Bilingual superadmin features

.clerk/.tmp/README.md

@@ -0,0 +1,4 @@
+
+## DO NOT COMMIT
+This directory is auto-generated from `@clerk/nextjs` because you are running in Keyless mode. Avoid committing the `.clerk/` directory as it includes the secret key of the unclaimed instance.
+

.clerk/.tmp/keyless.json

@@ -0,0 +1 @@
+{"publishableKey":"pk_test_bGlrZWQtamF2ZWxpbi02LmNsZXJrLmFjY291bnRzLmRldiQ","secretKey":"sk_test_e8dSaISCl0dIAbCRiHba1VhIrA1w8dfC9Bs2oZ5dFF","claimUrl":"https://dashboard.clerk.com/apps/claim?token=8a9lyxhq1f7tw70fxjabtor0finukxcsilfzefrp","apiKeysUrl":"https://dashboard.clerk.com/apps/app_37RA7v85L1UhcPG9G5373cbssXO/instances/ins_37RA7sD9nohiRs5A4hY0B9S0wxx/api-keys"}

.clerk/.tmp/telemetry.json

@@ -0,0 +1,4 @@
+{
+  "firedAt": "2025-12-27T17:10:41.974Z",
+  "event": "KEYLESS_ENV_DRIFT_DETECTED"
+}

.gitignore

@@ -33,3 +33,19 @@ tsconfig.tsbuildinfo
 
 # vercel
 .vercel
+
+# clerk (auto-generated, contains secret keys)
+.clerk
+
+# local tooling (do not commit)
+.tools
+
+# local npm cache (do not commit)
+.npm-cache/
+
+# gradle caches (do not commit)
+.gradle/
+
+# android signing (do not commit)
+*.jks
+android/keystore.properties

README.md

@@ -1,69 +1,160 @@
-# Next.js + Tailwind CSS + Ionic Framework + Capacitor Mobile Starter
+# FlowBalance — Next.js + Ionic + Capacitor + Clerk
 
-![Screenshot](./screenshot.png)
+This repo is a hybrid mobile app (Android/iOS) + web app:
+- **UI**: Next.js (App Router) + Ionic React + Tailwind
+- **Auth**: Clerk (`@clerk/nextjs`) with **email verification code** (passwordless)
+- **Billing**: Clerk Billing (B2C) shown in **external browser** (Google Play compliance)
+- **Mobile shell**: Capacitor (WebView pointing at the deployed Next.js app)
 
-This repo is a conceptual starting point for building an iOS, Android, and Progressive Web App with Next.js, Tailwind CSS, [Ionic Framework](https://ionicframework.com/), and [Capacitor](https://capacitorjs.com/).
+The project is intentionally built to avoid “spaghetti” workarounds: we prefer Clerk’s prebuilt components and documented configuration over custom auth UIs.
 
-Next.js handles the production React app experience, Tailwind can be used to style each page of your app, Ionic Framework provides the cross-platform system controls (navigation/transitions/tabs/etc.), and then Capacitor bundles all of it up and runs it on iOS, Android, and Web with full native access.
+---
 
-See this blog post for an overview of the stack and how it all works: <https://dev.to/ionic/build-mobile-apps-with-tailwind-css-next-js-ionic-framework-and-capacitor-3kij>
+## Fast commands
 
-## Usage
-
-This project is a standard Next.js app, so the typical Next.js development process applies (`npm run dev` for browser-based development). However, there is one caveat: the app must be exported to deploy to iOS and Android, since it must run purely client-side. ([more on Next.js export](https://nextjs.org/docs/advanced-features/static-html-export))
+```bash
+npm run dev
+```
 
-To build the app, run:
+```bash
+npm run make-android
+```
 
 ```bash
-npm run build
+npm run make-android-release
 ```
 
-All the client side files will be sent to the `./out/` directory. These files need to be copied to the native iOS and Android projects, and this is where Capacitor comes in:
+### One-command “commit & deploy to Vercel”
+
+We added a helper script:
 
 ```bash
-npm run sync
+npm run vercel -- "your commit message"
 ```
 
-Finally, use the following run commands to run the app on each platform:
+This runs: `git add .` → `git commit -m ...` → `git push origin main`.
+
+---
+
+## Architecture (how routing works)
+
+This repo uses Ionic’s router for the in-app experience, and Next routes for auth + web-only pages.
+
+- **Main app shell**: `components/AppShell.tsx`
+  - Ionic routes: `/home`, `/flows`, `/progress`, `/settings`
+- **Next routes**:
+  - `/sign-in` → `app/sign-in/[[...sign-in]]/page.tsx` (Clerk `<SignIn />`)
+  - `/sign-up` → `app/sign-up/[[...sign-up]]/page.tsx` (Clerk `<SignUp />`)
+  - `/subscribe-web` → `app/subscribe-web/page.tsx` (Clerk `<PricingTable />`, web-only)
+  - `/post-signup-redirect` → `app/post-signup-redirect/page.tsx` (legacy redirect helper; keep unless you remove env/dashboard redirects)
+
+---
+
+## Clerk: rules of engagement (important)
+
+### What we want
+- **No password sign-up** (email verification code only)
+- **No custom auth forms** unless Clerk prebuilt cannot support a requirement
+
+### What we actually use in code
+- Prebuilt components:
+  - `@clerk/nextjs` `<SignIn />` and `<SignUp />`
+  - `fallbackRedirectUrl` + `forceRedirectUrl` props (new API; replaces `afterSignInUrl` / `afterSignUpUrl`)
+
+### Official docs to reference first
+- Redirect URLs: `https://clerk.com/docs/guides/development/customize-redirect-urls`
+- Billing (B2C): `https://clerk.com/docs/nextjs/guides/billing/for-b2c`
+
+---
+
+## Mobile: Capacitor configuration (critical)
+
+### 1) Keep navigation inside the app WebView
+When `server.url` points to a remote domain, that domain **must** be included in `server.allowNavigation` or Capacitor will open it externally.
+
+Config lives in:
+- `capacitor.config.json` (source of truth)
+- generated copies under `android/.../capacitor.config.json` and `ios/.../capacitor.config.json` (sync keeps them updated)
+
+### 2) Do NOT enable `CapacitorHttp` for Clerk
+**Root cause of the “mobile WebView shows Email+Password (missing Clerk footer) vs browser shows correct passwordless sign-up”**:
+when `CapacitorHttp` is enabled, Clerk’s requests go through native HTTP, which breaks the WebView cookie/session model Clerk expects.
+
+Keep this setting:
+- `plugins.CapacitorHttp.enabled = false`
+
+If you change Capacitor config, always sync:
 
 ```bash
-npm run ios
-npm run android
+npx cap sync android
 ```
 
-## Livereload/Instant Refresh
+---
 
-To enable Livereload and Instant Refresh during development (when running `npm run dev`), find the IP address of your local interface (ex: `192.168.1.2`) and port your Next.js server is running on, and then set the server url config value to point to it in `capacitor.config.json`:
+## Billing / subscriptions (Google Play compliance)
 
-```json
-{
-  "server": {
-    "url": "http://192.168.1.2:3000"
-  }
-}
-```
+### Requirement
+**Payments must happen outside the app WebView**.
+
+### Current approach
+- In-app buttons open the **system browser** to:
+  - `https://flowbalance-jdk.vercel.app/subscribe-web`
+- We pass a **Clerk sign-in token** so the browser page is authenticated:
+  - `app/api/create-sign-in-token/route.ts`
+  - The native app opens: `/subscribe-web?__clerk_ticket=...`
+  - The web page consumes the ticket using `useSignIn().signIn.create({ strategy: 'ticket', ticket })`
+
+Key files:
+- `components/pages/Settings.tsx` (“Manage Subscription”)
+- `components/PaywallModal.tsx` (premium upsell → external browser)
+- `helpers/openExternal.ts` / `helpers/openSubscriptionPage.ts`
+- `app/subscribe-web/page.tsx`
 
-Note: this configuration wil be easier in Capacitor 3 which [recently went into beta](https://capacitorjs.com/blog/announcing-capacitor-3-0-beta).
+---
 
-## API Routes
+## Known gotchas (and how we avoid them)
 
-API Routes can be used but some minimal configuration is required. See [this discussion](https://github.com/mlynch/nextjs-tailwind-ionic-capacitor-starter/issues/4#issuecomment-754030049) for more information.
+### Next.js hydration errors
+Don’t render `window.location`, `navigator.userAgent`, etc. directly into JSX that’s server-rendered. Capture them in `useEffect` instead.
 
-## SEO & Static Hosting
+### Ionic SSR warnings
+Sometimes `<ion-*>` elements can warn about extra `class` attributes during hydration. Avoid putting Tailwind `className` directly on Ionic web components when it causes warnings; put styling on wrappers.
 
-- **Is the exported PWA crawlable?** By default this starter renders everything on the client (see `components/AppShell.tsx`), so the static build contains a minimal HTML shell that immediately hands off to JavaScript. Search engine bots that depend on server-rendered HTML will not see meaningful page content, so the project is not SEO-friendly out of the box. If you need full SEO support, SSR/SSG needs to be working on the routes you want indexed or using a parallel, SEO-optimized web surface, but take a look at the below caveat about this project.
-- **Can I host the export as static HTML?** Yes. `next.config.js` sets `output: 'export'`, so `npm run build` writes a fully static bundle to the `out/` directory. You can deploy those files to any static host (e.g. Vercel static, Netlify, S3, GitHub Pages) or let Capacitor copy them into the native shells.
+---
 
-## Caveats
+## Debugging utilities
 
-One caveat with this project: Because the app must be able to run purely client-side and use [Next.js's Export command](https://nextjs.org/docs/advanced-features/static-html-export), that means no Server Side Rendering in this code base. There is likely a way to SSR and a fully static Next.js app in tandem but it requires [a Babel plugin](https://github.com/erzr/next-babel-conditional-ssg-ssr) or would involve a more elaborate monorepo setup with code sharing that is out of scope for this project.
+We keep the debug UI **as an optional component**:
+- `components/DebugInfoBox.tsx`
 
-Additionally, Next.js routing is not really used much in this app beyond a catch-all route to render the native app shell and engage the Ionic React Router. This is primarily because Next.js routing is not set up to enable native-style transitions and history state management like the kind Ionic uses.
+Add it temporarily to any client page when debugging, then remove it for design work.
 
-## What is Capacitor?
+---
 
-You can think of [Capacitor](https://capacitorjs.com/) as a sort of "electron for mobile" that runs standard web apps on iOS, Android, Desktop, and Web.
+## Development workflow + user preferences (for future agents)
+
+### Preferences (must follow)
+- **Use official docs** before proposing changes. If unsure, link the exact doc page.
+- **Don’t invent** Clerk behavior or props; verify against docs.
+- **Don’t build custom auth UIs** unless explicitly requested (use Clerk prebuilt components).
+- **Always give copy/paste commands** using:
+  - `git add .`
+  - or the preferred one-liner: `npm run vercel -- "message"`
+- Keep changes clean and reversible; avoid “one-off hacks” that linger.
+
+### Style preference
+Tailwind-first styling. Only use raw CSS when necessary for Ionic theming or truly global concerns.
+
+---
+
+## Environment variables (minimum)
+
+Set these in both local `.env.local` and Vercel:
+
+```bash
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
+CLERK_SECRET_KEY=sk_...
+```
 
-Capacitor provides access to Native APIs and a plugin system for building any native functionality your app needs.
+If you use any redirect env vars, document them here and ensure they match existing routes. Avoid deprecated `NEXT_PUBLIC_CLERK_AFTER_*` variables.
 
-Capacitor apps can also run in the browser as a Progressive Web App with the same code.

android/app/build.gradle

@@ -1,10 +1,20 @@
 apply plugin: 'com.android.application'
 
 android {
-    namespace "com.example.app"
+    namespace "com.flowapp.app"
     compileSdkVersion rootProject.ext.compileSdkVersion
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
     defaultConfig {
-        applicationId "com.example.app"
+        applicationId "com.flowapp.app"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         versionCode 1
@@ -16,8 +26,24 @@ android {
             ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
+
+    signingConfigs {
+        release {
+            def keystorePropertiesFile = rootProject.file("keystore.properties")
+            def keystoreProperties = new Properties()
+            if (keystorePropertiesFile.exists()) {
+                keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
+                storeFile file(keystoreProperties['storeFile'])
+                storePassword keystoreProperties['storePassword']
+                keyAlias keystoreProperties['keyAlias']
+                keyPassword keystoreProperties['keyPassword']
+            }
+        }
+    }
+
     buildTypes {
         release {
+            signingConfig signingConfigs.release
             minifyEnabled false
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }