# nikhil0074-dev/safeforge architecture

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

- Interactive diagram: https://gitdiagram.com/nikhil0074-dev/safeforge
- Repository: https://github.com/nikhil0074-dev/safeforge

## Overview

SafeForge is a zero-trust content-disarm-and-reconstruction service. A user submits a file through the CLI or web/API; the engine identifies its true type, enforces resource limits and policy, dispatches to a format-specific sanitizer, verifies the rebuilt output, and returns a report and custody record. Conversion, fidelity scoring, and the browser UI support this core flow. The README documents additional format coverage and API capabilities; some routes and handler internals were not sampled, so those links are omitted where unverified.

Main entry points: [`safeforge/engine.py`](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/engine.py) (Sanitization Engine), [`safeforge/server.py`](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/server.py) (REST API), [`safeforge/__main__.py`](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/__main__.py) (CLI), [`safeforge/email_cdr.py`](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/email_cdr.py) (Email Sanitizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI<br/>[__main__.py]"]
end

subgraph group_pipeline["Sanitization Pipeline"]
  node_engine["Sanitization Engine<br/>[engine.py]"]
  node_detect["Type Detection<br/>[typedetect.py]"]
  node_limits["Bomb Limits<br/>[limits.py]"]
  node_policy["Sanitization Policy<br/>[policy.py]"]
  node_threats["Threat Logging<br/>[threats.py]"]
end

subgraph group_formats["Format Sanitizers"]
  node_pdf["PDF Sanitizer<br/>[pdf_cdr.py]"]
  node_office["Office Sanitizer<br/>[office_cdr.py]"]
  node_images["Image Sanitizer<br/>[image_cdr.py]"]
  node_svg["SVG Sanitizer<br/>[svg_cdr.py]"]
  node_email["Email Sanitizer<br/>[email_cdr.py]"]
  node_archive["Archive Sanitizer<br/>[archive_cdr.py]"]
  node_media["Audio Video Sanitizer<br/>[media_cdr.py]"]
  node_text["Text Sanitizer<br/>[text_cdr.py]"]
end

subgraph group_assurance["Assurance and Results"]
  node_verify["Output Verification<br/>[engine.py]"]
  node_fidelity["Fidelity Scoring<br/>[fidelity.py]"]
  node_chain["Custody Chain<br/>[chain.py]"]
  node_convert["File Conversion<br/>[convert.py]"]
end

subgraph group_interface["Service Interface"]
  node_api["REST API<br/>[server.py]"]
  node_webui["Web UI<br/>[app.js]"]
end

node_user(("File User"))

node_user -->|"submits file"| node_cli
node_user -->|"uploads file"| node_api
node_api -->|"serves assets"| node_webui
node_cli -->|"sanitizes"| node_engine
node_cli -->|"configures"| node_policy
node_api -->|"runs sanitize"| node_engine
node_api -->|"converts result"| node_convert
node_api -->|"verifies chain"| node_chain
node_engine -->|"identifies type"| node_detect
node_engine -->|"checks limits"| node_limits
node_engine -->|"uses policy"| node_policy
node_engine -->|"logs threats"| node_threats
node_engine -->|"dispatches to"| node_pdf
node_engine -->|"dispatches to"| node_office
node_engine -->|"dispatches to"| node_images
node_engine -->|"dispatches to"| node_svg
node_engine -->|"dispatches to"| node_email
node_engine -->|"dispatches to"| node_archive
node_engine -->|"dispatches to"| node_media
node_engine -->|"dispatches to"| node_text
node_engine -->|"re-scans output"| node_verify
node_engine -->|"measures fidelity"| node_fidelity
node_engine -->|"appends custody"| node_chain
node_email -->|"sanitizes attachments"| node_engine
node_archive -.->|"sanitizes members"| node_engine

click node_cli "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/__main__.py"
click node_api "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/server.py"
click node_webui "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/static/app.js"
click node_engine "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/engine.py"
click node_detect "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/typedetect.py"
click node_limits "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/limits.py"
click node_policy "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/policy.py"
click node_threats "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/threats.py"
click node_pdf "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/pdf_cdr.py"
click node_office "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/office_cdr.py"
click node_images "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/image_cdr.py"
click node_svg "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/svg_cdr.py"
click node_email "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/email_cdr.py"
click node_archive "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/archive_cdr.py"
click node_media "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/media_cdr.py"
click node_text "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/text_cdr.py"
click node_verify "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/engine.py"
click node_fidelity "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/fidelity.py"
click node_chain "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/chain.py"
click node_convert "https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/convert.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_user toneBlue
class node_engine,node_detect,node_limits,node_policy,node_threats toneAmber
class node_pdf,node_office,node_images,node_svg,node_email,node_archive,node_media,node_text toneMint
class node_verify,node_fidelity,node_chain,node_convert toneRose
class node_api,node_webui toneIndigo
```

## Components

### User Entry

- [CLI](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/__main__.py): `safeforge/__main__.py`

### Sanitization Pipeline

- [Sanitization Engine](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/engine.py): `safeforge/engine.py`
- [Type Detection](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/typedetect.py): `safeforge/typedetect.py`
- [Bomb Limits](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/limits.py): `safeforge/limits.py`
- [Sanitization Policy](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/policy.py): `safeforge/policy.py`
- [Threat Logging](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/threats.py): `safeforge/threats.py`

### Format Sanitizers

- [PDF Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/pdf_cdr.py): `safeforge/pdf_cdr.py`
- [Office Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/office_cdr.py): `safeforge/office_cdr.py`
- [Image Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/image_cdr.py): `safeforge/image_cdr.py`
- [SVG Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/svg_cdr.py): `safeforge/svg_cdr.py`
- [Email Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/email_cdr.py): `safeforge/email_cdr.py`
- [Archive Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/archive_cdr.py): `safeforge/archive_cdr.py`
- [Audio Video Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/media_cdr.py): `safeforge/media_cdr.py`
- [Text Sanitizer](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/text_cdr.py): `safeforge/text_cdr.py`

### Assurance and Results

- [Output Verification](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/engine.py): `safeforge/engine.py`
- [Fidelity Scoring](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/fidelity.py): `safeforge/fidelity.py`
- [Custody Chain](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/chain.py): `safeforge/chain.py`
- [File Conversion](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/convert.py): `safeforge/convert.py`

### Service Interface

- [REST API](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/server.py): `safeforge/server.py`
- [Web UI](https://github.com/nikhil0074-dev/safeforge/blob/main/safeforge/static/app.js): `safeforge/static/app.js`

### Other components

- **File User**

## Connections

- File User → CLI: submits file (evidence: `README.md`)
- File User → REST API: uploads file (evidence: `README.md`)
- REST API → Web UI: serves assets (evidence: `safeforge/server.py`)
- CLI → Sanitization Engine: sanitizes (evidence: `safeforge/__main__.py`)
- CLI → Sanitization Policy: configures (evidence: `safeforge/__main__.py`)
- REST API → Sanitization Engine: runs sanitize (evidence: `safeforge/server.py`)
- REST API → File Conversion: converts result (evidence: `safeforge/server.py`)
- REST API → Custody Chain: verifies chain (evidence: `safeforge/server.py`)
- Sanitization Engine → Type Detection: identifies type (evidence: `safeforge/engine.py`)
- Sanitization Engine → Bomb Limits: checks limits (evidence: `safeforge/engine.py`)
- Sanitization Engine → Sanitization Policy: uses policy (evidence: `safeforge/engine.py`)
- Sanitization Engine → Threat Logging: logs threats (evidence: `safeforge/engine.py`)
- Sanitization Engine → PDF Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Office Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Image Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → SVG Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Email Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Archive Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Audio Video Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Text Sanitizer: dispatches to (evidence: `safeforge/engine.py`)
- Sanitization Engine → Output Verification: re-scans output (evidence: `README.md`)
- Sanitization Engine → Fidelity Scoring: measures fidelity (evidence: `safeforge/engine.py`)
- Sanitization Engine → Custody Chain: appends custody (evidence: `safeforge/engine.py`)
- Email Sanitizer → Sanitization Engine: sanitizes attachments (evidence: `safeforge/email_cdr.py`)
- Archive Sanitizer → Sanitization Engine: sanitizes members (evidence: `README.md`)
