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.
Module Concept	How Arda decomposes the system into modules: state encapsulation, service boundaries, and inter-module bindings.
Viewpoint Mapping	Cross-reference of which viewpoints document which aspects of the system.

---

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.

Frontend

Patterns for the Next.js BFF and React frontend.

Document	Description
Frontend Application Architecture	Next.js BFF structure, React component model, authentication integration, and TypeScript conventions.