# saumyasaini11/redact-scalarai architecture

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

- Interactive diagram: https://gitdiagram.com/saumyasaini11/redact-scalarai
- Repository: https://github.com/saumyasaini11/redact-scalarai

## Overview

The product is an offline DOCX PII pseudonymizer. Users inspect a document or run the pipeline: it extracts text, analyzes embedded media, detects and scores candidates, applies review decisions, preserves identity links, generates replacements, and writes a gated draft or final document with QA and reports. README capabilities also include evaluation and standalone verification. The pipeline and selected modules were sampled; some subsystem wiring is represented only where documented, so uncertain call edges are omitted.

Main entry points: [`src/pii_redactor/pipeline.py`](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/pipeline.py) (Workflow Orchestrator), [`src/pii_redactor/cli.py`](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/cli.py) (Command Interface), [`src/pii_redactor/docx_io.py`](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/docx_io.py) (DOCX Package I/O), [`src/pii_redactor/recognizers.py`](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/recognizers.py) (PII Recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document Analysis"]
  node_cli["Command Interface<br/>[cli.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
  node_pipeline["Workflow Orchestrator<br/>[pipeline.py]"]
  node_docx["DOCX Package I/O<br/>[docx_io.py]"]
  node_recognizers["PII Recognition<br/>[recognizers.py]"]
  node_media["Media Analysis<br/>[media.py]"]
  node_ensemble["Candidate Scoring<br/>[ensemble.py]"]
end

subgraph group_decision["Review and Identity"]
  node_review["Review Decisions<br/>[review.py]"]
  node_review_queue[("Private Review State")]
  node_relationships["Identity Linking<br/>[relationships.py]"]
end

subgraph group_transform["Redaction and QA"]
  node_pseudonyms["Replacement Generator<br/>[pseudonyms.py]"]
  node_qa["Output Validation<br/>[qa.py]"]
  node_output["DOCX Outputs"]
end

subgraph group_insight["Reports and Evaluation"]
  node_reporting["Release Reporting<br/>[reporting.py]"]
  node_evaluation["Detection Evaluation<br/>[evaluation.py]"]
end

node_user(("User"))
node_reviewer(("Reviewer"))
node_tesseract["Tesseract OCR"]
node_spacy["spaCy Model"]

node_user -->|"invokes"| node_cli
node_reviewer -->|"records decisions"| node_review_queue
node_cli -->|"loads settings"| node_config
node_cli -->|"runs workflow"| node_pipeline
node_cli -->|"inspects or verifies"| node_docx
node_pipeline -->|"extracts and patches"| node_docx
node_pipeline -->|"detects text PII"| node_recognizers
node_pipeline -->|"analyzes media"| node_media
node_media -.->|"runs OCR"| node_tesseract
node_recognizers -.->|"runs NER"| node_spacy
node_pipeline -->|"merges and scores"| node_ensemble
node_pipeline -->|"loads and applies"| node_review
node_review -->|"reads and writes"| node_review_queue
node_pipeline -->|"assigns identity IDs"| node_relationships
node_pipeline -->|"generates replacements"| node_pseudonyms
node_pipeline -->|"writes redacted package"| node_docx
node_docx -->|"writes DOCX"| node_output
node_pipeline -->|"validates output"| node_qa
node_qa -->|"checks package"| node_output
node_pipeline -->|"builds summary"| node_reporting
node_pipeline -->|"evaluates detections"| node_evaluation
node_cli -->|"shows queue status"| node_reviewer

click node_cli "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/cli.py"
click node_config "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/config.py"
click node_pipeline "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/pipeline.py"
click node_docx "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/docx_io.py"
click node_recognizers "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/recognizers.py"
click node_media "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/media.py"
click node_ensemble "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/ensemble.py"
click node_review "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/review.py"
click node_review_queue "https://github.com/saumyasaini11/redact-scalarai/tree/main/data/private"
click node_relationships "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/relationships.py"
click node_pseudonyms "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/pseudonyms.py"
click node_qa "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/qa.py"
click node_output "https://github.com/saumyasaini11/redact-scalarai/tree/main/data/output"
click node_reporting "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/reporting.py"
click node_evaluation "https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/evaluation.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_cli,node_config,node_pipeline,node_docx,node_recognizers,node_media,node_ensemble,node_user,node_reviewer toneBlue
class node_review,node_review_queue,node_relationships toneAmber
class node_pseudonyms,node_qa,node_output toneMint
class node_reporting,node_evaluation toneRose
class node_tesseract,node_spacy toneIndigo
```

## Components

### Document Analysis

- [Command Interface](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/cli.py): `src/pii_redactor/cli.py`
- [Runtime Settings](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/config.py): `src/pii_redactor/config.py`
- [Workflow Orchestrator](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/pipeline.py): `src/pii_redactor/pipeline.py`
- [DOCX Package I/O](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/docx_io.py): `src/pii_redactor/docx_io.py`
- [PII Recognition](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/recognizers.py): `src/pii_redactor/recognizers.py`
- [Media Analysis](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/media.py): `src/pii_redactor/media.py`
- [Candidate Scoring](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/ensemble.py): `src/pii_redactor/ensemble.py`

### Review and Identity

- [Review Decisions](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/review.py): `src/pii_redactor/review.py`
- [Private Review State](https://github.com/saumyasaini11/redact-scalarai/tree/main/data/private): `data/private`
- [Identity Linking](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/relationships.py): `src/pii_redactor/relationships.py`

### Redaction and QA

- [Replacement Generator](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/pseudonyms.py): `src/pii_redactor/pseudonyms.py`
- [Output Validation](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/qa.py): `src/pii_redactor/qa.py`
- [DOCX Outputs](https://github.com/saumyasaini11/redact-scalarai/tree/main/data/output): `data/output`

### Reports and Evaluation

- [Release Reporting](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/reporting.py): `src/pii_redactor/reporting.py`
- [Detection Evaluation](https://github.com/saumyasaini11/redact-scalarai/blob/main/src/pii_redactor/evaluation.py): `src/pii_redactor/evaluation.py`

### Other components

- **User**
- **Reviewer**
- **Tesseract OCR**
- **spaCy Model**

## Connections

- User → Command Interface: invokes
- Reviewer → Private Review State: records decisions
- Command Interface → Runtime Settings: loads settings
- Command Interface → Workflow Orchestrator: runs workflow
- Command Interface → DOCX Package I/O: inspects or verifies
- Workflow Orchestrator → DOCX Package I/O: extracts and patches
- Workflow Orchestrator → PII Recognition: detects text PII
- Workflow Orchestrator → Media Analysis: analyzes media
- Media Analysis → Tesseract OCR: runs OCR
- PII Recognition → spaCy Model: runs NER
- Workflow Orchestrator → Candidate Scoring: merges and scores
- Workflow Orchestrator → Review Decisions: loads and applies
- Review Decisions → Private Review State: reads and writes
- Workflow Orchestrator → Identity Linking: assigns identity IDs
- Workflow Orchestrator → Replacement Generator: generates replacements
- Workflow Orchestrator → DOCX Package I/O: writes redacted package
- DOCX Package I/O → DOCX Outputs: writes DOCX
- Workflow Orchestrator → Output Validation: validates output
- Output Validation → DOCX Outputs: checks package
- Workflow Orchestrator → Release Reporting: builds summary
- Workflow Orchestrator → Detection Evaluation: evaluates detections
- Command Interface → Reviewer: shows queue status