Design Pattern Index

A curated index of key patterns and conventions across Arda’s documentation. Each entry gives a brief conceptual summary and pointers to canonical documentation and implementation details.

Implementation details, code paths, and “use when” guidance live in Implementation Patterns. FP philosophy is in Functional Programming.

Writing Kotlin? The binding language conventions — return types, the error channel, construction, persistence shape, the DBIO transaction contract — are in Kotlin Coding Standards, which is filed under process rather than here. If this is your first Arda backend change, start from Backend Onboarding, which sequences both sets.

Domain Modeling and References [GEN]

Values vs Entities — Identity-bearing, mutable state is Entity; pure data is Value. Drives ownership boundaries and persistence decisions.
Journalled Entities — Entity updates create immutable records in a lineage; supports “latest as-of” and historical/audit access.
Arda Domain Name (ADN) — URN-like naming for universes, entities, and specific records/versions; distinguishes pinned vs floating references.
Entity Reference URI — URI-like structure for cross-module addressing; conventions for pinned (…/rid/…) vs floating references.
Reference Data Lifecycle — Slow-changing entities with explicit lifecycle states (Draft/Published/Archived) and staged changes.
Edit–Draft–Publish — Drafts stored out-of-line from bitemporal history; publishing creates a new bitemporal record.
Inter-Entity Relationship Patterns — Explicit patterns: extension/delegation, aggregation, composition/parent-child, association via join entity.

Persistence and Data Access [BE]

Bitemporal Persistence — Both effective (business-valid) time and recorded (transaction) time tracked per record; supports correction without data loss.
DBIO (Functional Effect) Pattern — DB operations are composable suspendable values (DBIO<R> = suspend () -> Result<R>); separates description from execution.
Universe Pattern — Entity collections as Universe<Payload, Metadata> with persistence mapping, validator, and universal condition; consistent CRUD + query + history.
Validation Layering — Payload-level validation (EntityPayload.validate) + universe-level validation (Validator), orchestrated by AbstractUniverse.
Scoping via Metadata + Universal Condition + Validator — Tenant- or parent-scoped access enforced by carrying scope in metadata, applying a universe-wide filter, and rejecting mismatched metadata.
Parent–Child Persistence (Ordered vs Unordered) — Child collections as universes scoped to the parent; rank/line ordering when insertion/reorder matters.
Exposed Table/Record Mapping Patterns — Table configuration + table columns + record type + universe + SQL migrations.
Composite Value Mapping via Components — Nested value-object properties mapped to multiple DB columns; “all-null-or-none-null” invariants for optional composites.
Editable Data Authority Persistence — Draft storage + publish semantics around universes for reference data.

Module and Service Architecture [BE]

Data Authority Module Layering — Protocol adaptors, services, persistence, and proxies; services own transaction boundaries. See Data Authority Pattern.
Data Authority Endpoint/Service/Universe Split (CRUDQ) — Standard Create/Read/Update/Delete/Query with consistent separation of concerns and reusable base types.
Ktor Module Wiring Pattern — Module bootstrapping in Module.kt with explicit configuration + endpoint locator + authentication.
Module Concept (State Encapsulation + Bindings) — Modules encapsulate state behind services and interact via endpoints, data types, references, and bindings. See Module Concept.
Component Concept (Deployment Packaging + Provisioning) — Components are the deployable units that package one or more Modules and provision the resources those Modules declare; orthogonal to the functional naming hierarchy. See Component Concept.
application.conf Structure — HOCON file layout: component { ... } plus a domains { ... } tree with domains/modules/services/endpoints wrappers; per-Module include shape; declare/provide/bind flow. See application.conf Structure.

API and Query Patterns [BE]

Public URL Naming — <Purpose>.<Infrastructure>.<capability>.arda.cards/<major-version>/<endpoint-name>/…; canonical live.* hostnames; kebab-case endpoint names. See API Design.
Filtering/Query Endpoint — /query sub-routes with POST (new query) and GET /query/{page} (cursor); filtering/sorting/pagination via Query DSL.
Query DSL + Visitor Compilation — Serializable filter/sort/pagination DSL; compiled to SQL (Exposed) or evaluated in-memory; encoded cursors. EntityServiceConfiguration builds structured locator translators from @Serializable entity classes, enabling JSON field-name locators alongside legacy column-name locators. See Query DSL.
Standard API Error Responses — Exceptions normalized to AppError; consistent ErrorResponse { responseMessage, code, details } via Ktor StatusPages. See Exception Handling.
Functional Error Propagation — Result<T> + extension combinators (flatMap, collectAll, notNull, orElse); keeps error handling explicit and composable.

Frontend Data and State [FE]

See the Frontend Data and State Patterns section index for an overview and current status.

Context Scope by File-Path Hierarchy — A provider lives at the narrowest directory containing all its consumers; component-local context in the component’s folder, app-wide context in root hooks/. See State and Context Conventions.
Atomic Providers exposing Hooks — One concern per context; export a provider and a useState-shaped hook (or named operations for richer surfaces), never the raw context object; mutator defaults throw when used outside their provider. See State and Context Conventions.
Persist via useLocalStorage, not localStorage — Device-local view state goes through one SSR-safe, reactive, cross-tab useLocalStorage hook (which also replaces redux-persist); components never touch localStorage directly. Used sparingly — genuine user settings persist in the API (a future settings service), not on the device. Redux is being retired in favor of this context-and-hooks pattern. See State and Context Conventions.

Security and Authentication [GEN]

Realms + Scopes (RBAC/ABAC Framing) — Static realms and OAuth2 scopes for coarse RBAC; “application scopes” (e.g., tenant) for ABAC. See Security: Realms.
Cognito Authentication Service — Authn via Cognito user pool + resource server + web and M2M clients. See Security: Cognito.
JWT Claim Conventions — Expected Cognito ID/access token payload claims and custom attributes (custom:tenant, custom:role). See Security: JWT Payload.
Hybrid Auth (Demo202509) — BFF validates user JWT, calls backend with API key bearer token; user/tenant/role passed via trusted headers. Transitional/demo only. See Functional: Hybrid Auth.
Secrets Vault — OAM secrets in a shared 1Password vault; access gated to authorized humans/processes. See OAM: Secrets Vault.

Runtime, IaC, and Operations [GEN]

Runtime Containment Model — Root Services, Infrastructure (shared), Partition (purpose-scoped), Component (deployment unit); consistent simple names and FQNs.
DNS Hierarchy Pattern — DNS responsibilities split across registrar (global), root/platform zones (capabilities), infrastructure zones, and purpose-level targets.
CDK Construct Pattern — Reusable constructs with Configuration vs Props vs Built; build exposed; inputs validated up front.
CDK Stack Pattern — Stacks with Configuration/Props/Built plus explicit export keys/definitions/values; publish() step creates CloudFormation outputs.
IaC Layered Architecture — script → instances → apps → stacks → constructs dependency direction, layer responsibilities, and reuse model for the Arda-cards/infrastructure codebase. See IaC Functional Design and the Infrastructure Patterns section.
Service Monitoring — Availability via API Gateway 5xx signals, NLB health, and scheduled API tests; alerting layered by failure class.

Engineering and Delivery Practices [GEN]

Multi-Repo Kotlin Development (Gradle) — Temporary additive-only local packages or Gradle composite builds (includeBuild) for cross-repo iteration.
API Testing with Bruno — Collections + workflows; environments driven from 1Password-managed env files; OAuth2 token flows via native OAuth2 support or explicit “get token” requests.
Gradle Project Workflow Conventions — Local build commands, artifact publishing/versioning, and staged deployments with explicit approval gates.