# codevizsiyam/dq-doctor architecture

> Architecture diagram of the GitHub repository codevizsiyam/dq-doctor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codevizsiyam/dq-doctor
- Repository: https://github.com/codevizsiyam/dq-doctor

## Overview

Data Steward AI is a governed customer-data investigation and remediation app. A steward selects an incident in the Streamlit work queue; the runtime investigates it with read-only tools and a loaded skill, validates and grades the recommendation, then pauses for human review. Only an approved decision reaches remediation, which writes the golden record and audit history. A separate schema-impact path reports breaking changes and downstream lineage without migration. The graph reflects documented workflow ownership; unsampled wiring is omitted, and optional provider integrations are dashed.

Main entry points: [`src/data_steward/workflow/graph.py`](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/graph.py) (Workflow graph), [`src/data_steward/workflow/service.py`](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/service.py) (Steward runtime), [`app.py`](https://github.com/codevizsiyam/dq-doctor/blob/main/app.py) (Streamlit app), [`src/data_steward/repositories.py`](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/repositories.py) (Repository boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Steward experience"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_ui["Workbench views<br/>[ui.py]"]
end

subgraph group_workflow["Investigation workflow"]
  node_runtime["Steward runtime<br/>[service.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_investigator["Investigator agent<br/>[investigator.py]"]
  node_toolkit["Read-only toolkit<br/>[toolkit.py]"]
end

subgraph group_domain["Governance and domain"]
  node_skills["Investigation skills"]
  node_contract["Customer contract<br/>[customer.yaml]"]
  node_tools["Evidence and schema tools<br/>[tools.py]"]
  node_governance["Policy validation<br/>[governance.py]"]
  node_rubric["Recommendation rubric<br/>[rubric.py]"]
  node_remediation["Approved remediation<br/>[remediation.py]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Repository boundary<br/>[repositories.py]"]
  node_database[("Application database<br/>[sqlite.py]")]
  node_checkpoints[("Workflow checkpoints<br/>[service.py]")]
end

subgraph group_insight["Reporting and evaluation"]
  node_reports["Activity reports<br/>[reports.py]"]
  node_evaluations["Evaluation runner<br/>[evaluations.py]"]
end

node_steward(("Data steward"))
node_openai["OpenAI model"]
node_arize["Arize tracing"]
node_judge["LLM grounding judge"]

node_steward -->|"selects incident"| node_streamlit
node_streamlit -->|"requests workflow"| node_runtime
node_streamlit -->|"renders views"| node_ui
node_steward -->|"submits decision"| node_streamlit
node_runtime -->|"invokes and resumes"| node_graph
node_runtime -->|"loads incident data"| node_repository
node_runtime -->|"persists workflow state"| node_checkpoints
node_graph -->|"runs investigation"| node_investigator
node_investigator -->|"executes tools"| node_toolkit
node_investigator -.->|"requests completion"| node_openai
node_toolkit -->|"runs read-only tools"| node_tools
node_toolkit -->|"loads procedure"| node_skills
node_toolkit -->|"reads contract"| node_contract
node_tools -->|"reads records and lineage"| node_repository
node_graph -->|"validates proposal"| node_governance
node_graph -->|"grades recommendation"| node_rubric
node_graph -->|"records workflow events"| node_repository
node_graph -->|"pauses for review"| node_streamlit
node_streamlit -->|"submits decision"| node_runtime
node_graph -->|"applies approved decision"| node_remediation
node_remediation -->|"persists approved change"| node_repository
node_repository -->|"reads and writes"| node_database
node_runtime -->|"builds activity report"| node_reports
node_streamlit -->|"runs evaluations"| node_evaluations
node_evaluations -->|"reads incidents and records"| node_repository
node_evaluations -.->|"scores grounding"| node_judge
node_evaluations -.->|"publishes evaluation scores"| node_arize
node_runtime -.->|"traces investigation"| node_arize

click node_streamlit "https://github.com/codevizsiyam/dq-doctor/blob/main/app.py"
click node_ui "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/ui.py"
click node_runtime "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/service.py"
click node_graph "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/graph.py"
click node_investigator "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/investigator.py"
click node_toolkit "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/toolkit.py"
click node_skills "https://github.com/codevizsiyam/dq-doctor/tree/main/skills"
click node_contract "https://github.com/codevizsiyam/dq-doctor/blob/main/contracts/customer.yaml"
click node_tools "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/tools.py"
click node_governance "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/governance.py"
click node_rubric "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/rubric.py"
click node_remediation "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/remediation.py"
click node_repository "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/repositories.py"
click node_database "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/sqlite.py"
click node_checkpoints "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/service.py"
click node_reports "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/reports.py"
click node_evaluations "https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/evaluations.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_ui toneBlue
class node_runtime,node_graph,node_investigator,node_toolkit toneAmber
class node_skills,node_contract,node_tools,node_governance,node_rubric,node_remediation toneMint
class node_repository,node_database,node_checkpoints toneRose
class node_reports,node_evaluations,node_steward,node_openai,node_arize,node_judge toneIndigo
```

## Components

### Steward experience

- [Streamlit app](https://github.com/codevizsiyam/dq-doctor/blob/main/app.py): `app.py`
- [Workbench views](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/ui.py): `src/data_steward/ui.py`

### Investigation workflow

- [Steward runtime](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/service.py): `src/data_steward/workflow/service.py`
- [Workflow graph](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/graph.py): `src/data_steward/workflow/graph.py`
- [Investigator agent](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/investigator.py): `src/data_steward/workflow/investigator.py`
- [Read-only toolkit](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/toolkit.py): `src/data_steward/workflow/toolkit.py`

### Governance and domain

- [Investigation skills](https://github.com/codevizsiyam/dq-doctor/tree/main/skills): `skills`
- [Customer contract](https://github.com/codevizsiyam/dq-doctor/blob/main/contracts/customer.yaml): `contracts/customer.yaml`
- [Evidence and schema tools](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/tools.py): `src/data_steward/tools.py`
- [Policy validation](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/governance.py): `src/data_steward/governance.py`
- [Recommendation rubric](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/rubric.py): `src/data_steward/rubric.py`
- [Approved remediation](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/remediation.py): `src/data_steward/remediation.py`

### Persistence

- [Repository boundary](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/repositories.py): `src/data_steward/repositories.py`
- [Application database](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/sqlite.py): `src/data_steward/sqlite.py`
- [Workflow checkpoints](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/workflow/service.py): `src/data_steward/workflow/service.py`

### Reporting and evaluation

- [Activity reports](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/reports.py): `src/data_steward/reports.py`
- [Evaluation runner](https://github.com/codevizsiyam/dq-doctor/blob/main/src/data_steward/evaluations.py): `src/data_steward/evaluations.py`

### Other components

- **Data steward**
- **OpenAI model**
- **Arize tracing**
- **LLM grounding judge**

## Connections

- Data steward → Streamlit app: selects incident
- Streamlit app → Steward runtime: requests workflow
- Streamlit app → Workbench views: renders views
- Data steward → Streamlit app: submits decision
- Steward runtime → Workflow graph: invokes and resumes
- Steward runtime → Repository boundary: loads incident data
- Steward runtime → Workflow checkpoints: persists workflow state
- Workflow graph → Investigator agent: runs investigation
- Investigator agent → Read-only toolkit: executes tools
- Investigator agent → OpenAI model: requests completion
- Read-only toolkit → Evidence and schema tools: runs read-only tools
- Read-only toolkit → Investigation skills: loads procedure
- Read-only toolkit → Customer contract: reads contract
- Evidence and schema tools → Repository boundary: reads records and lineage
- Workflow graph → Policy validation: validates proposal
- Workflow graph → Recommendation rubric: grades recommendation
- Workflow graph → Repository boundary: records workflow events
- Workflow graph → Streamlit app: pauses for review
- Streamlit app → Steward runtime: submits decision
- Workflow graph → Approved remediation: applies approved decision
- Approved remediation → Repository boundary: persists approved change
- Repository boundary → Application database: reads and writes
- Steward runtime → Activity reports: builds activity report
- Streamlit app → Evaluation runner: runs evaluations
- Evaluation runner → Repository boundary: reads incidents and records
- Evaluation runner → LLM grounding judge: scores grounding
- Evaluation runner → Arize tracing: publishes evaluation scores
- Steward runtime → Arize tracing: traces investigation