⚙️ Architecture Control Plane¶

The Architecture Control Plane provides deterministic review, comparison, and promotion workflows for metadata-defined architecture.

It turns architecture state into explicit artifacts:

Architecture State
Architecture Change Report
Architecture Promotion Report
Architecture Approval Artifact
Architecture Execution Record
deterministic report fingerprints

These artifacts make structural architecture changes reviewable, policy-aware, approvable, verifiable, executable through controlled scopes, visible in the UI, and suitable for CI pipelines.

Architecture Catalog complements the control plane as a read-only discovery surface. It shows how datasets are defined, connected, controlled and linked to execution evidence without creating approvals or executing loads.

🔧 1. Purpose¶

elevata treats architecture as executable metadata.

The Architecture Control Plane defines the review and comparison layer around that metadata:

Architecture State
  ↓
Architecture Diff
  ↓
MigrationPlan
  ↓
Policy Decisions
  ↓
Architecture Change Report
  ↓
Architecture Review Briefing
  ↓
Architecture Approval Artifact
  ↓
Controlled Execution
  ↓
Architecture Execution Record

This makes schema evolution intent explicit before load execution applies any DDL or DML.

🔧 2. Architecture State¶

Architecture State is a deterministic snapshot of the metadata-defined platform architecture.

It contains:

datasets
columns
materialization semantics
incremental strategy
historization metadata
lineage-safe rename metadata
stable fingerprints

The command:

python manage.py elevata_state

renders the architecture state as deterministic JSON.

To write a state artifact:

python manage.py elevata_state --output .artifacts/dev_architecture_state.json

To print only the fingerprint:

python manage.py elevata_state --fingerprint-only

The persisted runtime baseline directory is configured via:

ELEVATA_ARCH_STATE_DIR=.elevata/state

The load runner builds the current Architecture State during execution planning and uses it for architecture diffing, MigrationPlan derivation, and guard checks.

The persisted runtime baseline represents the applied architecture state. It is written after successful load execution. Dry-run persistence is controlled via:

ELEVATA_PERSIST_ARCH_STATE_ON_DRY_RUN=false

🔧 3. Architecture Change Report¶

An Architecture Change Report describes the difference between a baseline state and the metadata-defined architecture state.

The report includes:

state fingerprints
affected dataset scope
dataset changes
column changes
MigrationPlan actions
policy decisions
deterministic report fingerprint

Report scope is part of the report contract.

Invocation	Scope mode	Scope meaning
`elevata_plan --all`	`all`	all active target datasets
`elevata_plan --all --schema rawcore`	`scoped`	all active target datasets in the selected schema
`elevata_plan rc_aw_customer`	`scoped`	the selected dataset and related architecture scope

For scoped reports, the report payload contains only changes, migration actions, policy decisions and summary counts that belong to the selected scope. The report fingerprint therefore represents the selected architecture scope.

When a target dataset name is unique, --schema can be omitted. Use --schema when the same dataset name exists in multiple schemas or when CI scripts should declare the intended schema explicitly.

Render a report for one dataset:

python manage.py elevata_plan rc_aw_customer

Render a report for one dataset with an explicit schema:

python manage.py elevata_plan rc_aw_customer --schema rawcore

Render a report for all datasets in a schema:

python manage.py elevata_plan --all --schema rawcore

Render JSON for CI:

python manage.py elevata_plan --all --format json

Use an explicit baseline state file:

python manage.py elevata_plan rc_aw_customer \
  --previous-state .artifacts/prod_architecture_state.json

🔧 4. Architecture Approval Artifact¶

An Architecture Approval Artifact records a review decision for one exact Architecture Change Report fingerprint.

It answers:

Has this exact architecture change report been reviewed and approved?

Approval artifacts are deterministic JSON artifacts. They bind a review decision to the report fingerprint, report scope, report state, summary counts, and policy status of the approved Architecture Change Report.

An approval does not override policy decisions. If a report contains blocking policy decisions, execution remains blocked by the load runner and materialization policy.

Approval artifacts are created from Architecture Change Report JSON:

python manage.py elevata_plan rc_aw_customer \
  --format json \
  --output .artifacts/architecture_plan_rc_aw_customer.json

python manage.py elevata_approve .artifacts/architecture_plan_rc_aw_customer.json \
  --approved-by "Reviewer Name" \
  --note "Reviewed for deployment." \
  --output .artifacts/architecture_approval_rc_aw_customer.json

To store the approval artifact in the configured approval directory:

python manage.py elevata_approve .artifacts/architecture_plan_rc_aw_customer.json \
  --approved-by "Reviewer Name" \
  --note "Reviewed for deployment." \
  --store

The approval artifact directory is configured via:

ELEVATA_ARCH_APPROVAL_DIR=.elevata/approvals

The stored file name is derived from the approved report fingerprint:

<report_fingerprint>.approval.json

To verify that an approval artifact matches an Architecture Change Report:

python manage.py elevata_approval_check \
  .artifacts/architecture_plan_rc_aw_customer.json \
  .elevata/approvals/<report_fingerprint>.approval.json

The approval check fails when:

