Architectural Design Framework

Arda’s system design relies on multiple viewpoints to capture its different aspects and provide a productive environment for engineers. This page is the entry point for the System Structure section: it states the foundational architectural decisions, names the viewpoints used to describe the system, and points to the per-viewpoint pages where each is developed in depth.

Foundational Decisions

Arda’s system architecture rests on six early decisions that are worth making explicit:

1. The bulk of the system is deployed in AWS cloud, using other ancillary cloud services where appropriate (e.g., Documint).
2. User access is through browsers and mobile devices over the public internet, including non-traditional devices (e.g., barcode scanners).
3. The system is built as a structured set of loosely-coupled elements with well-defined capabilities and strict state encapsulation. Interactions are through well-defined interfaces without implicit sharing of internal state.
4. The system must be easily duplicated when provided with a set of resources to support independent development, testing, and verification.
5. All items that go into building and deploying the system are versioned and change-tracked. All changes require review and approval by a team member other than the author.
6. Development avoids manual engineering intervention in building and deploying the system. Building and deploying is completely reproducible given a set of configuration parameters.

Development as a Sequence of Transformations

Development can be viewed as a sequence of transformations:

• Design: Transform desired capabilities into functional elements with defined behaviors and internal state.
• Implementation: Transform design elements into source code and configuration that computing tools can accept.
• Building: Transform implementation results into deployable artifacts (images, packages, scripts).
• Deployment: Install artifacts onto available resources (e.g., AWS accounts).
• Operation: Continuously configure, monitor, diagnose, secure, and manage the running system.

The architectural viewpoints correspond to the inputs and outputs of these transformations.

Architectural Viewpoints

Each viewpoint describes one slice of the system. Read this section for the summary of each viewpoint; follow the link in each row for the per-viewpoint deep treatment.

Product Viewpoint

Describes how the product interacts with its environment and users. The complete Arda platform is treated as an opaque element; the description centers on external entities: Enterprises, Personas, External Systems, Applications, APIs.

The Product viewpoint produces two kinds of descriptions:

• Features — descriptions of the value and functionality the platform provides to its users. Features are organized in a three-level hierarchy: Domain → Area → Feature.
• Use Cases — descriptions of how users (or other systems) interact with the platform. Use cases follow the organization of Features; multiple Use Cases describe the different ways a Feature is exercised. Use Cases are further described in terms of Scenarios.

See the product documentation for the catalog of features and personas.

Functional Viewpoint

Decomposes the system into the parts that together provide the overall functionality. The decomposition aims for minimum coupling between elements and maximum cohesion within an element.

The hierarchy is System → Domain → Module → Service → Endpoint. Each level has a specific architectural role:

• System — the complete set of capabilities of a product. The Arda system itself.
• Domain — a collection of capabilities closely related from a functionality or dependencies point of view. Primarily a naming and grouping unit.
• Module — declares the resources it requires and encapsulates its state. The minimum independently versionable and deployable unit.
• Service — entry point for execution and the boundary of a transaction. Future-facing: the unit at which fine-grained authorization (ABAC) will be enforced.
• Endpoint — protocol-bound surface that exposes a Service’s operations. Defines the authentication mechanism. A single Endpoint groups multiple operations (a sub-tree of HTTP routes), not a single operation.

The full description of each level, the canonical URL formula derived from the hierarchy, and the per-surface naming rules (HOCON, Helm, CloudFormation, Ktor) live in Functional Decomposition.

Orthogonal to the functional hierarchy, the Runtime Component is the deployable unit that packages one or more Modules and provisions or binds the resources those Modules declare. A Component is never part of a functional URL or any name a Module exposes — it has its own configuration footprint but does not participate in the functional naming hierarchy.

Sources Viewpoint

The digital artifacts that define the system — source files, configuration values, scripts, and the tools that consume them. Sources are organized into Repositories, Projects, Packages, and Files. The build systems adopted at Arda are:

• Java / Kotlin → Gradle
• Node / TypeScript → npm
• Python → poetry
• Kubernetes manifests → Helm
• Docker images → Docker
• CI / CD → GitHub Actions
• Cloud resources → AWS CDK v2
• Documentation → Astro Starlight

Artifacts Viewpoint

The deployable artifacts produced from sources. Each artifact has a type that determines how it is consumed and deployed:

• Library — a jar (Maven), npm module, or Python package consumed as a dependency.
• Image — a Docker image deployed to a container runtime.
• Chart — a Helm chart describing a complete set of K8s resources.
• CDK Application — an AWS CDK Node/TypeScript application that creates AWS resources.

Arda uses GitHub Package Registries to store Docker images, Maven jars, and Helm charts.

Runtime Viewpoint

Describes the resources that together realize system functionality. The hierarchy is Platform → (Infrastructure ∪ Root ∪ OAM) → Partition → Component → Resource. Key concepts:

• Platform — the complete set of runtime resources realising system functionality.
• Cloud Provider — an entity supplying resources (AWS, Coda, GitHub, Short.io, GoDaddy, Documint).
• Component — the smallest independently deployed unit. Packages one or more Modules from the Functional Viewpoint plus the resources they need (provisioned by the Component).
• Partition — a set of runtime resources providing compute, network, ingress/egress, and storage for Components. Different partitions have different security, reliability, and performance requirements.
• Infrastructure — a collection of shared resources used by multiple Partitions. The main unit of cost and governance. Two types: Production and NonProduction.
• Root — global resources shared by the complete platform (root DNS, e-mail domains).
• Resource — a capability needed for system execution: Compute, Network, Storage, Ingress/Egress, OAM, or External Services.

See Platform Structure for the per-Partition layout and naming conventions.

Technology Viewpoint

The Arda Platform is built using multiple technologies targeted to the different capabilities the system provides. They are organized in three layers:

• Infrastructure Layer — resources supporting all system capabilities: Compute, Communication, Storage, Ingress/Egress, OAM. Implemented with AWS Services and resources, K8s resources, and others (e.g. Sentry). Built using CDK (TypeScript stack), CloudFormation, Helm, and ancillary tools.
• Back-End Layer — code and configuration deploying and configuring services in Arda’s cloud environment, typically as K8s Deployments, Services, Ingress, etc. Predominantly a JVM stack with Kotlin as the primary language.
• Front-End Layer — code and configuration that supports browser- and mobile-based access to the platform.

OAM Viewpoint

Describes how the system is operated, administered, and maintained — provisioning, configuration, monitoring, diagnosis, security, and cost management.

Section navigation

Page	What it describes
Functional Decomposition	The Functional Viewpoint developed in full: criteria for each level, the canonical URL formula, per-surface naming rules, and the Component-vs-Module orthogonality.
Module Concept	Module-level deep dive: cohesion, state encapsulation, interaction mechanisms (Endpoints, References, Data Types, Bindings), and the shared-library considerations across Kotlin/TypeScript ecosystems.
Component Concept	Runtime Components as the deployable units that package one or more Modules and provision the resources those Modules declare. Identity, configuration footprint, and the declare/provide IoC pattern.
Viewpoint Mapping	Cross-reference of which viewpoints document which aspects of the system, with concrete pointers from functional concepts to source code, artifacts, and runtime resources.
Legacy State	Current divergences between the documented canonical naming and the live system’s URLs, configuration, and HOCON structure. Includes the cardinality-transition and collapse-rule mechanics that govern migration.

Notation

Diagrams use the C4 Model and UML notation. UML is used for clarity over strict formal semantics.

This framework is influenced by the 4+1 architectural view model, the C4 Model abstractions, and the Backstage Software Catalog system model.