Design Principles

Atomic Field Design

ADS is designed with atomic fields — structured, discrete values rather than free-text wherever possible. This is a core principle of the standard.

Why Atomic Fields?

Benefit	Description
Reduced ambiguity	Authors select from defined options rather than inventing prose
Machine-processable	Tooling can aggregate, compare, validate, and report across SADs
Faster to complete	Checkboxes and selections are quicker than blank text fields
Comparable	Two SADs can be structurally compared and diffed
Translatable	Enum values can be mapped to any language without ambiguity
Governance-ready	The architecture governance process can verify completeness programmatically

How It Works Across Formats

The same atomic field renders differently depending on the output format, but carries identical meaning:

Schema Type	JSON / YAML	Markdown / Word	Confluence / Wiki
boolean	true / false	Checkbox: ☑ / ☐	Checkbox macro
enum (single)	"active-active"	Radio button or bold selection	Status macro or dropdown
enum (array)	["aws", "azure"]	Multiple checkboxes: ☑ AWS ☑ Azure	Multi-select macro
yesNoNa	"yes" / "no" / "not-applicable"	☑ Yes ☐ No ☐ N/A	Status macro
riskLevel	"high"	HIGH (with colour)	Status lozenge
integer / number	4096	Numeric field	Numeric field
string (constrained)	"PT4H" (ISO 8601)	“4 hours”	Duration field
string (free-text)	Prose	Prose	Prose

Free-Text Fields

Free-text fields are still used where structured options are not practical (e.g., solutionOverview, mitigationPlan, rationale). However, even these are scoped — they have a specific purpose described in the schema, not open-ended “notes” fields.

Atomic Field Categories in ADS

The schema uses the following atomic patterns:

Pattern	Example Fields	Values
Yes / No / N/A	internetFacing, thirdPartyHosted, backupEnabled	yes, no, not-applicable
Risk Level	residualRisk, confidentiality, integrity	critical, high, medium, low, negligible
Classification	classification	public, internal, restricted, highly-restricted
Status	document status, ADR status, risk status	Defined per context
Technology Enum	protocol, authenticationMethod, secretStore	Defined per field
Sizing Category	dataSizeCategory, clusterSize	Banded ranges
Duration	retentionPeriod, rtoTarget	ISO 8601 or banded categories
Criticality	businessCriticality	tier-1-critical through tier-5-minimal
ID Pattern	UC-01, ADR-001, R-001	Regex-constrained strings

Multi-Format Compatibility

ADS is designed to work equally well as:

• A human-authored document (Word, Confluence, wiki) — where atomic fields become checkboxes, dropdown menus, and radio buttons
• A machine-readable file (JSON, YAML, Markdown) — where atomic fields are enums, booleans, and typed values
• A web form — where atomic fields map directly to form controls

The JSON Schema is the single source of truth. All output formats are derived from it, ensuring consistency regardless of how the SAD is authored or consumed.

Accessibility & Cognitive Load

ADS is designed to be usable by all architects, including those who are neurodivergent. The following principles reduce cognitive load and improve readability:

Structural Consistency

Every section in the standard follows the same pattern:

1. Purpose — a short statement explaining what this section covers and why
2. Tables / Fields — structured, atomic fields to complete
3. Guidance — contextual help in a clearly marked box

This predictable structure means you always know what to expect when you open a new section.

Reducing Cognitive Load

Principle	How ADS Implements It
Atomic fields over blank pages	Checkboxes, enums, and structured tables replace open-ended text fields. You select rather than compose.
Progressive disclosure	Three documentation depths (Minimum → Recommended → Comprehensive) let you start simple and add detail only when needed.
One idea per row	Tables present one field per row rather than combining multiple concepts.
Consistent terminology	The glossary defines all acronyms. Terms are used consistently throughout.
Visual markers	Colour-coded depth indicators (Minimum Recommended Comprehensive) let you quickly see what’s required.
Clear scoring	The 0–5 compliance scale provides unambiguous, numeric feedback rather than subjective prose.

Acronyms & Terminology

All acronyms used in ADS are defined in the glossary. When completing a SAD:

• Define all acronyms on first use within the document
• Include a glossary (Section 7.1) in every SAD
• Avoid jargon where a plain-language alternative exists

Readability Guidelines for SAD Authors

When writing free-text content in a SAD:

• Use short sentences. One idea per sentence.
• Use bullet points rather than long paragraphs.
• Use active voice (“The service sends data to…”) not passive (“Data is sent by the service to…”).
• Use diagrams to complement text, not replace it.
• Ensure diagrams have alt-text descriptions for screen readers.

Sustainability as a First-Class Concern

ADS treats sustainability as a quality attribute on equal footing with reliability, performance, and cost — not as an afterthought or a one-line tick-box.

Principle	How ADS Implements It
A dedicated quality attribute	Section 4.5 covers hosting efficiency, carbon measurement, network efficiency, code efficiency, and data efficiency, with prompts and a 0–5 scoring scale.
Embedded in the views, not bolted on	The Physical View (3.3), Data View (3.4), and Logical View (3.1) each have explicit Sustainability Considerations prompts at the point where the carbon-impacting decisions are actually made.
Operational, not aspirational	The Lifecycle Management section (5.5) requires documenting how non-prod auto-shutdown, right-sizing reviews, and orphan-resource reclamation are operationalised — not just intended.
Aligned to recognised frameworks	Cross-references to AWS Well-Architected Sustainability and the Green Software Foundation’s Software Carbon Intensity (SCI) specification.
Trade-offs documented, not buried	Where sustainability conflicts with another quality attribute (e.g., always-on DR vs cold standby), the trade-off is captured in Section 4.6 Quality Attribute Tradeoffs rather than left implicit.

The intent is that a SAD reviewer who reads only the views and the lifecycle section, never opening Section 4.5, still encounters the carbon-impacting decisions and can challenge them.

Extensibility Without Ambiguity

When organisations add custom sections via the customSections extension point, they SHOULD follow the same atomic field principles:

1. Use boolean for yes/no questions
2. Define enum values for any field with a finite set of valid answers
3. Use typed fields (integer, number, date) for measurable values
4. Reserve free-text string fields for genuinely open-ended content
5. Add description to every field to clarify its purpose