the approval artifact fingerprint does not match its payload
the approval identifier does not match the artifact fingerprint
the approval references another Architecture Change Report
the review decision is not approved

🔧 5. Architecture Review Status UI¶

The Architecture Review Status UI shows the review state for a selected TargetDataset architecture scope.

It displays:

review status
report fingerprint
approval identifier and artifact fingerprint
reviewer and decision timestamp
policy status
architecture scope
change summary
state fingerprints

Review states include approved, pending review, approval drift, blocked by policy, no architecture changes, and invalid approval artifact.

🔧 6. Architecture Control UI¶

The Architecture Control UI makes Architecture Control Plane workflows operable across controlled architecture scopes.

It supports:

all-dataset scopes
schema scopes
TargetDataset scopes
TargetDataset scopes with target-only execution

🧩 6.1 Architecture Review Briefing¶

Architecture Review Briefing is a compact, deterministic decision aid inside Architecture Control.

It summarizes what a reviewer should understand before approving or executing the selected scope:

selected scope and scope size
review state
architecture change counts
policy attention
destructive or blocking migration signals
execution readiness
suggested reviewer focus

The briefing is derived from existing Architecture Control signals: the current scoped Architecture Change Report, the Architecture Review Status and the Execution Preview. It is read-only and does not create approvals, run approval checks, xecute loads or mutate metadata.

The UI keeps the briefing compact by showing the main reviewer signals first. Detailed sections are available on demand through an expandable detail area.

The Architecture Control UI provides controlled actions for architecture artifacts and execution:

show the scoped Architecture Change Report
download the scoped Architecture Change Report as JSON
create an Architecture Approval Artifact
check the stored Approval Artifact against the report
refresh the Architecture Review Status
inspect the Architecture Review Briefing
inspect the Execution Preview
run controlled load execution
inspect captured execution output
inspect the Architecture Execution Record
browse stored Architecture Execution Records
filter execution history by scope, status, date range and dependency mode
download stored execution record JSON
apply retention cleanup for older execution records

Approval Artifact creation records the logged-in reviewer, the decision timestamp, and an optional review note. The artifact is stored in the configured approval artifact directory and is bound to the report fingerprint.

Approval checks compare the stored Approval Artifact with the current scoped Architecture Change Report and surface the result in the UI.

Controlled execution runs through the load runner. It does not bypass preflight validation, materialization policy checks, Architecture Guard enforcement, or approval matching.

Execution uses the selected Architecture Control scope:

Scope	Execution behavior
All datasets	Executes all active target datasets with dependency ordering
Schema	Executes selected schema roots with dependency ordering
TargetDataset	Executes the selected TargetDataset with dependency ordering
TargetDataset, target-only	Executes only the selected TargetDataset

Target-only execution is available only for TargetDataset scopes. It is intended for focused iteration when upstream data is already available.

Controlled execution produces an Architecture Execution Record.

🔧 7. Artifact Storage for Shared Deployments¶

Architecture Control Plane artifacts are stored on the server-side filesystem.

The Architecture State Store uses ELEVATA_ARCH_STATE_DIR and stores the persisted architecture state as JSON. The Approval Artifact Store uses ELEVATA_ARCH_APPROVAL_DIR and stores deterministic approval artifacts as JSON files. The Architecture Execution Record Store uses ELEVATA_ARCH_EXECUTION_DIR and stores controlled execution records as JSON files.

Default artifact directories:

ELEVATA_ARCH_STATE_DIR=.elevata/state
ELEVATA_ARCH_APPROVAL_DIR=.elevata/approvals
ELEVATA_ARCH_EXECUTION_DIR=.elevata/executions

For single-instance environments, the default .elevata paths provide a compact artifact layout inside the elevata runtime directory. For shared deployments, these directories must point to persistent server-side storage that is available to every application instance serving the same metadata database.

Recommended deployment pattern:

ELEVATA_ARCH_STATE_DIR=/var/lib/elevata/state
ELEVATA_ARCH_APPROVAL_DIR=/var/lib/elevata/approvals
ELEVATA_ARCH_EXECUTION_DIR=/var/lib/elevata/executions

In containerized or multi-instance deployments, these paths are backed by a shared persistent volume. This ensures that Architecture State, Approval Artifacts, Review Status, Approval Checks, and Architecture Execution Records are resolved consistently for all users of the shared metadata application.

The metadata database stores metadata definitions. Architecture Control Plane artifacts are stored in the configured artifact directories.

Architecture Execution Records use a table-shaped JSON contract. This keeps the file-backed store compact while preserving a stable record structure for operational audit processing.

Architecture Execution Record history is resolved from the configured execution record directory. Retention cleanup removes stored execution record artifacts older than the selected retention window. The cleanup operates on audit artifacts only and does not alter metadata definitions, approval artifacts, Architecture State artifacts, load run logs or load run snapshots.

🔧 8. Architecture Promotion Report¶

An Architecture Promotion Report compares two Architecture State artifacts.

It answers:

What would change when this target architecture state is compared to that source state?

Example:

