Skip to main content

Platform decisions

Identity-level choices that bind every repo — a Flutter SDK contributor needs these as much as a backend contributor. Implementation mechanics live in systems/<domain>/; repo conventions live in each repo's docs/. If code and this page disagree, the code wins — then fix this page.

Verified against optolink-backend @ 29f8589 and optolink-portal @ 7d31d45, 2026-10-07 (B-010) — via the source-checked systems pages (B-012/B-013/B-018 passes) and product/pricing-and-plans; the portal's geo.ts read directly.

Clerk is the identity provider​

Portal and backend authenticate through Clerk (JWT sessions, org membership via webhook mirroring). SDKs don't use Clerk — they integrate with API keys (below). Mechanics: systems/auth-clerk/.

Plans and quotas are backend-enforced​

Five plans (STARTER → SOLO → GROWTH → SCALE → ENTERPRISE) gate features and quotas server-side; every client — portal or SDK — sees the enforcement as HTTP 402s and locked surfaces. Pricing detail: product/pricing-and-plans. Enforcement mechanics: systems/entitlements/; subscription mechanics: systems/billing/.

API keys have two tiers​

CLIENT (opl_sdk_…) and SERVER (opl_api_…). The tier governs which endpoints a key can reach; every SDK integrates against this contract. Contract detail: systems/sdk-contracts/; key mechanics: systems/auth-clerk/authentication.

Two payment gateways, currency-routed​

USD → Stripe, EGP → Paymob. The routing rule is by-country (EG → EGP → Paymob, everyone else → USD → Stripe), but the geo-detection behind it is deliberately inert (FLOW-012 D1): cachedCountry() falls back to "EG" and nothing writes the cache, so every browser currently defaults to EGP → Paymob — USD/Stripe is reachable only by manually setting the localStorage country key. Flipping that default is a product decision, not a code fix. Mechanism: systems/billing/architecture.

One org per user (v2 scope)​

OrgMember is the canonical membership source. Everything multi-org is out of scope until a decision record says otherwise. Membership mechanics: systems/auth-clerk/.