Skip to main content

Glossary

One stable anchor per term. Cite a definition by linking to its slug — docs.planetb2b.com/reference/glossary#tenant — instead of restating it.

Terms are alphabetised. Each entry also lists where the term is implemented (schema, module, package) and links to the rule, spec, or module page where it lives in detail.

audit-entry​

A row in the audit schema representing a security-relevant action. Written via @constellation-platform/audit (auditCritical() for security-critical mutations — writes the row AND publishes an audit.entry.created outbox event in the same transaction) or @constellation-platform/db (auditAction() for routine entries — writes the row only). Audit entries form a hash chain — each row's hash field includes the previous row's hash, so any tamper produces a verifiable break.

catalog-entry​

A product or service listing in the Catalog module. Each entry has a lifecycle (draft → published → archived), a position in the configured taxonomy (see taxonomy), and may carry pgvector embeddings for semantic search.

  • Schema: catalog.entries
  • Module: Catalog
  • Events: catalog.entry.created, catalog.entry.updated, catalog.entry.deleted, catalog.entry.status_changed — see Domain events.

caveats​

JWT claim listing data-handling caveats (e.g. NOFORN, REL TO …). Optional defence-extension claim — present only on tenants that opt into classification-aware access control. See classification and clearance.

  • Source of claim: JWT issued by the auth provider.
  • Type: string[].

classification​

Optional sensitivity level on data and JWT claims (e.g. UNCLASSIFIED, RESTRICTED, CONFIDENTIAL, SECRET, TOP_SECRET). Combined with clearance and caveats, enables row-level access control on tenants that opt in.

  • JWT claim: classification (optional).
  • Per-row: classification column on classification-scoped tables.

clearance​

Optional defence-extension JWT claim representing the user's maximum classification level. Compared against the row's classification by the auth provider's permission evaluator.

  • JWT claim: clearance (optional).

correlation-id​

UUID propagated across requests, audit entries, and outbox events that all derive from one user-initiated action. At the entry route handler, getCorrelationId(request) extracts the value from the incoming x-request-id header — or generates a new UUID if the header is absent — and the handler then threads it explicitly through tools, services, repositories, and into the audit + outbox helpers. Critical for forensic replay: given a correlation ID, you can find every audit row + every published event that originated from one action.

  • Source: x-request-id header on the incoming request, or a generated UUID when the header is missing.
  • Constant: CORRELATION_HEADER from @constellation-platform/db/correlation.
  • Read with: getCorrelationId(request) from @constellation-platform/auth-next (re-exports the helper from @constellation-platform/db/correlation).

criterion​

A single acceptance criterion attached to a deliverable or task. Reviewers tick criteria off when accepting; rejecting a deliverable requires citing which criteria failed.

  • Schema: projects.deliverable_criteria, projects.task_criteria.

delegate​

A user who has been granted permission to act on another user's behalf within a specific scope (e.g. approve deliverables for a project while a reviewer is on leave). Implemented in the Project Tracker module.

  • Schema: projects.delegations.

deliverable​

A reviewable artefact submitted within a project — typically a document, file, or marked-complete checklist. Has a status lifecycle: DRAFT → SUBMITTED → UNDER_REVIEW → ACCEPTED | REJECTED | REVISED. Each deliverable has zero or more criteria.

  • Schema: projects.deliverables, projects.deliverable_criteria.
  • Events: projects.deliverable.* — see Domain events.

domain-event​

A typed, append-only message published to the outbox representing a fact about something that already happened. Naming follows <schema>.<entity>.<verb-past-tense> (see event-naming). Cross-module communication goes through events, not HTTP calls (see no-cross-app-imports).

  • Publisher: publish(tx, ...) from @constellation-platform/events.
  • Index: Domain events.

epic​

