docs(architecture): add full ADR + DDD documentation set

.gitignore

@@ -6,6 +6,13 @@
 # ============================================
 # Node.js dependencies
 node_modules/
+
+# Husky v9 generates `.husky/_/` on install (`npm run prepare`),
+# and the prepare script copies scripts/git-hooks/pre-commit into
+# .husky/pre-commit. The source-of-truth hook lives in
+# scripts/git-hooks/ and is the code-reviewed artifact;
+# .husky/ is the install target and should not be tracked.
+.husky/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# pre-commit-tool config (ADR-0025).
+#
+# Two scanners run on every commit and again in CI:
+#
+#   1. detect-secrets — high-entropy + known-pattern scan against staged
+#      diffs. Findings are diffed against `.secrets.baseline`; only new
+#      hits fail the commit. Refresh the baseline via
+#      `scripts/detect-secrets-update-baseline.sh` after auditing the
+#      new entries (and never wholesale-accepting unknown findings).
+#
+#   2. gitleaks — second scanner using a different rule set, catches
+#      patterns detect-secrets misses (especially provider-specific
+#      formats like Slack tokens, GitHub PATs, etc.).
+#
+# These hooks are tracked by the `pre-commit` (Python) framework, not
+# by npm. Install once per workstation:
+#
+#   pip install --user pre-commit detect-secrets
+#   pre-commit install
+#
+# CI runs `pre-commit run --all-files` as a gate, which protects against
+# anyone bypassing the local hook with `--no-verify`.
+repos:
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        name: detect-secrets (staged-only)
+        args:
+          - "--baseline"
+          - ".secrets.baseline"
+        # Exclude generated / vendored paths that would otherwise flood
+        # the scanner with false positives.
+        exclude: |
+          (?x)^(
+              package-lock\.json|
+              node_modules/.*|
+              coverage/.*|
+              dist/.*|
+              .*\.enc\.(yaml|yml|json|env)|
+              .*\.snap
+          )$
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks
+        name: gitleaks (staged-only)
+        # `--staged` keeps the scan scoped to the diff being committed,
+        # mirroring detect-secrets behaviour, so CI sees the same set.
+        args:
+          - "protect"
+          - "--staged"
+          - "--redact"

.secrets.baseline

@@ -0,0 +1,48 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    { "name": "ArtifactoryDetector" },
+    { "name": "AWSKeyDetector" },
+    { "name": "AzureStorageKeyDetector" },
+    { "name": "Base64HighEntropyString", "limit": 4.5 },
+    { "name": "BasicAuthDetector" },
+    { "name": "CloudantDetector" },
+    { "name": "DiscordBotTokenDetector" },
+    { "name": "GitHubTokenDetector" },
+    { "name": "GitLabTokenDetector" },
+    { "name": "HexHighEntropyString", "limit": 3.0 },
+    { "name": "IbmCloudIamDetector" },
+    { "name": "IbmCosHmacDetector" },
+    { "name": "IPPublicDetector" },
+    { "name": "JwtTokenDetector" },
+    { "name": "KeywordDetector", "keyword_exclude": "" },
+    { "name": "MailchimpDetector" },
+    { "name": "NpmDetector" },
+    { "name": "OpenAIDetector" },
+    { "name": "PrivateKeyDetector" },
+    { "name": "PypiTokenDetector" },
+    { "name": "SendGridDetector" },
+    { "name": "SlackDetector" },
+    { "name": "SoftlayerDetector" },
+    { "name": "SquareOAuthDetector" },
+    { "name": "StripeDetector" },
+    { "name": "TelegramBotTokenDetector" },
+    { "name": "TwilioKeyDetector" }
+  ],
+  "filters_used": [
+    { "path": "detect_secrets.filters.allowlist.is_line_allowlisted" },
+    { "path": "detect_secrets.filters.common.is_baseline_file", "filename": ".secrets.baseline" },
+    { "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies", "min_level": 2 },
+    { "path": "detect_secrets.filters.heuristic.is_indirect_reference" },
+    { "path": "detect_secrets.filters.heuristic.is_likely_id_string" },
+    { "path": "detect_secrets.filters.heuristic.is_lock_file" },
+    { "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string" },
+    { "path": "detect_secrets.filters.heuristic.is_potential_uuid" },
+    { "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign" },
+    { "path": "detect_secrets.filters.heuristic.is_sequential_string" },
+    { "path": "detect_secrets.filters.heuristic.is_swagger_file" },
+    { "path": "detect_secrets.filters.heuristic.is_templated_secret" }
+  ],
+  "results": {},
+  "generated_at": "2026-05-16T00:00:00Z"
+}

.sops.yaml

@@ -0,0 +1,48 @@
+# SOPS configuration (ADR-0025).
+#
+# SOPS encrypts low-risk, low-rotation values for *dev* and *staging*
+# environments so they can live in git without exposing plaintext.
+# Production secrets MUST go through the External Secrets Operator
+# (see k8s/secrets/external-secrets/) — SOPS is not a substitute.
+#
+# Only files matching the patterns below are encrypted. Convention:
+# any file named `*.enc.json`, `*.enc.yaml`, or `*.enc.env` is treated
+# as ciphertext at rest. The plaintext sibling (`config.dev.json`)
+# never gets committed — it is gitignored — and developers run
+# `sops -d` to materialise it locally.
+#
+# Encryption uses two redundant key sources:
+#
+#   1. `age` — keys distributed to engineers via 1Password. The
+#      placeholder fingerprint below is illustrative; the real value is
+#      a public recipient key produced by `age-keygen` and stored in
+#      the team password manager. Rotate by regenerating the key with
+#      `age-keygen -o ~/.config/sops/age/keys.txt` and updating the
+#      `age:` field below in a follow-up PR.
+#
+#   2. `kms` — AWS KMS Customer Managed Key, ARN below. Provides a
+#      break-glass decrypt path that does not require an engineer's
+#      personal age key (used by CI). Rotate by creating a new CMK and
+#      replacing the ARN; SOPS will re-encrypt on the next `sops -e`.
+#
+# To re-key an existing file after rotating either source:
+#   sops updatekeys path/to/file.enc.yaml
+#
+# Pattern-match order matters — first matching rule wins, so the more
+# specific `.enc.env` rule appears before the catch-all `.enc.{json,yaml}`.
+creation_rules:
+  # Per-environment .enc.env files (loaded by `dotenv` after decrypt).
+  - path_regex: \.enc\.env$
+    age: >-
+      age1placeholder0000000000000000000000000000000000000000000000000000
+    kms: "arn:aws:kms:us-east-1:000000000000:key/00000000-0000-0000-0000-000000000000"
+    encrypted_regex: "^.*$"
+
+  # Structured config snippets — JSON & YAML.
+  - path_regex: \.enc\.(json|yaml|yml)$
+    age: >-
+      age1placeholder0000000000000000000000000000000000000000000000000000
+    kms: "arn:aws:kms:us-east-1:000000000000:key/00000000-0000-0000-0000-000000000000"
+    # For YAML/JSON SOPS encrypts values only; keys remain readable so
+    # `git diff` shows which fields changed.
+    encrypted_regex: "^(password|secret|token|key|api[_-]?key|client[_-]?secret|connection[_-]?string)$"