# Architecture Fitness Functions Catalogue: [System or product]

> Catalogue of architecture fitness functions for [System]: the quality
> attributes that matter, an objective check for each, how it is
> classified, the metric and threshold, where it is implemented, how often
> it runs, who owns it and its current result. Based on the fitness
> function concept from *Building Evolutionary Architectures* (Neal Ford,
> Rebecca Parsons, Patrick Kua, and in the second edition Pramod
> Sadalage). Replace every `[bracketed]` value and every row marked
> *Example*.

<!--
Guidance: How to use this template
- Start from the quality attributes the business cares about (section 2),
  not from the tools you already have. Each fitness function must protect
  a named attribute.
- A fitness function is an objective, repeatable check with a threshold.
  "The code should be clean" is a wish; "no package in domain/ imports
  from infrastructure/" is a fitness function.
- Automate wherever possible and run checks where a failure is cheapest
  to fix: in the build for structure, in the pipeline for performance,
  in production for availability.
- Review thresholds when the architecture evolves. A threshold nobody
  remembers the reason for gets switched off.
-->

| Field | Value |
|---|---|
| Catalogue ID | [FF-SYSTEM] |
| System | [Name and scope] |
| Version | [0.1] |
| Owner | [@architect] |
| Contributors | [Teams] |
| Last reviewed | YYYY-MM-DD |
| Related | [Architecture description], [Quality attribute scenarios], [Tech debt register] |

## 1. Purpose and concept

<!-- Guidance: Explain in two or three sentences why the team uses fitness functions, so new members understand that a failing check is an architecture conversation, not just a red build. -->

A fitness function is an objective measure of how well the system meets
one architectural characteristic. Together, the functions in this
catalogue act as an executable description of the architecture: when a
change would erode a property we care about, a check fails early and
the team decides consciously whether to fix the change or revise the
target. The concept comes from evolutionary computing, where a fitness
function scores how close a candidate solution is to the goal.

## 2. Quality attributes in scope

<!-- Guidance: List the architectural characteristics this system must protect, in priority order, with the business reason. Link quality attribute scenarios where they exist. -->

| ID | Quality attribute | Why it matters | Priority |
|---|---|---|---|
| QA-01 | *Example:* Modularity (layering and bounded contexts) | Teams release independently; coupling slows every change | High |
| QA-02 | *Example:* Performance (API latency) | Checkout abandonment rises above 1 s response time | High |
| QA-03 | *Example:* Security (dependency hygiene) | Regulator requires patching critical CVEs within 14 days | High |
| QA-04 | *Example:* Availability | Contractual 99.9% monthly SLA | High |
| QA-05 | *Example:* Deployability | Target: deploy any service on any working day in < 30 min | Medium |
| QA-06 | *Example:* Cost efficiency | Unit cost must fall as volume grows | Medium |
| [QA-nn] | [Attribute] | [Reason] | [H/M/L] |

## 3. Classification dimensions

<!-- Guidance: Classify each function so the catalogue shows balance. A catalogue with only atomic, triggered, static checks misses runtime behaviour. Descriptions below are written for this template. -->

| Dimension | Values | Meaning |
|---|---|---|
| Scope | Atomic / Holistic | Atomic checks one characteristic in isolation; holistic checks how several interact (for example performance under a security control) |
| Trigger | Triggered / Continual | Triggered runs on an event such as a commit or a release; continual runs all the time, typically in production monitoring |
| Result | Static / Dynamic | Static compares with a fixed threshold; dynamic threshold depends on context such as load or time of day |
| Execution | Automated / Manual | Manual checks (for example a legal review) are allowed but should be rare and scheduled |
| Timing | Temporal | Runs on a calendar, for example "upgrade check every quarter" |
| Intent | Intentional / Emergent | Intentional checks are defined up front; emergent ones are added after the system reveals a new risk |

## 4. Fitness function catalogue

<!-- Guidance: One row per function. The definition must be precise enough that two engineers would implement the same check. Record the current result at each review; a function never run is not part of the architecture. -->

