Overview

This section describes the architectural structure, viewpoints, and engineering patterns used across the Arda platform. It is written for developers and engineers who need to understand how Arda services are designed, decomposed, and implemented.

---

System Structure

The structure section covers how Arda describes and organizes its architecture — the notation it uses, how viewpoints relate to each other, and how the system is decomposed into modules.

Document	Description
Architectural Design Framework	The viewpoints and notation (C4, PlantUML) used to describe the system across different levels of abstraction. Section index.
Functional Decomposition	The Functional Viewpoint in depth: System → Domain → Module → Service → Endpoint criteria, the canonical URL formula, and per-surface naming rules.
Module Concept	How Arda decomposes the system into modules: state encapsulation, service boundaries, and inter-module bindings.
Component Concept	Runtime Components as deployable units packaging one or more Modules; identity, configuration footprint, and the declare/provide IoC pattern.
Viewpoint Mapping	Cross-reference of which viewpoints document which aspects of the system.
Legacy State	Current divergences between the canonical naming and the live system’s URLs and configuration; cardinality-transition and collapse-rule mechanics that govern Module evolution.

---

Design Patterns

The patterns section is a curated catalog of recurring design decisions with implementation guidance. The Design Pattern Index provides a concise summary of all patterns with links to their canonical documentation.

Service Architecture

Patterns governing how individual services and modules are structured.

Document	Description
Data Authority Module Pattern	The primary four-layer module pattern (Protocol Adaptor → Service → Persistence → Proxy) for entities that own and manage a set of entities.
Data Authority Limitations	Known constraints and edge cases of the Data Authority query system.

API Design

Patterns for service boundaries and client-facing contracts.

Document	Description
API Design	URL naming conventions, REST endpoint structure, filtering/pagination, and standard error responses.
Query DSL	The serializable filter/sort/pagination DSL used on /query endpoints, compiled to SQL via Exposed or evaluated in-memory.

Persistence

Patterns for storing, retrieving, and evolving entity state.

Document	Description
Persistence Overview	Landing page for all persistence patterns.
Universe Design	The Universe abstraction: entity collections with consistent CRUD, query, validation, and scoping.
Bitemporal Persistence	Recording both effective-time and transaction-time on every record; correction semantics without data loss.
Parent-Child Persistence	Child collections scoped to a parent; ordering, rank management, and cascade semantics.
Table Mappings	Exposed ORM table definition conventions: columns, records, and composite value mapping.
Exposed ORM Patterns	Flyway migrations, Exposed DSL usage, and DBIO functional effect patterns.

General Backend Patterns

Cross-cutting patterns applied throughout the Kotlin backend.

Document	Description
Backend Implementation Patterns	Comprehensive reference: Ktor module wiring, CRUDQ implementation, service patterns, and testing conventions.
Exception Handling	AppError hierarchy, Result<T> propagation, and Ktor StatusPages normalization.
Functional Programming at Arda	FP philosophy: immutability, Result, DBIO, state machines, and composability.
Observer and Notification Patterns	Async notification emission, observer wiring, and testing patterns.
Naming Conventions	Naming rules for Kotlin code, Kubernetes resources, Helm charts, and Docker images.
application.conf Structure	HOCON file layout: Component-level block, functional-hierarchy tree with domains/modules/services/endpoints wrappers, per-Module include shape, declare/provide/bind flow.

Frontend

The frontend reference moved to its own top-level section under current-system/user-interface/. The links below point there.

Document	Description
Frontend Application Architecture	Next.js BFF structure, React component model, authentication integration, and TypeScript conventions.
User Interface — Section Index	Landing page for all frontend system documentation: architecture, data flow, editing and concurrency.