דילוג לתוכן
מרכז התיעוד
לאתר LinkNodes Energy
LinkNodesENERGYתיעוד

טוענים את החיפוש…

    חיפוש גם בתוך המאמרים ↑ ↓ לניווט Esc לסגירה

    לאתר החברה

    ארכיטקטורה וטכנולוגיה

    תוכנית ריבוי הפלטפורמות

    תוכנית מסירה לווב ולמובייל, תלויות ושערי מוכנות.

    בעמוד הזה

    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#

    1. Do not move, rename, wrap or redesign the root Next.js application.
    2. Existing approved imagery, vehicle assets, colors, typography and workflows remain locked.
    3. The only native client is additive under apps/mobile.
    4. Mobile is a native React Native client, not a WebView of the website.
    5. Windows and macOS remain browser-only; no native desktop app is maintained.
    6. Service-role, HYP, supplier and infrastructure secrets never ship in client bundles.
    7. 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:

    1. auth/onboarding/workspace selection.
    2. vehicles and verified vehicle flows.
    3. provider preferences.
    4. native station map/search.
    5. unified electricity/fuel ledger.
    6. analytics/reporting.
    7. billing/subscriptions using hosted secure payment flows.
    8. notifications/deep links where justified.
    9. 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:

    1. Web remains production healthy.
    2. iOS App Store version is live.
    3. Google Play production version is live.
    4. one real account works across Web, iOS and Android.
    5. tenant-isolation evidence passes across Web, iOS and Android.
    6. Grafana/PostHog receive production telemetry by client/version.
    7. rollback/release procedures are tested.
    8. 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.