python manage.py elevata_promote \
  .artifacts/dev_architecture_state.json \
  .artifacts/prod_architecture_state.json \
  --source-label dev \
  --target-label prod

For schema-scoped comparison:

python manage.py elevata_promote \
  .artifacts/dev_architecture_state.json \
  .artifacts/prod_architecture_state.json \
  --schema rawcore

For dataset-scoped comparison:

python manage.py elevata_promote \
  .artifacts/dev_architecture_state.json \
  .artifacts/prod_architecture_state.json \
  --target-dataset rc_aw_customer

For dataset-scoped comparison with an explicit schema:

python manage.py elevata_promote \
  .artifacts/dev_architecture_state.json \
  .artifacts/prod_architecture_state.json \
  --target-dataset rc_aw_customer \
  --schema rawcore

Promotion reports use the same scope semantics as change reports. The embedded Architecture Change Report exposes the effective scope in JSON and text output.

🔧 9. CI Exit Policies¶

Architecture reports and promotion reports support explicit exit policies:

Option	Behavior
`--fail-on-changes`	Fails when architecture changes are present
`--fail-on-blocked`	Fails when policy decisions block execution
`--fail-on-destructive`	Fails when destructive actions are present

Example:

python manage.py elevata_plan --all \
  --format json \
  --fail-on-blocked

Example:

python manage.py elevata_promote \
  .artifacts/dev_architecture_state.json \
  .artifacts/prod_architecture_state.json \
  --format json \
  --fail-on-blocked \
  --fail-on-destructive

🔧 10. Execution Guardrails¶

The Architecture Control Plane separates architecture review, approval, execution control, and load-run enforcement.

Load execution remains protected by the load runner. elevata_load performs its own preflight checks before DDL or DML can be executed.

This preserves a strict separation:

Command	Responsibility
`elevata_state`	Render architecture state
`elevata_plan`	Render architecture change report
`elevata_promote`	Compare architecture state artifacts
`elevata_approve`	Create architecture approval artifact
`elevata_approval_check`	Verify approval artifact against a change report
`elevata_load`	Execute loads with preflight and guard checks

The Architecture Control UI invokes the same load runner through a constrained execution path. The UI does not expose arbitrary load runner flags. It exposes controlled scope selection, approval status, execution preview, target-only execution for TargetDataset scopes, captured output, and execution records.

🔧 11. Architecture Execution Record¶

An Architecture Execution Record describes one controlled Architecture Control execution.

It captures:

execution identifier
reviewer or operator
timestamps and duration
execution status
Architecture Control scope
dependency mode
report fingerprint
approval identifier
preview fingerprint
command invocation metadata
output and error tails
output and error line counts
deterministic record fingerprint

Execution records answer:

Who executed which approved architecture scope, with which dependency mode, and what happened?

The record is stored as deterministic JSON:

<execution_id>.execution.json

Stored records can be listed in Architecture Control, filtered by scope, status, date range and dependency mode, opened as detail views, and downloaded as JSON audit artifacts. Retention cleanup removes older stored records from the execution record store.

Architecture Execution Records are audit artifacts. They complement load-run logs and snapshots:

Artifact	Purpose
Load Run Log	Dataset- and attempt-level operational events
Load Run Snapshot	Batch-level execution state and outcomes
Architecture Execution Record	Architecture Control execution decision and result

🔧 12. Deterministic Fingerprints¶

Architecture State, Architecture Change Report, Architecture Promotion Report, Architecture Approval Artifact, and Architecture Execution Record each expose deterministic fingerprints.

Fingerprints are derived from canonical JSON representations and allow CI, review processes, approval decisions, promotion workflows, and audit processes to reference exact architecture artifacts.

🔧 13. Operational Smoke Checks¶

The following commands provide a compact validation set for architecture artifacts.

Export the current architecture state:

python manage.py elevata_state --output .artifacts/current_architecture_state.json

Render a platform-wide report:

python manage.py elevata_plan --all \
  --format json \
  --output .artifacts/architecture_plan_all.json

Render a schema-scoped report:

python manage.py elevata_plan --all \
  --schema rawcore \
  --format json \
  --output .artifacts/architecture_plan_rawcore.json

Render a dataset-scoped report:

python manage.py elevata_plan rc_aw_customer \
  --format json \
  --output .artifacts/architecture_plan_rc_aw_customer.json

Compare two state artifacts:

python manage.py elevata_promote \
  .artifacts/current_architecture_state.json \
  .artifacts/current_architecture_state.json \
  --format json \
  --output .artifacts/architecture_promotion_self_check.json

Create and store an approval artifact:

python manage.py elevata_approve .artifacts/architecture_plan_rc_aw_customer.json \
  --approved-by "Reviewer Name" \
  --note "Reviewed for deployment." \
  --store

Verify the stored approval artifact:

python manage.py elevata_approval_check \
  .artifacts/architecture_plan_rc_aw_customer.json \
  .elevata/approvals/<report_fingerprint>.approval.json

Validate no-change exit behavior against an explicit baseline:

python manage.py elevata_plan --all \
  --previous-state .artifacts/current_architecture_state.json \
  --format json \
  --fail-on-changes