# adarshh025/tracecrypt architecture

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

- Interactive diagram: https://gitdiagram.com/adarshh025/tracecrypt
- Repository: https://github.com/adarshh025/tracecrypt

## Overview

TraceCrypt is an offline, post-quantum document attribution system. A sender packages an encrypted document for certified recipients; on decryption, the recipient receives only a uniquely watermarked document after an attribution event is signed and submitted to the permissioned ledger. If a copy leaks, an investigator extracts its watermark, verifies the ledger and cryptographic evidence, and produces a verdict and proof bundle. The graph retains these distinct stages and the local API/UI. Links for unsampled subsystems follow documented capabilities; uncertain implementation wiring is omitted.

Main entry points: [`tracecrypt/document/attribution_pipeline.py`](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/attribution_pipeline.py) (Decryption attribution), [`tracecrypt/forensics/engine.py`](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/engine.py) (Investigation engine), [`tracecrypt/identity/certificate.py`](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/identity/certificate.py) (Certificates), [`tracecrypt/document/package.py`](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/package.py) (Package creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and crypto"]
  node_rootca["Root CA<br/>[ca.py]"]
  node_certificates["Certificates<br/>[certificate.py]"]
  node_pqc["PQC crypto"]
end

subgraph group_documents["Document workflow"]
  node_package["Package creation<br/>[package.py]"]
  node_encryption["Encryption and wrapping<br/>[encryption.py]"]
  node_validation["Package validation<br/>[validator.py]"]
  node_attribution["Decryption attribution"]
  node_watermark["Watermarking"]
end

subgraph group_ledger["Permissioned ledger"]
  node_signedevent["Signed events"]
  node_bft["BFT ledger<br/>[node.py]"]
  node_ledgerstorage[("Ledger storage<br/>[storage.py]")]
end

subgraph group_forensics["Forensic investigation"]
  node_evidence["Evidence ingestion<br/>[ingestion.py]"]
  node_investigation["Investigation engine<br/>[engine.py]"]
  node_extraction["Watermark extraction<br/>[extractor.py]"]
  node_proof["Proof and verdict<br/>[proof_bundle.py]"]
end

subgraph group_interface["Local interface"]
  node_api["Local API<br/>[app.py]"]
  node_ui["Web UI<br/>[app.js]"]
  node_localstore[("Local metadata store<br/>[sqlite_store.py]")]
end

node_sender(("Sender"))
node_recipient(("Recipient"))
node_investigator(("Investigator"))

node_sender -->|"submits document"| node_package
node_package -->|"encrypts and wraps"| node_encryption
node_package -->|"uses recipient certificates"| node_certificates
node_rootca -->|"issues"| node_certificates
node_recipient -->|"decrypts package"| node_attribution
node_attribution -->|"validates package"| node_validation
node_attribution -->|"decapsulates keys"| node_pqc
node_attribution -->|"checks credentials"| node_certificates
node_attribution -->|"embeds watermark"| node_watermark
node_attribution -->|"builds and signs event"| node_signedevent
node_attribution -->|"submits transaction"| node_bft
node_signedevent -->|"signs with"| node_pqc
node_bft -->|"persists chain"| node_ledgerstorage
node_investigator -->|"submits leak"| node_investigation
node_investigation -->|"ingests evidence"| node_evidence
node_investigation -->|"extracts watermark"| node_extraction
node_investigation -->|"looks up event"| node_ledgerstorage
node_investigation -->|"creates proof and verdict"| node_proof
node_investigation -->|"validates identity"| node_certificates
node_ui -->|"sends requests"| node_api
node_api -->|"reads and writes metadata"| node_localstore
node_api -->|"retrieves ledger events"| node_ledgerstorage

click node_rootca "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/identity/ca.py"
click node_certificates "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/identity/certificate.py"
click node_pqc "https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/crypto"
click node_package "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/package.py"
click node_encryption "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/encryption.py"
click node_validation "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/validator.py"
click node_attribution "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/attribution_pipeline.py"
click node_watermark "https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/watermark"
click node_signedevent "https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/event"
click node_bft "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ledger/node.py"
click node_ledgerstorage "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ledger/storage.py"
click node_evidence "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/ingestion.py"
click node_investigation "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/engine.py"
click node_extraction "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/watermark/extractor.py"
click node_proof "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/proof_bundle.py"
click node_api "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/api/app.py"
click node_ui "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ui/web/app.js"
click node_localstore "https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/storage/sqlite_store.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_rootca,node_certificates,node_pqc toneBlue
class node_package,node_encryption,node_validation,node_attribution,node_watermark toneAmber
class node_signedevent,node_bft,node_ledgerstorage toneMint
class node_evidence,node_investigation,node_extraction,node_proof toneRose
class node_api,node_ui,node_localstore,node_sender,node_recipient,node_investigator toneIndigo
```

## Components

### Identity and crypto

- [Root CA](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/identity/ca.py): `tracecrypt/identity/ca.py`
- [Certificates](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/identity/certificate.py): `tracecrypt/identity/certificate.py`
- [PQC crypto](https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/crypto): `tracecrypt/crypto`

### Document workflow

- [Package creation](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/package.py): `tracecrypt/document/package.py`
- [Encryption and wrapping](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/encryption.py): `tracecrypt/document/encryption.py`
- [Package validation](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/validator.py): `tracecrypt/document/validator.py`
- [Decryption attribution](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/document/attribution_pipeline.py): `tracecrypt/document/attribution_pipeline.py`
- [Watermarking](https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/watermark): `tracecrypt/watermark`

### Permissioned ledger

- [Signed events](https://github.com/adarshh025/tracecrypt/tree/main/tracecrypt/event): `tracecrypt/event`
- [BFT ledger](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ledger/node.py): `tracecrypt/ledger/node.py`
- [Ledger storage](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ledger/storage.py): `tracecrypt/ledger/storage.py`

### Forensic investigation

- [Evidence ingestion](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/ingestion.py): `tracecrypt/forensics/ingestion.py`
- [Investigation engine](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/engine.py): `tracecrypt/forensics/engine.py`
- [Watermark extraction](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/watermark/extractor.py): `tracecrypt/watermark/extractor.py`
- [Proof and verdict](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/forensics/proof_bundle.py): `tracecrypt/forensics/proof_bundle.py`

### Local interface

- [Local API](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/api/app.py): `tracecrypt/api/app.py`
- [Web UI](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/ui/web/app.js): `tracecrypt/ui/web/app.js`
- [Local metadata store](https://github.com/adarshh025/tracecrypt/blob/main/tracecrypt/storage/sqlite_store.py): `tracecrypt/storage/sqlite_store.py`

### Other components

- **Sender**
- **Recipient**
- **Investigator**

## Connections

- Sender → Package creation: submits document
- Package creation → Encryption and wrapping: encrypts and wraps
- Package creation → Certificates: uses recipient certificates
- Root CA → Certificates: issues
- Recipient → Decryption attribution: decrypts package
- Decryption attribution → Package validation: validates package
- Decryption attribution → PQC crypto: decapsulates keys
- Decryption attribution → Certificates: checks credentials
- Decryption attribution → Watermarking: embeds watermark
- Decryption attribution → Signed events: builds and signs event
- Decryption attribution → BFT ledger: submits transaction
- Signed events → PQC crypto: signs with
- BFT ledger → Ledger storage: persists chain
- Investigator → Investigation engine: submits leak
- Investigation engine → Evidence ingestion: ingests evidence
- Investigation engine → Watermark extraction: extracts watermark
- Investigation engine → Ledger storage: looks up event
- Investigation engine → Proof and verdict: creates proof and verdict
- Investigation engine → Certificates: validates identity
- Web UI → Local API: sends requests
- Local API → Local metadata store: reads and writes metadata
- Local API → Ledger storage: retrieves ledger events