Naming Conventions

Formats and terminology for labels, routes, metrics, and error codes across Plat5.

Project Terminology

Plat5 — Brand and main product: gateway, identity, route registry, contracts (platform runtime).
Plat5 Auth — Optional reference OIDC IdP (separate product).
Service — Any unit of code that runs with Plat5 (e.g. gateway, identity, widgets).
Platform service — Plat5 runtime units: gateway, route-registry, identity, audit.
Business service — Use-case service behind Plat5: domain APIs.
IdP — External identity provider (JWT issuer). Not part of Plat5 (optional Plat5 Auth is a separate product).

Scope of Plat5

Plat5 owns the directory of people (ids linked to IdP subjects, display names), organizations, members, service accounts, credentials (API keys and sessions), audit, the route registry, and the user-facing gateway. Login is the IdP. Access to individual resources is an optional policy engine’s. See model.md.

Identity domain nouns

Concept	Formal name	Notes
Context that holds memberships	Realm	The directory or an organization
Where every person lives	Directory	One. Private: customers cannot list or search people
Global person	User	`user_id`, Plat5’s id, linked to one or more IdP subjects
Isolation boundary	Organization	Do not call it tenant.
An identity’s standing in a realm	Membership	A person’s in the directory, or a member in an org
Org principal	Member	User or service account in an org; wire id `member_id`
What a member holds	Role	Deployment-defined slug on a member; its labels come from the roles file (`roles.md`). Plat5 names no roles.
Route requirement	Label	Opaque `[a-z0-9:._-]+`. Routes require them (`required_labels`); roles grant them. Keys and sessions carry their member’s. Not `scope`: route `scope` is `public` / `user` / `organization` / `member`.
Non-human org identity	Service account	Created under an organization; always has a member row
Credential	API key	A user key (the person’s own) or a member key. One credential table with sessions
Short-lived org credential	Session	One active user member, one org. Kind `session` of the same credential

Rejected service names: org-service, orgs, tenants, tenancy, memberships (alone), rbac, authz, accounts, api-keys (as a standalone platform service).

The identity control-plane service is identity (service.name: identity).

Service Names

Format: kebab-case
Examples: identity, gateway, route-registry
Match the service directory name
Used in service.name container label and OTel resource attribute

Service Namespaces

Full table and labels: container-labels.md. Identity backend uses identity; gateway stays edge.

Service	`service.namespace`
`identity`	`identity`
`gateway`, `route-registry`	`edge`
`audit`	`audit`
Business APIs	`api` (etc.)

When changing labels: update compose labels and OTEL_SERVICE_NAMESPACE together.

HTTP Routes

kebab-case path segments: /user-profiles
No path version segment. No /api prefix.
- Public: /public/...
- Internal (private network, not on the gateway): /internal/...
Resource names are plural nouns: /widgets, /users, /organizations, /members
Identity list query/body: lists.md. Business services may copy it; they are not required to.
Actions use HTTP methods, not verbs in paths:
- POST /widgets — create
- GET /widgets/{id} — read
- PUT /widgets/{id} — update
- DELETE /widgets/{id} — delete

Path patterns (identity)

The first path segment is the subject.

Surface	Pattern
User	`/users/{user_id}/...`
Organization	`/organizations/{organization_id}/...`
Member	`/members/{member_id}/...`
Internal (not on the gateway)	`/internal/credentials/validate`, `/internal/lifecycle-events`

Audit follows the same pattern: /organizations/{organization_id}/audit-events and /users/{user_id}/audit-events public, /internal/events/{request_id} internal (audit.md).

Those are identity’s own URLs. The gateway edge does not put the subject in the path.

Edge	Scope	Upstream fills
`/user/...`	`user`	`{subject.user_id}`
`/org/...`	`organization`	`{subject.organization_id}`
`/member/...`	`member`	`{subject.member_id}` (and `organization_id` if the template needs it)

There is no /api prefix. A route that needs the subject sets upstream. The match path does not contain a param whose name is a subject field of that scope.

Scopes and subject fill: gateway-contract.md. Full identity API: identity.md.

Subject

The route scope names the subject. upstream fills it. The client path does not. Full contract: gateway-contract.md.

Scope	Subject fields
`public`	none
`user`	`user_id`
`organization`	`organization_id`
`member`	`organization_id`, `member_id`

Always (all scopes): X-Request-ID, traceparent. Services are not told the caller’s role or labels. See gateway-contract.md.

Log Fields

Format: snake_case
Common: request_id, user_id, organization_id, member_id, duration_ms, error_kind
Credential (gateway request line): auth_type, key_prefix (display prefix, never the key). See telemetry.md
Service-specific fields should be namespaced: auth_provider, db_operation

Metric Names

Format: snake_case
Structure: <domain>_<entity>_<unit>
Examples: http_requests_total, http_request_duration_seconds, db_operations_total, process_resident_memory_bytes

Error Codes

Format: UPPER_SNAKE_CASE
Full list: api-errors.md

Environment Variables

Format: UPPER_SNAKE_CASE
Group by prefix when related: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT
Examples: PORT, DATABASE_URL, DEPLOYMENT_ENV

Database

Table names: snake_case, plural: identities, memberships, credentials, organizations
Column names: snake_case: created_at, updated_at, user_id, organization_id, member_id, service_account_id
Foreign key columns: <entity>_id
New identity row IDs: ULID strings (user_id, organization_id, member_id, service_account_id, key ids)

Doc	Role
`identity-boundary.md`	Authn vs org context vs resource authz
`identity.md`	Identity service API
`container-labels.md`	Namespace values
`gateway-contract.md`	Headers and service rules
`routes.md`	Route scopes and publish
`lists.md`	Identity list pagination (optional for business APIs)