@opengroundplan/core 0.1.1

package/catalog/decision.yaml

@@ -0,0 +1,309 @@
+# The question tree. Derived from Richards' published decision procedure, not invented — see
+# docs/research/03-architecture-selection-and-repo-standards.md §2.
+#
+# ENGINE CONTRACT: rank candidates by sum(weight * score) across every answered choice's `weights`,
+# where `score` comes from the architecture entry and every key is a Characteristic enum member.
+# Negative weights push away from a characteristic. Gates run BEFORE ranking and eliminate outright.
+
+version: 1
+
+# Step 0 — narrow the candidate set to the families the project actually has. A project commonly
+# answers this more than once (a system topology AND an application style AND a frontend style).
+surfaces:
+  - id: application-style
+    prompt: "How should code inside a single deployable be organized?"
+    family: application
+  - id: system-topology
+    prompt: "How should the system be split into deployable units?"
+    family: system
+  - id: frontend-style
+    prompt: "How should the frontend be organized?"
+    family: frontend
+  - id: ai-style
+    prompt: "How should the LLM-facing part of the system be built?"
+    family: ai
+  - id: data-style
+    prompt: "How should the analytical data platform be organized?"
+    family: data
+
+questions:
+  # Q1 — feasibility veto first; it eliminates more candidates than any scoring round.
+  - id: team-size
+    prompt: "How many engineers will touch this codebase?"
+    type: select
+    choices:
+      - value: solo
+        label: "1-7"
+        weights: { simplicity: 5, cost: 4, deployability: -2, scalability: -2 }
+      - value: small
+        label: "8-25"
+        weights: { simplicity: 3, cost: 3, maintainability: 1 }
+      - value: medium
+        label: "25-100"
+        weights: { maintainability: 3, deployability: 3, simplicity: -1 }
+      - value: large
+        label: "Over 100"
+        weights: { maintainability: 4, deployability: 4, evolvability: 3, simplicity: -3, cost: -2 }
+
+  # Q2 — pre-PMF forces the style that is cheapest to CHANGE, not the most scalable.
+  - id: domain-maturity
+    prompt: "Is the domain understood and stable, or still being discovered?"
+    type: select
+    choices:
+      - value: discovering
+        label: "Still being discovered (pre-PMF)"
+        weights: { simplicity: 5, cost: 4, evolvability: 3, deployability: -3, scalability: -3 }
+      - value: emerging
+        label: "Mostly understood, boundaries still moving"
+        weights: { simplicity: 2, evolvability: 3, cost: 2 }
+      - value: stable
+        label: "Well understood and stable"
+        weights: { maintainability: 3, abstraction: 2, deployability: 2 }
+
+  # Q3 — Richards' Step 1 fork, the single highest-leverage question and the most commonly skipped.
+  # Uniform characteristics + distributed architecture = paying $$$$$ for nothing.
+  - id: characteristic-uniformity
+    prompt: "Do different parts of the system need materially different scale or availability?"
+    type: select
+    choices:
+      - value: uniform
+        label: "No — the whole system needs roughly the same characteristics"
+        weights: { simplicity: 5, cost: 5, scalability: -3, elasticity: -3, deployability: -2 }
+      - value: divergent
+        label: "Yes — one subsystem needs far more than another"
+        weights: { scalability: 4, elasticity: 3, deployability: 3, fault-tolerance: 3, simplicity: -3 }
+
+  - id: deploy-cadence
+    prompt: "One release train, or independent per-component schedules?"
+    type: select
+    choices:
+      - value: single-train
+        label: "One release train"
+        weights: { simplicity: 4, cost: 3, deployability: -2 }
+      - value: independent
+        label: "Independent, with different approvals per component"
+        weights: { deployability: 5, evolvability: 2, simplicity: -2, cost: -2 }
+
+  # Q5 — responsiveness kills microservices at 2 and rewards event-driven at 5.
+  - id: latency-budget
+    prompt: "Is there a hard p99 latency target in milliseconds?"
+    type: select
+    choices:
+      - value: none
+        label: "No hard target"
+        weights: {}
+      - value: soft
+        label: "Soft target, seconds are acceptable"
+        weights: { responsiveness: 1 }
+      - value: hard
+        label: "Yes, a hard millisecond-scale p99"
+        weights: { responsiveness: 5, simplicity: 1, cost: -1 }
+
+  - id: consistency-tolerance
+    prompt: "Can any part of the system tolerate eventual consistency?"
+    type: select
+    choices:
+      - value: strict
+        label: "No — everything must be strongly consistent"
+        weights: { simplicity: 4, cost: 3, scalability: -3, elasticity: -3 }
+      - value: partial
+        label: "Some parts can"
+        weights: { scalability: 2, evolvability: 1 }
+      - value: tolerant
+        label: "Yes, broadly"
+        weights: { scalability: 3, elasticity: 3, fault-tolerance: 2 }
+
+  - id: elasticity-profile
+    prompt: "What does your load profile look like?"
+    type: select
+    choices:
+      - value: steady
+        label: "Steady and predictable"
+        weights: { cost: 4, simplicity: 3, elasticity: -3 }
+      - value: predictable-peak
+        label: "Predictable peaks"
+        weights: { elasticity: 2, scalability: 2 }
+      - value: unpredictable-spike
+        label: "Unpredictable spikes, near-zero baseline between them"
+        weights: { elasticity: 5, scalability: 3, cost: 2, simplicity: -2 }
+
+  - id: regulatory-isolation
+    prompt: "Must any subsystem be provably isolated for compliance (PCI, HIPAA, export control)?"
+    type: boolean
+    choices:
+      - value: false
+        label: "No"
+        weights: {}
+      - value: true
+        label: "Yes"
+        weights: { deployability: 4, fault-tolerance: 3, abstraction: 2, simplicity: -3, cost: -2 }
+
+  # Q9 — the second feasibility veto. Distributed styles are unavailable until the platform exists.
+  - id: platform-maturity
+    prompt: "Do you already have CI/CD, observability, and an on-call rotation?"
+    type: select
+    choices:
+      - value: none
+        label: "None of it"
+        weights: { simplicity: 5, cost: 4, deployability: -4, fault-tolerance: -3 }
+      - value: partial
+        label: "CI/CD yes, observability and on-call thin"
+        weights: { simplicity: 2, cost: 2, deployability: -1 }
+      - value: mature
+        label: "All three, in production use"
+        weights: { deployability: 2, fault-tolerance: 2 }
+
+  # Q10 — the actual scoring input. Weighted heaviest by design: Richards' whole method is that the
+  # top 3 decide, and that a system optimized for everything is optimized for nothing.
+  - id: top-three
+    prompt: "Which 3 characteristics would you refuse to trade away?"
+    type: multiselect
+    max: 3
+    choices:
+      - { value: maintainability,  label: "Maintainability",  weights: { maintainability: 10 } }
+      - { value: testability,      label: "Testability",      weights: { testability: 10 } }
+      - { value: deployability,    label: "Deployability",    weights: { deployability: 10 } }
+      - { value: simplicity,       label: "Simplicity",       weights: { simplicity: 10 } }
+      - { value: scalability,      label: "Scalability",      weights: { scalability: 10 } }
+      - { value: elasticity,       label: "Elasticity",       weights: { elasticity: 10 } }
+      - { value: responsiveness,   label: "Responsiveness",   weights: { responsiveness: 10 } }
+      - { value: fault-tolerance,  label: "Fault tolerance",  weights: { fault-tolerance: 10 } }
+      - { value: evolvability,     label: "Evolvability",     weights: { evolvability: 10 } }
+      - { value: abstraction,      label: "Abstraction",      weights: { abstraction: 10 } }
+      - { value: interoperability, label: "Interoperability", weights: { interoperability: 10 } }
+      - { value: cost,             label: "Low cost",         weights: { cost: 10 } }
+
+# Hard gates run before ranking. `disqualify` removes candidates; `require` keeps only those that
+# clear a floor. Richards' Step 3: a single 1 on a top-3 characteristic is disqualifying, not
+# something an average smooths over.
+gates:
+  - id: top-three-floor
+    when: "always"
+    rule: disqualify
+    condition: "any(score[c] == 1 for c in answers.top-three)"
+    why: "A 1 on a driving characteristic is a veto, not a low average."
+
+  - id: fault-isolation
+    when: "answers.characteristic-uniformity == 'divergent'"
+    rule: require
+    condition: "score['fault-tolerance'] >= 4"
+    why: "One component's failure must leave the others serving."
+
+  - id: regulatory-boundary
+    when: "answers.regulatory-isolation == true"
+    rule: require
+    condition: "score['deployability'] >= 4"
+    why: "Compliance scope has to be bounded by a deployment boundary, not a module boundary."
+
+  - id: small-team-veto
+    when: "answers.team-size == 'solo'"
+    rule: disqualify
+    condition: "complexity in ['high', 'very-high']"
+    why: "Operational surface exceeds capacity below ~8 engineers regardless of the scoring."
+
+  - id: no-platform-veto
+    when: "answers.platform-maturity == 'none'"
+    rule: disqualify
+    condition: "family == 'system' and id != 'monolith'"
+    why: "Distributed styles are unavailable until CI/CD, observability, and on-call exist."
+
+  - id: pre-pmf-preference
+    when: "answers.domain-maturity == 'discovering'"
+    rule: disqualify
+    condition: "complexity == 'very-high'"
+    why: "Pre-PMF, pick the style cheapest to change, not the most scalable."
+
+# The §2.4 default table. Applied when ranking produces a near-tie, and used to explain the result.
+defaults:
+  - situation: "New product, small team, unclear domain"
+    recommend: modular-monolith
+    why: "5 simplicity at $ cost, and domain partitioning preserves the extraction path."
+  - situation: "Established domain, need deploy independence, moderate team"
+    recommend: microservices
+    why: >-
+      Only when the top 3 lands in its 5s and the team can absorb $$$$$. Richards' own best-value
+      style here is service-based ($$ with 4s across the board), which this catalog does not yet
+      carry as an entry — treat microservices as the upper bound, not the default.
+  - situation: "Large org, divergent scale, mature platform, over 25 engineers"
+    recommend: microservices
+    why: "Its 5s are maintainability, testability, deployability, scalability, fault-tolerance, evolvability."
+  - situation: "Hard latency plus fault-tolerance requirements"
+    recommend: event-driven
+    why: "5 responsiveness, 5 fault-tolerance, 5 evolvability at $$$."
+  - situation: "Spiky near-zero-baseline load, small team, no platform engineer"
+    recommend: serverless
+    why: "5 elasticity and 5 deployability; the cost case inverts above ~60-80% sustained utilization."
+  - situation: "Any monolithic default"
+    recommend: modular-monolith
+    why: >-
+      Never default to layered. There is no characteristic where layered beats modular monolith, at
+      identical cost. Layered's only advantage is familiarity.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Repo strategy is a separate decision from architecture style — it follows team and ownership
+# boundaries, not technical layers. Signal table transcribed from research doc 03 §5.6.
+repoStrategy:
+  signals:
+    - signal: engineers
+      thresholds:
+        - { value: "under 15",  monorepo: strongly, polyrepo: overhead }
+        - { value: "15-50",     monorepo: "yes, with affected-detection + CODEOWNERS", polyrepo: viable }
+        - { value: "50-150",    monorepo: "needs build-infra investment", polyrepo: "yes, or hybrid" }
+        - { value: "over 150",  monorepo: "only with a funded build team", polyrepo: "yes, hybrid" }
+    - signal: deployable-services
+      thresholds:
+        - { value: "1-5",     monorepo: yes, polyrepo: no }
+        - { value: "over 20", monorepo: hybrid, polyrepo: yes }
+    - signal: shared-code
+      thresholds:
+        - { value: "over 20% of LOC", monorepo: decisive, polyrepo: no }
+        - { value: "under 5% of LOC", monorepo: no, polyrepo: decisive }
+    - signal: cross-cutting-changes
+      thresholds:
+        - { value: "more than 1/month touching 3+ components", monorepo: decisive, polyrepo: painful }
+    - signal: org-boundaries
+      thresholds:
+        - { value: "different companies, contractors, or compliance domains", monorepo: no, polyrepo: decisive }
+    - signal: access-control
+      thresholds:
+        - { value: "some code must be invisible to some engineers", monorepo: hard, polyrepo: free }
+    - signal: regulatory-isolation
+      thresholds:
+        - { value: "PCI/HIPAA scope must be bounded", monorepo: no, polyrepo: decisive }
+    - signal: languages
+      thresholds:
+        - { value: "5 or more", monorepo: "only with Bazel/Buck2/moon", polyrepo: yes }
+
+  # Hard triggers override the table entirely.
+  forcePolyrepo:
+    - "Code needs non-overlapping audiences"
+    - "Regulatory scope must be provably bounded"
+    - "Different legal entities own components"
+    - "A component has a genuinely independent lifecycle"
+    - "You publish a library consumers clone standalone"
+  forceMonorepo:
+    - "One team owns everything and cross-cutting changes are routine"
+    - "Type-safety across service boundaries is a primary value"
+    - "You are pre-PMF — the boundaries you draw now will be wrong, and a monorepo makes them cheap to redraw"
+    - "You spend more time on version-bump PRs than features"
+
+  default: monorepo
+  defaultWhy: >-
+    Default new projects to a monorepo and make extraction easy — clean package boundaries, no deep
+    cross-imports, per-package manifests. Extraction from a well-bounded monorepo is a day of work;
+    merging N drifted polyrepos is a quarter.
+
+  # Conway's Law: align repo boundaries with team ownership, not architectural layers. A repo per
+  # team is defensible; a repo per layer (frontend/backend/shared) guarantees three coordinated PRs
+  # per feature. Never split for aesthetics; split to solve a specific named problem.
+  cautions:
+    - "The Google-scale fallacy: monorepos require investment proportional to size. Google's works because Google funds a build-infra org."
+    - "CI time is the #1 monorepo killer — without affected-graph detection and remote caching, every PR runs every test."
+    - "A monorepo does not force everything to release together, but it does force every project to build against HEAD of shared code."
+    - "Circulating monorepo adoption and PR-cycle-time figures are confounded and must not be quoted as fact."
+
+sources:
+  - https://www.developertoarchitect.com/downloads/architecture-styles-worksheet.pdf
+  - https://www.developertoarchitect.com/downloads/architecture-characteristics-worksheet.pdf
+  - https://martinfowler.com/bliki/MicroservicePrerequisites.html
+  - https://martinfowler.com/bliki/MonolithFirst.html