A task with issueType = EPIC that groups base-level tasks via their epicId (Jira's Epic Link / parent). The epicId edge is tenant-scoped: as of PT-446 an epic may parent children in a different project within the same tenant, so an epic can span projects. On a task the caller can read, a referenced epic that lives in a project the caller cannot read is returned redacted — sentinels + isCrossProject: true, never the real key/title (the PT-283 reference-redaction pattern). Tasks in unreadable projects are themselves omitted from listings, not returned-and-redacted; redaction applies to the epic reference, not to child rows. The epic edge is distinct from the same-project sub-task edge (parentTaskId, terminal at one level). The project-scoped GET /api/projects/:id/tasks?epicId= filter lists an epic's children within one project; a tenant-scoped cross-project listing of an epic's children is tracked as PT-491.

  • Schema: projects.tasks (epic_id, issue_type).
  • Introduced: PT-375 (same-project); widened cross-project in PT-446.

gate​

A review checkpoint between stages in a stage-gate workflow. Reviewers vote PASS, FAIL, WAIVE, or HOLD; PASS auto-progresses the stage.

  • Schema: projects.gates, projects.gate_reviews.
  • Events: projects.gate.reviewed.

hash-chain​

Cryptographic chain over the audit schema. Each row's hash is H(prev_hash || canonical_payload). Any tampered or out-of-order row breaks the chain at the next verification scan. See audit-entry and the Tamper-evident chain page of the audit-log spec.

idempotency​

Property of an event handler that processing the same event multiple times yields the same result as processing it once. Required because the outbox dispatcher may re-deliver an event if the subscriber acknowledged late. Idempotency is achieved with a deduplication table keyed on event_id or by upserting on a natural key.

  • Pattern: events.processed deduplication table per subscriber.

issue​

A bug, defect, support ticket, or service request in the Project Tracker module. Distinct from a task — issues are unplanned (something broke), tasks are planned (something was scheduled). Issues have severity (CRITICAL | HIGH | MEDIUM | LOW), an SLA-based first-response and resolution deadline, and may be promoted to a task.

  • Schema: projects.issues.
  • Events: projects.issue.* — see Domain events.

locale​

A BCP-47 language-and-region tag that identifies the rendering preferences for a request — UI strings, date and number formatting, currency symbol, plural rules. Constellation uses full regional tags only (en-US, en-GB, it-IT, de-DE, fr-FR); base-language tags (en, it) are not in the supported set because Intl formatters produce inconsistent output across runtimes when the region is left implicit.

  • Type: Locale from @constellation-platform/i18n.
  • Source on the wire: the constellation-locale cookie, scoped to the apex domain so all three Vercel zones see it.
  • Tenant policy: tenants.default_locale plus tenants.enabled_locales; see tenant-locale-policy.
  • Full design: Multilanguage (i18n) Specification.

locale-resolution​

The rule that decides which locale a given request renders in. Order: cookie (validated against the tenant's enabled_locales) → user preference → tenant default → Accept-Language (unauthenticated only) → platform default (en-US). A cookie that fails the tenant check is rejected and overwritten on the response so the bad value does not persist. Implemented in resolveLocale() (pure) and applied via the localeResolver hook on createConstellationAuthMiddleware.

  • Implementation: resolveLocale() in @constellation-platform/i18n; resolveRequestLocale() in @constellation-platform/auth-next/locale.
  • Forwarded to handlers as: the x-constellation-locale request header (gated behind trustForwardedHeaders).

module​

A self-contained vertical slice of the platform with its own database schema, API surface, and code base under apps/. The current modules are Directory, Catalog, and Project Tracker. Modules communicate only via domain events and typed service contracts — see no-cross-app-imports and module-isolation.

organisation​

A company that participates in a tenant — typically a buyer, supplier, or service provider. Organisations are containers for users and have type, verification status, and credentials.

outbox​

Postgres table (events.outbox) that holds domain events written transactionally with the originating mutation. A polling dispatcher reads undispatched rows and delivers them to subscribers. Combined with subscriber-side idempotency, this gives at-least-once delivery without distributed transactions.

  • Schema: events.outbox.
  • Publisher: @constellation-platform/events (publish()).
  • Dispatcher: polling cron in each consuming app.

permission​

A named capability check (organisation.read, task.update, audit.read.own, …). Permissions are stored in identity.permissions and assigned to roles; the auth-core matchPermission() helper evaluates them at runtime. The .own suffix narrows a permission to records the actor created/owns.

  • Schema: identity.permissions, identity.role_permissions.
  • Helper: matchPermission() from @constellation-platform/auth-core.

programme​

The top of the Project Tracker hierarchy — a long-running container of related projects (e.g. "Constellation Platform Development" is the dogfood programme that contains the Directory, Catalog, PT, etc. projects).

  • Schema: projects.programmes.
  • Events: projects.programme.progress_updated.

project​

A bounded unit of work within a programme, containing stages, tasks, deliverables, and issues.

  • Schema: projects.projects.
  • Events: projects.project.* — see Domain events.

RLS​

Row-Level Security. Postgres feature that filters rows based on a per-connection setting. Constellation uses RLS to enforce tenant isolation — every tenant-scoped table has a policy USING (tenant_id = current_setting('app.tenant_id', true)::uuid).

role​

A named bundle of permissions assigned to a user within a scope (tenant, organisation, project). A user can have multiple roles; the union of their permissions applies.

  • Schema: identity.roles, identity.user_roles, identity.role_permissions.
  • Events: directory.role.*.

schema-per-module​

Isolation pattern where each module owns one Postgres schema (identity, catalog, projects) within a single shared database, and is the only writer of that schema. Cross-module reads go through the module's API or events — never via cross-schema joins.

stage​

A phase of a project, typically separated by gates. Stages contain tasks and deliverables. Stages have a status lifecycle (planned → in-progress → completed) and progress automatically when their gate passes.

  • Schema: projects.stages.
  • Events: projects.stage.progressed.

subscriber​

A consumer of domain events — an event handler in another module (or the same module) that runs on each event delivered from the outbox. Subscribers must be idempotent.

  • Helper: subscribe() from @constellation-platform/events.

tenant-locale-policy​

The set of locale-related fields a tenant configures: default_locale, enabled_locales, time_zone, and currency. Defaults preserve English-only behaviour ('en-US', ['en-US'], 'UTC', 'USD'). A DB CHECK enforces default_locale ∈ enabled_locales plus a non-empty, no-NULL invariant on the array. Edited by tenant admins on the tenant detail page in Directory.

  • Schema: identity.tenants (columns default_locale, enabled_locales, time_zone, currency).
  • Validation: LocaleSchema / TimeZoneSchema / CurrencySchema in apps/directory/src/lib/schemas/tenant.schema.ts.
  • Read by: localeResolver on createConstellationAuthMiddleware; per-app server actions on cookie write.

task​

A planned unit of work in the Project Tracker module. Has an assignee, due date, status, and progress. Distinct from an issue: tasks are planned ("we will do X by Y"), issues are unplanned ("X is broken").

  • Schema: projects.tasks.
  • Events: projects.task.* — see Domain events.

taxonomy​

A hierarchical classification tree for catalog entries. Stored as Postgres LTREE so any prefix query is fast. Configurable per tenant — supported standards include UNSPSC (general commerce), ETIM (industrial), NATO FSC (defence), CPV (EU public procurement), or custom hierarchies.

  • Schema: catalog.taxonomy_nodes.
  • Events: catalog.taxonomy.* — see Domain events.

tenant​

The top-level isolation boundary in Constellation. A tenant is a single customer organisation (or in the dogfood case, "Planet B2B" itself). Every tenant-scoped table has a tenant_id column, and every query runs under app.tenant_id set from the JWT — see tenant-context.

  • Schema: identity.tenants.
  • JWT claim: tenant_id.
  • Module: Directory.

tenant-id​

The UUID identifying a tenant. Set as a Postgres connection setting (app.tenant_id) for the duration of a request, where it's read by RLS policies on every query.

user​

An account in the Directory module — typically a person, but service accounts also exist. Users belong to zero or one organisation and have one or more roles.

  • Schema: identity.users.
  • Events: directory.user.*.