Skip to main content

Glossary

All definitions below are sourced directly from project_context_map.md, kernel-spec.md, and CONVENTIONS.md. Terms are listed alphabetically.

A​

Argon2id​

Password hashing algorithm used by the IAM service for all user passwords. Parameters follow OWASP NIST 800-63B recommendations: memory 65 536 KB (64 MB), iterations 3, parallelism 4, output 32 bytes, salt 16 bytes. Argon2id is the mandatory algorithm — bcrypt, scrypt, and sha256 are not accepted.

Audit Dual-Write​

The Audit Service's write pipeline uses two independent paths: Primary — application emits events to Kafka (platform.audit.events) → ClickHouse consumer writes to ClickHouse. Fallback — when Kafka is unavailable, the application writes to PostgreSQL audit_wal table → a background worker replays records to Kafka when it recovers. The dual-write guarantees zero audit record loss under Kafka outages.

B​

B2B2B​

The three-tier commercial model of Platform-Kernel: Platform Owner (root) → Partner (reseller/integrator) → Client (end tenant). Each tier is a Tenant node in the closure table hierarchy. Partners can provision clients and inherit platform policies. Clients are isolated from each other via Row-Level Security.

C​

CDC (Change Data Capture)​

The pipeline that streams data changes from PostgreSQL (OLTP) to ClickHouse (OLAP): PostgreSQL → Debezium (WAL reader) → Kafka → ClickHouse consumer → ClickHouse. Latency: < 5 seconds. Delivery guarantee: at-least-once. Deduplication in ClickHouse is handled by ReplacingMergeTree + FINAL keyword.

Circuit Breaker​

A fault-isolation pattern implemented in services/gateway/internal/circuitbreaker/. The Gateway wraps each upstream service call in a circuit breaker with three states: Closed (normal, all requests pass), Open (upstream failing, all requests return 503 immediately), Half-Open (probe request sent to check recovery). State is tracked in-process. Metric: circuit_breaker_state Gauge (0=closed, 1=half-open, 2=open).

Closure Table​

The data structure used to represent and query the B2B2B tenant hierarchy in O(1) time. Each ancestor–descendant relationship is stored as a row (ancestor_id, descendant_id, depth). Querying whether Tenant B is under Tenant A requires a single index lookup instead of a recursive CTE. Implemented in the IAM service migrations and exposed via gRPC TenantHierarchyService.IsDescendant.

Conventional Commits​

The commit message format enforced in this repository: type(scope): description. Types: feat, fix, chore, refactor, test, docs, perf, freeze. All entries in the Changelog follow this format.

D​

Data Primitive​

One of the seven core primitives of Platform-Kernel (see Primitive). The Data primitive provides dynamic CRUD over PostgreSQL, analytics via ClickHouse, caching via Valkey, and real-time updates via the CDC pipeline. Accessed via @platform/sdk-data (useQuery(), useMutation(), useRealtime()).

Debezium​

The CDC connector that reads the PostgreSQL Write-Ahead Log (WAL) and publishes row-level change events to Kafka. Platform-Kernel pins Debezium at a fixed version (see docker/versions.env). Debezium JMX metrics are scraped by the OpenTelemetry JMX receiver and forwarded to VictoriaMetrics.

Delegation Token​

A short-lived JWT (default TTL: 3 600 seconds, env: DELEGATION_TOKEN_TTL) issued by the IAM service to allow a Platform Owner or Partner to act on behalf of a downstream client tenant. The token carries a parent_tenant_id claim validated by the Gateway delegation middleware. Valid TTL range is clamped to [MinDelegationTTL, MaxDelegationTTL] at service startup.

DLQ (Dead Letter Queue)​

A holding queue for events or webhook deliveries that have exhausted all retry attempts. In Platform-Kernel, two DLQ implementations exist: (1) Event Bus — Kafka messages that fail consumer processing after KAFKA_MAX_ATTEMPTS retries are moved to a DLQ topic; (2) Integration Hub — outgoing HTTP webhook calls that fail 5 times are moved to the Integration Hub DLQ for manual review or replay. Module authors can inspect the DLQ via GET /api/v1/integrations/dlq.

Double-Entry Ledger​

The accounting model enforced by the Money Service. Every value transfer creates exactly two journal entries: one debit on the source wallet and one credit on the destination wallet. The sum of all entries across all wallets always equals zero. Implemented using SELECT FOR UPDATE with deadlock prevention via lock ordering by UUID ASC.

E​

Envelope Encryption​

The multi-layer key management scheme used for field-level encryption: a Data Encryption Key (DEK) encrypts the plaintext field (AES-256-GCM), the DEK is encrypted by a Key Encryption Key (KEK) (RSA-2048+), and the KEK is protected by a Master Key stored in a FIPS 140-3 Level 3 HSM. Vault manages the DEK → KEK hierarchy via the shared/crypto package.

