# mathangi18/mdr architecture

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

- Interactive diagram: https://gitdiagram.com/mathangi18/mdr
- Repository: https://github.com/mathangi18/mdr

## Overview

MDR Legal Evidence Workshop is a browser-based regulatory reading and legal-assessment application. Participants authenticate, query a frozen MDR corpus, inspect cited evidence and plain-language explanations, and save editable legal decisions; generated drafts are not approved meanings. Its runtime combines retrieval, graph context, and rule-based or local-model explanations, while assessment storage keeps participant drafts separate. The README also documents isolated adapter-training code. Backend excerpts are partial, so some documented frontend/API relationships use README evidence; unsampled implementation links are omitted.

Main entry points: [`workshop_deployment/backend/app.py`](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/app.py) (Authenticated API), [`workshop_deployment/backend/loop.py`](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/loop.py) (Evidence answering), [`workshop_deployment/backend/model.py`](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/model.py) (Local draft model), [`training/run.py`](https://github.com/mathangi18/mdr/blob/main/training/run.py) (Adapter training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workshop interface"]
  node_frontend["Workshop UI<br/>[index.html]"]
  node_assessment_ui["Assessment editor<br/>[assessment.js]"]
  node_review_ui["Review interface<br/>[review.js]"]
  node_inference_ui["Inference interface<br/>[inference.js]"]
  node_hosted_ui["Hosted access<br/>[hosted.js]"]
end

subgraph group_runtime["Query and explanation"]
  node_api["Authenticated API<br/>[app.py]"]
  node_answer_loop["Evidence answering<br/>[loop.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_concepts["Concept matching<br/>[concepts.py]"]
  node_explanation["Plain-language rules<br/>[explanation.py]"]
  node_model["Local draft model<br/>[model.py]"]
  node_telemetry["Inference metrics<br/>[telemetry.py]"]
  node_schemas["Result contracts<br/>[schemas.py]"]
end

subgraph group_assessment["Legal assessment"]
  node_legal_graph["Legal graph contract<br/>[legal_graph.py]"]
  node_review["Decision validation<br/>[review.py]"]
  node_review_store[("Draft revisions<br/>[store.py]")]
end

subgraph group_data["Corpus and persistence"]
  node_corpus[("Regulatory corpus<br/>[corpus.sqlite]")]
  node_source_docs["Source documents"]
  node_db_access["SQLite access<br/>[storage.py]"]
  node_connector["Graph connector<br/>[connector.py]"]
end

subgraph group_training["Model training"]
  node_training_data["Training dataset<br/>[data.py]"]
  node_training_run["Adapter training<br/>[run.py]"]
end

node_participant(("Participant"))
node_trainer(("Training operator"))

node_participant -->|"uses"| node_frontend
node_frontend -->|"requests"| node_api
node_assessment_ui -->|"submits decisions"| node_api
node_review_ui -->|"requests review"| node_api
node_inference_ui -->|"requests drafts"| node_api
node_hosted_ui -->|"accesses"| node_api
node_api -->|"dispatches queries"| node_answer_loop
node_answer_loop -->|"searches evidence"| node_retrieval
node_answer_loop -->|"detects concepts"| node_concepts
node_answer_loop -->|"explains evidence"| node_explanation
node_answer_loop -->|"builds results"| node_schemas
node_retrieval -->|"reads through"| node_db_access
node_db_access -->|"queries"| node_corpus
node_api -->|"validates decisions"| node_review
node_review -->|"edits graph"| node_legal_graph
node_api -->|"loads and saves"| node_review_store
node_review_store -->|"uses connections"| node_db_access
node_api -->|"serves PDFs"| node_source_docs
node_api -->|"serves corpus"| node_corpus
node_api -->|"requests generation"| node_model
node_model -->|"decomposes drafts"| node_explanation
node_model -->|"measures inference"| node_telemetry
node_answer_loop -.->|"uses graph links"| node_connector
node_trainer -->|"runs training"| node_training_run
node_training_run -->|"loads dataset code"| node_training_data
node_training_run -->|"uses model definitions"| node_model

click node_frontend "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/index.html"
click node_assessment_ui "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/assessment.js"
click node_review_ui "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/review.js"
click node_inference_ui "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/inference.js"
click node_hosted_ui "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/hosted.js"
click node_api "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/app.py"
click node_answer_loop "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/loop.py"
click node_retrieval "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/retrieval.py"
click node_concepts "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/concepts.py"
click node_explanation "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/explanation.py"
click node_model "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/model.py"
click node_telemetry "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/telemetry.py"
click node_schemas "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/schemas.py"
click node_legal_graph "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/legal_graph.py"
click node_review "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/review.py"
click node_review_store "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/store.py"
click node_corpus "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/bundle/corpus.sqlite"
click node_source_docs "https://github.com/mathangi18/mdr/tree/main/workshop_deployment/bundle/source_documents"
click node_db_access "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/storage.py"
click node_connector "https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/connector.py"
click node_training_data "https://github.com/mathangi18/mdr/blob/main/training/data.py"
click node_training_run "https://github.com/mathangi18/mdr/blob/main/training/run.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_frontend,node_assessment_ui,node_review_ui,node_inference_ui,node_hosted_ui toneBlue
class node_api,node_answer_loop,node_retrieval,node_concepts,node_explanation,node_model,node_telemetry,node_schemas toneAmber
class node_legal_graph,node_review,node_review_store toneMint
class node_corpus,node_source_docs,node_db_access,node_connector toneRose
class node_training_data,node_training_run,node_participant,node_trainer toneIndigo
```

## Components

### Workshop interface

- [Workshop UI](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/index.html): `workshop_deployment/frontend/index.html`
- [Assessment editor](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/assessment.js): `workshop_deployment/frontend/assessment.js`
- [Review interface](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/review.js): `workshop_deployment/frontend/review.js`
- [Inference interface](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/inference.js): `workshop_deployment/frontend/inference.js`
- [Hosted access](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/frontend/hosted.js): `workshop_deployment/frontend/hosted.js`

### Query and explanation

- [Authenticated API](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/app.py): `workshop_deployment/backend/app.py`
- [Evidence answering](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/loop.py): `workshop_deployment/backend/loop.py`
- [Hybrid retrieval](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/retrieval.py): `workshop_deployment/backend/retrieval.py`
- [Concept matching](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/concepts.py): `workshop_deployment/backend/concepts.py`
- [Plain-language rules](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/explanation.py): `workshop_deployment/backend/explanation.py`
- [Local draft model](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/model.py): `workshop_deployment/backend/model.py`
- [Inference metrics](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/telemetry.py): `workshop_deployment/backend/telemetry.py`
- [Result contracts](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/schemas.py): `workshop_deployment/backend/schemas.py`

### Legal assessment

- [Legal graph contract](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/legal_graph.py): `workshop_deployment/backend/legal_graph.py`
- [Decision validation](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/review.py): `workshop_deployment/backend/review.py`
- [Draft revisions](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/store.py): `workshop_deployment/backend/store.py`

### Corpus and persistence

- [Regulatory corpus](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/bundle/corpus.sqlite): `workshop_deployment/bundle/corpus.sqlite`
- [Source documents](https://github.com/mathangi18/mdr/tree/main/workshop_deployment/bundle/source_documents): `workshop_deployment/bundle/source_documents`
- [SQLite access](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/storage.py): `workshop_deployment/backend/storage.py`
- [Graph connector](https://github.com/mathangi18/mdr/blob/main/workshop_deployment/backend/connector.py): `workshop_deployment/backend/connector.py`

### Model training

- [Training dataset](https://github.com/mathangi18/mdr/blob/main/training/data.py): `training/data.py`
- [Adapter training](https://github.com/mathangi18/mdr/blob/main/training/run.py): `training/run.py`

### Other components

- **Participant**
- **Training operator**

## Connections

- Participant → Workshop UI: uses (evidence: `README.md`)
- Workshop UI → Authenticated API: requests (evidence: `README.md`)
- Assessment editor → Authenticated API: submits decisions (evidence: `README.md`)
- Review interface → Authenticated API: requests review (evidence: `README.md`)
- Inference interface → Authenticated API: requests drafts (evidence: `README.md`)
- Hosted access → Authenticated API: accesses (evidence: `README.md`)
- Authenticated API → Evidence answering: dispatches queries (evidence: `workshop_deployment/backend/app.py`)
- Evidence answering → Hybrid retrieval: searches evidence (evidence: `workshop_deployment/backend/loop.py`)
- Evidence answering → Concept matching: detects concepts (evidence: `workshop_deployment/backend/loop.py`)
- Evidence answering → Plain-language rules: explains evidence (evidence: `workshop_deployment/backend/loop.py`)
- Evidence answering → Result contracts: builds results (evidence: `workshop_deployment/backend/loop.py`)
- Hybrid retrieval → SQLite access: reads through (evidence: `workshop_deployment/backend/retrieval.py`)
- SQLite access → Regulatory corpus: queries (evidence: `README.md`)
- Authenticated API → Decision validation: validates decisions (evidence: `workshop_deployment/backend/app.py`)
- Decision validation → Legal graph contract: edits graph (evidence: `workshop_deployment/backend/review.py`)
- Authenticated API → Draft revisions: loads and saves (evidence: `workshop_deployment/backend/app.py`)
- Draft revisions → SQLite access: uses connections (evidence: `workshop_deployment/backend/store.py`)
- Authenticated API → Source documents: serves PDFs (evidence: `workshop_deployment/backend/app.py`)
- Authenticated API → Regulatory corpus: serves corpus (evidence: `workshop_deployment/backend/app.py`)
- Authenticated API → Local draft model: requests generation (evidence: `workshop_deployment/backend/app.py`)
- Local draft model → Plain-language rules: decomposes drafts (evidence: `workshop_deployment/backend/model.py`)
- Local draft model → Inference metrics: measures inference (evidence: `workshop_deployment/backend/model.py`)
- Evidence answering → Graph connector: uses graph links
- Training operator → Adapter training: runs training (evidence: `README.md`)
- Adapter training → Training dataset: loads dataset code (evidence: `training/run.py`)
- Adapter training → Local draft model: uses model definitions (evidence: `training/run.py`)