| ID | Quality attribute | Fitness function definition | Type | Metric and threshold | Implementation | Cadence | Owner | Current result |
|---|---|---|---|---|---|---|---|---|
| FF-01 | QA-01 Modularity | *Example:* Classes in `domain` must not depend on `infrastructure` or `web` packages | Atomic, triggered, static, automated | 0 violations | Architecture unit test (ArchUnit) in build | Every commit | [@team-core] | Pass, 0 violations |
| FF-02 | QA-01 Modularity | *Example:* No cycles between modules | Atomic, triggered, static, automated | 0 cycles | dependency-cruiser rule in CI | Every commit | [@team-web] | Pass |
| FF-03 | QA-02 Performance | *Example:* p95 latency of `/checkout` under 300 RPS load | Atomic, triggered, static, automated | p95 <= 400 ms | k6 load test in staging pipeline | Every release candidate | [@team-checkout] | 362 ms, pass |
| FF-04 | QA-03 Security | *Example:* No dependency with a known critical vulnerability older than 14 days | Atomic, triggered and temporal, static, automated | 0 critical findings > 14 days | Software composition analysis in CI plus nightly scan | Every commit and nightly | [@security] | 1 finding, 6 days old, pass |
| FF-05 | QA-04 Availability | *Example:* Monthly availability of public API from synthetic probes | Atomic, continual, static, automated | >= 99.9% per month | Synthetic checks every minute from 3 regions | Continual | [@sre] | 99.95% last month, pass |
| FF-06 | QA-02 and QA-03 | *Example:* p95 latency stays within budget with WAF and mTLS enabled | Holistic, triggered, static, automated | p95 <= 400 ms with all security controls on | Load test in production-like environment | Monthly | [@sre] | 391 ms, pass (near threshold) |
| FF-07 | QA-05 Deployability | *Example:* Lead time from merge to production | Atomic, continual, dynamic, automated | Median < 30 min; alert if 7-day median rises 50% above the 90-day median | Pipeline metrics dashboard | Continual | [@platform] | 22 min median, pass |
| FF-08 | QA-06 Cost | *Example:* Infrastructure cost per 1,000 orders | Holistic, temporal, dynamic, automated | Must not rise for two consecutive months | Cost export and query | Monthly | [@finops] | Fell 4%, pass |
| FF-09 | QA-03 Security | *Example:* Annual review of data flows against records of processing | Atomic, temporal, static, manual | Review completed and signed off | Privacy review checklist | Yearly | [@dpo] | Due YYYY-MM-DD |
| [FF-nn] | [QA-nn] | [Precise definition] | [Scope, trigger, result, execution] | [Metric and threshold] | [Test, tool, query] | [Cadence] | [@name] | [Result and date] |

### 4.1 Threshold rationale

Record why each threshold has its value, so it can be revisited.

| ID | Threshold | Rationale | Source |
|---|---|---|---|
| FF-03 | p95 <= 400 ms | *Example:* Leaves 600 ms of the 1 s page budget for front end and network | Performance budget, [link] |
| FF-04 | 14 days | *Example:* Regulatory patching deadline | [Policy reference] |
| [FF-nn] | [Threshold] | [Reason] | [Source] |

## 5. Implementation guidelines

<!-- Guidance: Agree conventions so fitness functions are maintained like production code. -->

- Store fitness function code in the same repository as the system it
  checks, under [path, e.g. `tests/architecture/`], and review it like
  any other change.
- Each failing check prints the function ID, the threshold, the measured
  value and a link to this catalogue.
- Pipeline position: structural checks block merge; performance and
  holistic checks block promotion to production; continual checks raise
  alerts routed to the owner.
- New quality attribute scenarios must propose at least one fitness
  function or explain why one is not possible.
- Disabling a check needs an entry in section 6 with an expiry date.

## 6. Exceptions and waivers

<!-- Guidance: Record every temporarily disabled or relaxed check with a reason and an expiry. Waivers without expiry become permanent erosion. -->

| ID | Function | Waiver | Reason | Approved by | Expires |
|---|---|---|---|---|---|
| WV-01 | *Example:* FF-02 | Allow one known cycle between `billing` and `invoicing` | Being removed by TD-017 | [@architect] | YYYY-MM-DD |
| [WV-nn] | [FF-nn] | [Change] | [Reason] | [@name] | YYYY-MM-DD |

## 7. Review and results history

<!-- Guidance: Summarise the state of the catalogue at each review: how many functions pass, which are near threshold, which thresholds changed and why. -->

| Review date | Functions | Passing | Near threshold | Failing | Changes made |
|---|---|---|---|---|---|
| YYYY-MM-DD | *Example:* 9 | 8 | 1 (FF-06) | 0 | Added FF-08 cost check; tightened FF-03 from 500 ms to 400 ms |
| YYYY-MM-DD | [n] | [n] | [IDs] | [IDs] | [Changes] |

Actions from the latest review: [list with owners]. *Example:* profile
the WAF rule set to restore headroom on FF-06 ([@sre], YYYY-MM-DD).

## Standard and licence note

Based on the architecture fitness function concept described in
*Building Evolutionary Architectures* by Neal Ford, Rebecca Parsons and
Patrick Kua (O'Reilly, 2017; second edition with Pramod Sadalage, 2023).
The classification dimensions are summarised in original words; no text
from the book is reproduced. Tool names are examples only. Template
licence: MIT.