ES256​

The JWT signing algorithm used by Platform-Kernel for all internal platform tokens: ECDSA with the P-256 curve and SHA-256 hash. Private key stored in Vault at secret/platform/iam/jwt-keys. Public key distributed to all services via JWT_PUBLIC_KEY environment variable. Rotation interval: 90 days with 24-hour dual-key grace period.

F​

Feature Flag​

A runtime boolean or variant value managed by the GoFeatureFlag service (port 1031). Flags are namespaced per tenant with key prefix {tenantId}:{flagName}. The SDK (@platform/sdk-flags) caches flag state in-memory and refreshes every 15 seconds. When GoFeatureFlag is unreachable, all flags default to false (safe default).

G​

Gateway​

The single HTTP/gRPC entry point for all API traffic. Implemented in services/gateway/. The Gateway performs: JWT authentication, CORS enforcement (no wildcard), per-IP rate limiting (dual-layer: local token bucket + Valkey sliding window), OpenAPI request validation, RBAC permission checking, gRPC proxying to upstream services, and circuit breaking. All /api/v1/* requests are proxied; /live, /ready, and /health are served directly.

H​

Hold​

A temporary reservation of funds on a wallet, created by POST /api/v1/wallets/:id/hold. A hold reduces the wallet's available balance by the held amount. The hold can be resolved by Confirm (debit the frozen amount) or Cancel (release it back to available). Default TTL: 72 hours (MONEY_HOLD_TTL_HOURS). Maximum TTL: 7 days. Maximum concurrent holds per wallet: 100.

I​

Idempotency Key​

A client-supplied identifier (Idempotency-Key request header or idempotency_key JSON field) that guarantees at-most-once execution. If a request with the same key arrives twice within the dedup window, the second request receives the cached response without re-executing the operation. Implemented via Valkey with a TTL equal to the operation retention window.

Integration Hub​

The outbound HTTP proxy service (services/integration-hub/) that manages connections to external third-party APIs. Features: per- provider rate limiting (100 req/sec default), automatic retries with exponential backoff, AES-256-GCM credential encryption in PostgreSQL, Dead Letter Queue for failed deliveries. Accessed via gRPC IntegrationHubService.

J​

JWT (JSON Web Token)​

The authorization token format used throughout Platform-Kernel. Access tokens: signed with ES256, TTL 15 minutes. Refresh tokens: TTL 7 days. Delegation tokens: TTL 3 600 seconds (configurable). OIDC tokens (RS256): issued by the IAM OIDC provider for third-party OAuth application integration.

K​

KRaft​

The Kafka Raft consensus protocol that replaces ZooKeeper for Kafka cluster metadata management. Platform-Kernel pins Kafka at 3.9.0 in KRaft mode. There is no ZooKeeper dependency.

M​

MFE (Micro-Frontend)​

A frontend application that runs as a remote in the Module Federation 2.0 architecture hosted by ui-shell. Each MFE is independently deployed and loaded at runtime. MFEs communicate with each other via the event-bridge package (browser CustomEvents) and are registered in the Module Registry.

Module​

A self-contained vertical feature built on top of Platform-Kernel primitives. A module has: a Manifest (JSON schema), a remote MFE entry point (remoteEntry.js), declared permissions (what primitives it accesses), and optional backend extensions. Modules are registered via ModuleRegistryService.Register and activated per-tenant via ModuleRegistryService.Activate. A module is the unit of deployment for third-party functionality on the platform.

mTLS (Mutual TLS)​

Authentication at the service-to-service level, where both the client and server present certificates. In production, mTLS is enforced via Istio service mesh in the platform-services Kubernetes namespace. All inter-service gRPC calls are protected by mTLS. TLS 1.3 is the minimum version.

O​

OIDC (OpenID Connect)​

The identity layer built on top of OAuth 2.0, implemented in services/iam/internal/oidc/. Platform-Kernel IAM acts as an OIDC provider, issuing RS256-signed ID tokens for third-party OAuth applications. Discovery endpoint: {OIDC_ISSUER}/.well-known/ openid-configuration.

OpenTelemetry (OTel)​

The observability framework used by all 12 Go services for metrics, traces, and logs. Metrics are pushed to the OTel Collector via OTLP gRPC (port 4317). The Collector forwards metrics to VictoriaMetrics via Prometheus remote write. Traces are forwarded to Jaeger/Tempo.

P​

Primitive​

One of the seven foundational building blocks of Platform-Kernel: Auth, Data, Events, Notify, Files, Money, Audit. Every primitive is implemented as one Go backend service and one @platform/sdk-* TypeScript package. The design philosophy is "everything is a primitive" — every business capability of any module can be reduced to a composition of these seven primitives.

Problem Details (RFC 9457)​

The error response format used by all Platform-Kernel APIs. Every error response has Content-Type: application/problem+json and the structure: { type, title, status, detail, instance, traceId }. The type field is a URI identifying the error category (e.g. https://platform.kernel/problems/not-found).

R​

RBAC (Role-Based Access Control)​

The permission model enforced by the IAM service and Gateway. A user has one or more Roles; each Role has a set of Permissions. The Gateway checks the permission middleware before proxying to upstream services. RBAC policies are stored in PostgreSQL and synced to Valkey cache.

Replay Buffer​

A Valkey-backed message buffer in the Notify service that stores the last 100 WebSocket messages per channel with a 1-hour TTL (WS_REPLAY_BUFFER_SIZE, WS_REPLAY_BUFFER_TTL_SEC). When a WebSocket client reconnects after a disconnect, the server replays all buffered messages in order, guaranteeing no notification is lost during transient connection drops.

Reversal​

An undo of a previously completed wallet transaction. Reversals are supported up to MONEY_REVERSAL_MAX_AGE_DAYS (365 days) after the original transaction. A reversal creates two new journal entries that cancel the original debit and credit. Reversals are not available for hold-related transactions — use Cancel instead.

RLS (Row-Level Security)​

PostgreSQL's built-in mechanism for tenant data isolation. All tables in Platform-Kernel have ROW SECURITY ENABLED. The IAM service and Data Layer set SET LOCAL app.current_tenant_id = ? on each database connection before executing queries. Rows without a matching tenant_id are invisible to the current session.

S​

SSOT (Single Source of Truth)​

A design principle in Platform-Kernel: each piece of configuration or data has exactly one authoritative source. Examples: docker/versions.env is the SSOT for all infrastructure package versions; go.work is the SSOT for Go module versions; kernel-spec.md is the SSOT for what the platform does; CONVENTIONS.md is the SSOT for how the platform is coded.

T​

Tenant​

An isolated organizational unit in Platform-Kernel. A tenant maps to one row in the tenants PostgreSQL table. All data belonging to a tenant is partitioned by tenant_id at every layer: PostgreSQL (RLS), ClickHouse (row policy + WHERE tenant_id = ?), Kafka (SDK- level filtering from JWT), WebSocket channels ({tenantId}: {channel}), S3 path prefix ({tenantId}/{bucket}/). In the B2B2B model, tenants form a three-level hierarchy: Platform Owner → Partner → Client.

TOTP (Time-Based One-Time Password)​

The MFA algorithm implemented in the IAM service, following RFC 6238. TOTP secrets are encrypted in PostgreSQL using AES-256 (key: MFA_ENCRYPTION_KEY). Users receive 10 recovery codes at enrollment (bcrypt-hashed). Recovery codes are one-time-use.

U​

UUID v7​

The identifier format used for all entity IDs across Platform-Kernel (users, tenants, wallets, transactions, records, etc.). UUID v7 is time-sortable: the first 48 bits encode Unix timestamp in milliseconds, enabling efficient B-tree index ordering without a separate created_at sort column.

V​

Vault (HashiCorp Vault)​

The secrets management service (services/vault/) providing the SecretProvider interface. Vault stores JWT signing keys, OIDC RSA keys, MFA encryption keys, domain TLS certificates, and dynamic database credentials. There is no env-variable fallback for secrets (AD-1): if Vault is unreachable at startup, the service calls os.Exit(1) after VAULT_INIT_TIMEOUT_SEC seconds (default: 120). Production deployment uses 3-node Raft HA mode.

VictoriaMetrics​

The metrics storage backend that receives Prometheus remote write from the OpenTelemetry Collector. Dashboards are served via Grafana with the VictoriaMetrics data source. Alert rules are defined in MetricsQL format.

W​

WAL (Write-Ahead Log)​

PostgreSQL's transaction log. Platform-Kernel uses WAL in two contexts: (1) CDC — Debezium reads the WAL via logical replication to capture row-level changes and stream them to Kafka; (2) Audit fallback — when Kafka is down, the Audit Service writes to a audit_wal PostgreSQL table, which is replayed to Kafka when connectivity restores.

Z​

Zero-Debt Policy​

The project-wide quality standard requiring that no technical debt is introduced or left unresolved. Applied to: golangci-lint v2 (0 warnings), markdownlint-cli2 (0 errors), pnpm build (0 broken links), test coverage >80%, no TODO/FIXME in production code paths. All primitives must pass a Freeze Checklist before being marked FROZEN.

See Also​