Architectural Design Framework

Arda’s system design relies on multiple viewpoints to capture its different aspects and provide a productive environment for engineers. This document describes the intent and structure of each viewpoint.

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.

The viewpoints we adopt correspond to the Inputs & Outputs of these transformations.

Architectural Viewpoints

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.

Product Concepts

Enterprise : A legal entity that does business with Arda Systems and has a contractual agreement to use or provide services.

Persona : A human that interacts with the system on behalf of an Enterprise. Characterized by access method (desktop, mobile, barcode scanner) and role (Administrator, Shop Operator, Facility Manager).

External System : An information system that interacts with Arda’s system on behalf of an Enterprise via machine-to-machine API. May be a Server system (provides capabilities to Arda) or a Client system (uses Arda’s capabilities).

Application : A human-accessible interface to the system (web, mobile, or specialized device software).

API : A machine-accessible interface, preferably REST over HTTP.

Descriptions

The Product View point described the capabilities and behaviors of the platform from an external point of view. The descriptions it provides are:

• Features: Descriptions of the value and functionality that the platform provides to its users. Features are organized in a 3 level hierarchy with Domain, Area and Feature

• Use Cases: Descriptions of how users (or other systems) interact with the platform. Use cases follow the organization of Features with multiple Use Cases describing the different ways a Feature is exercised. Use Cases are further described in terms of Scenarios where an Scenario describes a specific path or sequence of interactions for the use case. Different scenarios show the standard way a use case is exercised, error conditions, alternative paths, etc..

Functional Viewpoint

Decomposes the system into smaller parts that together provide the overall functionality. The functional decomposition defines elements that minimize coupling among them and maximizes cohesion within an element.

The functional decomposition is organized as a containment hierarchy:

System : The complete set of capabilities of a product, decomposed into Domains.

Domain : A cohesive set of information, workflows, and functions, composed of Applications, Modules, and Capabilities.

Module : A subset of a Domain that is internally cohesive and related to other modules through uni-directional dependencies. A Module depends on other modules if it needs them to perform the functions its services offer. Modules can be nested inside other Modules.

Service : A collection of algorithms and information models that implement functionality for one or multiple Endpoints belonging to a Domain or a Module inside a domain.

Endpoint : The mechanism to access a well-defined function or a part of the state of the system. Endpoints may be Request/Response or Streaming. Endpoints must have a formal specification (OpenAPI or gRPC for request/response; protobuf or JSON schema for streaming).

Note

Endpoints are the only, exclusive way to access the functionality of a Module and therefore the system.

Capability : A closely related set of algorithms, information models, and designs expressing a common cross-cutting concern. Never mapped independently into runtime elements — always embedded in Modules or Applications.

Artifacts Viewpoint

The digital artifacts that define, build and deploy the platform.

They include

• source files (code, configuration, scripts, etc.)
• build artifacts (jar, npm modules, images, …)
• deployment artifacts (helm charts, cdk applications, …)
• configuration values (values for environment variables, identities, secrets, …)
• underlying tools used to create, transform and manage the above artifacts.

Source files

All sources are managed by GitHub in a multi-repo structure. Build systems adopted:

• Java/Kotlin: Gradle
• Node/TypeScript: npm
• Python: poetry
• K8s Manifests: Helm
• Docker images: Docker
• CI/CD: GitHub Actions
• Cloud Resources: AWS CDK v2
• Documentation: MkDocs

Key concepts: Organization, Repository, Project, Package, File, Export.

Describes deployable artifacts produced from sources. Artifact types:

• Library: A jar (Maven), npm module, or Python package used 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. Key concepts:

Platform : The complete set of runtime resources that together realize system functionality.

Cloud Provider : An entity supplying resources (AWS, Coda, GitHub, Short.io, GoDaddy, Documint).

Component : The smallest independently deployed unit. May include resources from multiple technologies (API Gateway routes, Helm charts, SQL scripts).

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.

Technology Viewpoint

The Arda Platform is built using multiple technologies targeted to the different capabilities that the system provides. These technologies are largely organized in three categories or layers, each with their own stack of technologies and tools:

Infrastructure Layer : The resources that support all the capabilities of the system: Compute, Communication, Storage, Ingress/Egress and OAM. It is implemented using AWS Services and resources, K8s Resources and other capabilities (e.g. Sentry). It is built using a combination of CDK (Typescript stack), CloudFormation, Helm and other tools.

Back End Layer : The Code and Configuration that deploys and configures services running in Arda’s cloud environment, typically K8s Deployments, Services, Ingress, etc. Its technology stack is mostly built on a JVM stack with Kotlin its primary language.

Front End Layer : The Code and Configuration that directly supports

OAM Viewpoint

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

Notation

Diagrams use 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.