GCStore Core — Level-2 Deep Dive

GCStore Core is the constellation's central component: the single source of truth for customer identity, entitlement, app catalog, licensing and delivery. Every product — the desktop Hub fleet, the web SaaS apps, the storefront — delegates the same two questions to it: who is this customer, and what may they do? It answers with short-lived signed tokens and server-side decisions; no client is ever trusted to decide anything.

Internal architecture

Four API surfaces over a shared core, one small Go binary:

Device API — the Hub fleet's surface: device authorization (license key + hardware fingerprint, optional TPM tier) and delivery (signed leases, signed package pointers, gated link lists for push content).
Account API — the web surface: exchanges a verified Keycloak login for a short-lived, scope-carrying app token (per app, and for video, per content item — including a viewing session id and a watermark identity), and serves the storefront's purchase context (identity + eligibility + profile + documents) in one call.
Admin API — bearer-gated management surface driven by the ERP (the constellation's admin cockpit): apps, packages, staged rollout, plans, entitlements, customers, role mappings.
Webhooks — real-time inbound events from the identity provider.

Behind the surfaces:

Entitlement engine — the composable plan model: plans grant scopes and include other plans (store → app → feature); effective access is the transitive union, expanded with a cycle-guarded walk. New commercial tiers are data, not code. Device entitlements and account eligibility (a deliberate denylist for commerce) live here too.
Token service — Ed25519 (EdDSA) JWS minting with a published key set, so every app backend verifies tokens offline: no shared secrets ever cross a trust boundary. Per-app TTLs are configuration.
Catalog & delivery — the app registry (typed: packaged app, web/push, API-brokered, video), staged developer→released rollout, signed package URLs served outside the container.
Identity sync — the two-way Keycloak integration. Forward: entitlement grants are projected into Keycloak client roles (auto-created, reconciled), so role-reading apps need no GCStore Core code path. Reverse: a custom Java event-listener SPI provider (built in-house, delivered as a jar the identity stack mounts — never embedded) webhooks profile changes in real time, with a scheduled poll as backup; every superseded profile is archived as an append-only JSON snapshot. GCStore Core owns the customer record; Keycloak is the gate.

Design decisions worth naming

Untrusted client, server-side truth. The Hub runs on machines the company does not control; visibility is universal but the right to install/use is decided per request, server-side. Client-side locks are UX only.
Contracts first, in a public repo. Every boundary (device authorization, web delivery, video delivery, storefront identity) is specified in a public contract folder before either side builds. The contract is the only state two development sessions reliably share.
Offline verification over shared secrets. Ed25519 public-key verification keeps app backends decoupled and the signing key in exactly one place (a secret manager — it never touches any repo).
Projection over duplication. Apps that already gate on IdP roles keep doing so; GCStore Core reconciles those roles from the plan model instead of every app growing its own user table.
Typed SQL over ORM (sqlc): compile-time-checked queries, versioned hand-applied migrations, no query-builder magic.
Minimal runtime: one static Go binary in a distroless image behind a TLS-terminating host proxy.

Interfaces

With	Provides	Consumes
Hub fleet	device auth, signed leases/packages, push content	device claims (license, fingerprint, TPM)
Web apps	scoped Ed25519 app tokens, published key set, per-content video gate	verified Keycloak bearers
Storefront	purchase context: identity, eligibility (denylist), profile, documents	verified Keycloak bearers
ERP	the whole admin API (cockpit), customer reconciliation	admin operations
Keycloak	role projection, user sync/backfill	OIDC token verification, profile events (webhook + poll)

Tech stack

Go · MySQL via sqlc (typed SQL, versioned migrations) · Ed25519/JWS (RFC 7515/8037) · OIDC (customers realm) · Docker multi-stage → distroless · host nginx TLS front · companion Java: the in-house Keycloak SPI event-listener provider.

Status & near roadmap

Production — serving the Hub fleet, GCruiter, GCflix and the storefront today. Near roadmap: payment-confirmed grant flow (checkout → entitlement), ERP-driven customer import (past marketplace buyers → invited accounts), finer per-content denial reasons, and viewing-session validation/concurrency caps for video.