Add architecture decision records (#225)

* add architecture decision records

* docs: keep Development Standards description with its list item

Item 8 was inserted between item 7's link and its description paragraph, which
re-parents that paragraph onto Architecture Decisions. Move item 8 below the
Development Standards description.

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>

* docs: describe the Architecture Decisions index entry

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>

---------

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>

Architecture-Decisions.md

@@ -0,0 +1,24 @@
+# Architecture Decision Records
+
+Architecture Decision Records (ADRs) capture decisions that guide Cacti's
+long-term architecture. They are concise, reviewable documents rather than
+implementation plans.
+
+## Status values
+
+- **Proposed**: under review and not yet binding.
+- **Accepted**: approved for new work.
+- **Superseded**: replaced by a later ADR.
+
+## Decisions
+
+1. [ADR-0001: Establish bounded contexts and framework-independent domain code](Architecture/0001-bounded-contexts.md)
+2. [ADR-0002: Model installation as durable, resumable install runs](Architecture/0002-durable-install-runs.md)
+3. [ADR-0003: Provide a versioned plugin extension boundary](Architecture/0003-plugin-extension-boundary.md)
+4. [ADR-0004: Persist workflow state separately from diagnostic artifacts](Architecture/0004-workflow-storage-and-observability.md)
+
+## Contributing
+
+New ADRs should describe the context, decision, consequences, and links to
+the implementation work. An ADR does not replace user, operator, or API
+documentation.

Architecture/0001-bounded-contexts.md

@@ -0,0 +1,33 @@
+# ADR-0001: Establish bounded contexts and framework-independent domain code
+
+**Status:** Proposed
+
+## Context
+
+Cacti has grown through a long-lived procedural and class-based codebase.
+Several workflows combine HTTP handling, CLI parsing, rendering, persistence,
+shell execution, and business rules in the same implementation. This makes
+incremental change difficult and exposes internal behavior to plugins.
+
+## Decision
+
+New architectural work will identify bounded contexts and keep their domain
+logic framework-independent. Initial contexts include Installation, Plugin
+Management, Configuration, Authorization, Data Collection, and Template and
+Package Management.
+
+Domain code will use PHP 8.1 value objects, backed enums, aggregates, and
+domain exceptions where they make rules explicit. Constructors must not access
+the database, filesystem, shell, globals, or request state. Infrastructure,
+framework components, and legacy helpers will be accessed through application
+services and narrowly defined ports.
+
+## Consequences
+
+- New code can be tested without web, CLI, or database bootstrap.
+- Symfony components may implement infrastructure concerns, but Cacti will not
+  require a full Symfony application migration.
+- Existing code is migrated through adapters; this decision does not require a
+  flag-day rewrite.
+- Public plugin APIs must depend on stable application contracts, not domain
+  internals or legacy globals.

Architecture/0002-durable-install-runs.md

@@ -0,0 +1,29 @@
+# ADR-0002: Model installation as durable, resumable install runs
+
+**Status:** Proposed
+
+## Context
+
+The installer currently keeps workflow state in mutable global settings and
+mixes wizard rendering with side effects. Background timestamp coordination can
+hide failures or permit ambiguous ownership of an install attempt.
+
+## Decision
+
+Installation and upgrade work will be represented by a durable `InstallRun`
+with a unique identifier, typed options, plan version, explicit state,
+operation checkpoints, lease data, progress, and structured failure details.
+
+The lifecycle is `validating`, `ready`, `running`, `succeeded`, `failed`, or
+`cancelled`. State transitions are validated and recorded atomically. A worker
+holds a renewable lease for a run and executes one idempotent operation at a
+time. Web and CLI interfaces submit commands and render run views; they do not
+perform installation work directly.
+
+## Consequences
+
+- Refreshing a wizard page and querying status are side-effect free.
+- Failed runs remain failed until an explicit retry or new run is requested.
+- Operations can resume from durable checkpoints after interruption.
+- Legacy `install_*` settings require a temporary compatibility adapter and a
+  documented removal plan.

Architecture/0003-plugin-extension-boundary.md

@@ -0,0 +1,30 @@
+# ADR-0003: Provide a versioned plugin extension boundary
+
+**Status:** Proposed
+
+## Context
+
+Plugins need to extend Cacti without depending directly on legacy installer
+state, globals, raw persistence, or unstable domain internals. Existing hooks
+must remain compatible while the platform evolves.
+
+## Decision
+
+Cacti will introduce a versioned plugin manifest and extension registry.
+Plugins will declare identity, compatibility, dependencies, capabilities, and
+their supported lifecycle contributions. They will receive typed application
+contexts and least-privilege service interfaces.
+
+Installer extensions will contribute pure plan entries and worker-owned,
+idempotent operations. Plugin operations are checkpointed by run, plugin,
+version, and operation key. Required plugin failures prevent core terminal
+success; optional failures follow an explicit policy.
+
+## Consequences
+
+- Plugin authors have a stable compatibility contract and conformance tests.
+- Legacy hooks are translated through a compatibility adapter during a
+  published deprecation period.
+- Plugins cannot mutate install-run state directly.
+- Core can report plugin lifecycle failures with plugin and run identifiers
+  while redacting secrets.

Architecture/0004-workflow-storage-and-observability.md

@@ -0,0 +1,31 @@
+# ADR-0004: Persist workflow state separately from diagnostic artifacts
+
+**Status:** Proposed
+
+## Context
+
+Installer state, progress, and diagnostics are currently spread across global
+settings and logs. This makes recovery, support, retention, and secret
+redaction difficult to reason about.
+
+## Decision
+
+Relational storage is the source of truth for install runs, operation
+checkpoints, leases, and structured events. Each record is scoped to a run ID
+and uses atomic state and lease updates. Verbose logs, support bundles, and
+large generated artifacts are stored separately with metadata and checksums in
+the relational store.
+
+Run options, checkpoints, and events are schema-versioned and validated.
+Secrets are not copied into run records, events, logs, or artifacts; protected
+configuration stores secret values and workflow records retain only references
+or redacted values.
+
+## Consequences
+
+- Operators can diagnose a run without reconstructing state from global logs.
+- Retention can prune successful details while preserving failed-run evidence.
+- Plugin operation data can use generic namespaced checkpoints instead of
+  creating arbitrary installer-state tables.
+- Storage migrations, indexing, artifact cleanup, and retention policy are
+  required parts of the implementation.

README.md

@@ -97,6 +97,11 @@ PARTICULAR PURPOSE. See the GNU General Public License for more details.
    Group. Non-compliance does not automatically mean exclusion of proposed
    changes.
 
+8. [Architecture Decisions](README.md#architecture-decisions)
+
+   This section contains the architecture decision records that describe the
+   decisions guiding the long-term architecture of Cacti.
+
 ### Known Issues
 
 [List of Known issues](Known-Issues.md)
@@ -385,6 +390,10 @@ Watch Howto's and Tutorials on the Cacti Official YouTube page if you prefer. If
 
 7. [Security](Standards-Security.md)
 
+### Architecture Decisions
+
+1. [Architecture Decision Records](Architecture-Decisions.md)
+
 ### Template Specific Documentation
 
 This section will be for template specific configuration requirements