ארכיטקטורה וטכנולוגיה
תוכנית ריבוי הפלטפורמות
תוכנית מסירה לווב ולמובייל, תלויות ושערי מוכנות.
בעמוד הזה
Status: Phase 1 foundation implemented on an isolated feature branch. The approved Web product remains the source of truth and is locked from unrelated visual or runtime changes.
Production target#
Ship one LinkNodes Energy account and data model across three production surfaces:
- Web: existing Next.js application on Vercel, used from Windows and macOS browsers.
- iOS/iPadOS: Expo + React Native.
- Android: Expo + React Native.
All clients share Clerk identity, Supabase data/RLS, server-side business rules, Grafana observability and PostHog product analytics. They do not share one forced UI implementation.
Non-destructive boundaries#
- Do not move, rename, wrap or redesign the root Next.js application.
- Existing approved imagery, vehicle assets, colors, typography and workflows remain locked.
- The only native client is additive under apps/mobile.
- Mobile is a native React Native client, not a WebView of the website.
- Windows and macOS remain browser-only; no native desktop app is maintained.
- Service-role, HYP, supplier and infrastructure secrets never ship in client bundles.
- Existing Web /api/platform same-origin protections remain unchanged.
Architecture#
LinkNodes Platform
Clerk + Supabase + Server APIs
|
+--------------------+
| |
Web Mobile
Next.js / Vercel Expo / RN
Windows + macOS browsers iOS + Android
The first migration is deliberately not a root workspace refactor. Each new client owns an isolated package.json and client-local pnpm workspace boundary with exact direct dependency versions. Release lockfiles are introduced and validated in the native signing/release phase. Shared packages are introduced only after stable cross-client contracts are proven.
Identity and authorization#
Clerk stays the identity provider. Supabase PostgreSQL/RLS stays the authorization boundary.
Normal client access uses:
- Clerk user session token.
- Supabase publishable key.
- Supabase third-party Clerk verification.
- existing tenant memberships and RLS.
Never embed:
- SUPABASE_SERVICE_ROLE_KEY or Supabase secret keys.
- HYP/Masof credentials.
- charging/fuel provider secrets.
- webhook secrets.
- infrastructure/admin tokens.
Mobile API boundary#
The Web mutation API intentionally requires same-origin browser requests and Clerk's Next.js session. Mobile must not weaken it.
Phase 2 adds a versioned client API such as /api/client/v1:
- Authorization: Bearer Clerk session JWT.
- server-side Clerk token verification.
- user-scoped Supabase RLS client.
- explicit schemas, body limits and rate limits.
- tenant membership re-check per protected operation.
- no wildcard CORS.
- privileged server-only actions remain server-only.
- tests for expired/invalid token, suspended membership, wrong tenant and cross-tenant access.
Web /api/platform retains its current cookie + same-origin behavior.
Design translation#
Canonical sources remain styles/tokens.css, public/design-system/tokens.json, Visual System 2.0 and approved production screens.
Current shared values:
- Midnight #161b36
- Primary #4b3eff
- Energy #c4ff48
- Background #f4f5fb
- Text #18213d
- Surface #ffffff
- Border #e0e4f0
- spacing 4/8/12/16/20/24/32/40/48
Platform adaptation is allowed; redesign is not.
Mobile:
- Home / Map / Vehicles / Energy / Account bottom navigation.
- safe areas, native touch targets, keyboard handling and accessibility.
- iOS/Android platform conventions where appropriate.
- Hebrew RTL first-class.
Desktop:
- sidebar + dense workspace.
- keyboard/pointer/focus/window resizing.
- macOS and Windows platform conventions where required.
- same brand hierarchy, not a stretched phone layout.
Phase 1 — foundation#
Deliver:
- apps/mobile: Expo SDK 58 / React Native.
- approved LinkNodes app icon source preserved as SVG; platform-native renditions are generated and verified in the signing/release phase.
- isolated package manifests, exact direct dependency versions and client-local workspace boundaries.
- EAS development/preview/production profiles.
- identifiers:
- iOS bundle: com.linknodesenergy.app
- Android package: com.linknodesenergy.app
- deep-link scheme: linknodes
- root Web TypeScript/ESLint explicitly excludes client trees.
- independent CI checks.
Acceptance:
- existing Web pipeline behavior is unchanged.
- client installs resolve inside their own workspace and do not mutate the root workspace.
- Mobile TypeScript passes.
- Expo Doctor passes 20/20.
- iOS and Android JavaScript bundles export successfully.
- no secret is committed.
Phase 2 — identity + client API#
Mobile:
- ClerkProvider + SecureStore token cache.
- branded sign-in/sign-up/recovery.
- Apple/Google sign-in only after provider and entitlement validation.
- Supabase client uses Clerk token.
Backend:
- bearer-token client API.
- shared service layer for privileged operations.
- full tenant-isolation test matrix.
Acceptance:
- one account signs in on all clients.
- tenant A cannot read/write tenant B from any client.
- suspended/revoked membership fails everywhere.
Phase 3 — Mobile product#
Implement in dependency order:
- auth/onboarding/workspace selection.
- vehicles and verified vehicle flows.
- provider preferences.
- native station map/search.
- unified electricity/fuel ledger.
- analytics/reporting.
- billing/subscriptions using hosted secure payment flows.
- notifications/deep links where justified.
- offline/error/retry states.
No UI may claim real charging/payment execution until provider production APIs are connected and verified.
Phase 4 — Observability#
All clients join the existing DigitalOps control plane:
- Grafana Cloud = official monitoring/observability.
- PostHog = product analytics.
- no duplicate Sentry/standalone monitoring pipeline.
- telemetry includes platform/environment/app version.
- no tenant/customer PII in high-cardinality labels.
Track:
- mobile crashes/errors and launch health.
- API latency/error by client version.
- auth failures.
- map/search latency.
- release adoption.
Phase 5 — QA/security matrix#
Every release candidate requires:
- type/unit/API contract checks.
- auth + tenant isolation tests.
- iOS physical-device QA.
- Android physical-device QA.
- accessibility.
- Hebrew RTL.
- visual regression against approved screens.
- deep-link validation.
- upgrade/rollback test.
- client bundle secret scan.
Phase 6 — Store/signing readiness#
Apple:
- Apple Developer organization membership.
- App Store Connect record.
- production capabilities/signing.
- privacy disclosures/policy.
- screenshots/metadata/support URL.
- TestFlight validation.
- App Review after release gate.
Google Play:
- organization developer account.
- app record for com.linknodesenergy.app.
- Play App Signing.
- Data Safety/privacy disclosures.
- store listing.
- internal/closed testing.
- production rollout after release gate.
Signing material never enters Git.
Phase 7 — release pipelines#
Web remains GitHub → Vercel.
Mobile: development builds → preview/internal → production EAS build → TestFlight / Play internal → explicit store submission gate.
EAS Update is only for runtime-compatible JS/assets. Native module/runtime changes require a new binary.
100% production definition#
Multi-platform production is complete only when:
- Web remains production healthy.
- iOS App Store version is live.
- Google Play production version is live.
- one real account works across Web, iOS and Android.
- tenant-isolation evidence passes across Web, iOS and Android.
- Grafana/PostHog receive production telemetry by client/version.
- rollback/release procedures are tested.
- no unresolved P0/P1 security or data-isolation issue remains.
Rollback#
- Web: existing Vercel rollback.
- Mobile: stop rollout; rollback OTA only when runtime-compatible, otherwise release prior-known-good binary/version.
- API/database changes remain backward-compatible across supported client versions until minimum supported version is deliberately raised.