Architecture | contextIsKey documentation

System overview

contextIsKey investigates proposed data-contract changes before execution. It turns an SRS or incident brief into bounded DataHub context, a deterministic impact assessment, hidden SQL-consumer findings, reviewable remediation artifacts, and approval-gated catalog proposals.

Incident input→Pasted requirements or extracted PDF, DOCX, text, Markdown, SQL, and CSV content

Context graph→DataHub schema and lineage through MCP, with optional entity, search, and query-history context

Impact engine→Deterministic classification, blast radius, SQL module discovery, regions, and remediation planning

Review boundary→Downloadable artifacts and server-rebuilt DataHub proposals that require explicit approval

Runtime topology

Runtime	Responsibilities	Primary implementation
FastAPI web app	Serve seven product workspaces, accept incident input, sign analysis state, and expose exports	`app.py`
Triage pipeline	Extract documents, parse rules, map requirements to assets, and compose chronological investigations	`triage.py`, `document_ingest.py`
DataHub MCP adapter	Require schema and lineage tools, bound lineage to three hops, and read optional entity and query context	`mcp_client.py`, `live.py`
Impact and planning	Score evidence completeness, discover SQL consumers, group regional exposure, and produce rollout plans	`impact.py`, `sql_impact.py`, `planner.py`
Evidence outputs	Build deterministic SQL, JSON, SARIF, validation, rollback, text, and PDF artifacts	`artifacts.py`, `exports.py`, `gate.py`
Write-back boundary	Rebuild approved proposals server-side and apply simulated or explicitly enabled GraphQL writes	`writeback.py`

Investigation flow

ExtractRead requirements from pasted text or a supported uploaded document; discard the original binary after extraction.
MapConvert rules into explicit mapped or unmapped results instead of inventing missing assets.
RetrieveRead schema and downstream lineage through the official DataHub MCP contract when live mode is enabled.
AssessCombine catalog evidence with static SQL-module discovery and regional metadata.
PlanProduce dependency-ordered remediation, validation, rollback, and manual-review decisions.
ApproveApply only selected proposal IDs after the server reconstructs their catalog content.

Design invariant

Generated SQL is review material. contextIsKey never executes database SQL automatically.

Authority and evidence model

Concern	Control	Failure behavior
Evidence mode	Bundled synthetic mode and live DataHub MCP mode are labeled separately	No silent fallback presented as live evidence
Missing context	Unmapped rules, incomplete lineage, missing owners, and absent regions remain visible	Lower confidence or require review
AI interpretation	Runs only after an explicit user action and cannot replace deterministic evidence	Return the grounded deterministic result
Write-back content	Browser submits proposal IDs; the server rebuilds catalog content from signed analysis values	Reject invalid state or ignore unknown IDs
Real DataHub writes	Require DataHub mode, an enabled flag, reachability, and selected proposals	Return an error stating that nothing was written

State and persistence

The hosted application is request-oriented. Analysis state is recomputed from signed change values rather than trusted from browser content. Uploaded document bytes are not persisted by the application after text extraction. The bundled scenario and generated artifacts are deterministic; DataHub remains the system of record for approved catalog changes.

Data class	Location	Continuity
Bundled evidence	Python fixtures and static scenario data	Versioned with the repository
Uploaded document	Request memory during extraction	Original binary discarded
Analysis state	Recomputed from HMAC-signed values	Bound to the running application key
Generated artifacts	Built from the current analysis response	Downloaded by the user when needed
Approved metadata	DataHub through GraphQL in explicitly enabled live mode	Persisted by DataHub

Build and delivery

The Python 3.12 application is packaged with setuptools, tested with pytest, linted with Ruff, and served by Uvicorn. Railway uses Nixpacks, starts changeproof.app:app, and requires /healthz before considering the service healthy.

InstallResolve the locked Python environment and package templates, styles, and scenario fixtures.
VerifyRun unit and integration tests plus Ruff before release.
ServeStart the FastAPI application through Uvicorn on the assigned port.
AcceptCheck the health route and exact user workflows; HTTP availability alone is not outcome proof.

Current boundaries

The public Railway demo uses deterministic synthetic DataHub-shaped context, not a live cloud catalog.
The opt-in live path requires get_lineage and list_schema_fields from the official DataHub MCP server.
Static SQL discovery can miss runtime dynamic SQL, external tools, and assets absent from metadata.
AI explanations are advisory and cannot alter deterministic scores, evidence, or execution state.
Generated fixes, rollout steps, and gate results remain review material until a human verifies and applies them.