# dvcyberspace/truetrail architecture

> Architecture diagram of the GitHub repository dvcyberspace/truetrail, 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/dvcyberspace/truetrail
- Repository: https://github.com/dvcyberspace/truetrail

## Overview

TrueTrail is a forensic evidence ingestion API: users submit evidence files, which are identified and parsed into canonical records, reconciled, and stored for API access. Its documented inputs cover UPI, bank statements, CDR, IPDR, and device extractions; outputs include transactions, calls, IP sessions, device artifacts, evidence provenance, rejected rows, and summaries. The excerpts support the ingestion and persistence flow, but do not show a graphing or timeline-reconstruction implementation. Parser-to-helper links follow the SOURCE INDEX; unsampled API behavior is not inferred.

Main entry points: [`backend/ingestion/pipeline.py`](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py) (Ingestion pipeline), [`backend/api.py`](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/api.py) (Ingestion API), [`backend/ingestion/parsers/base.py`](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/base.py) (Row parsing and dedupe), [`backend/ingestion/normalizers.py`](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/normalizers.py) (Field normalizers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Evidence ingestion"]
  node_evidence_files["Evidence files"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
end

subgraph group_parsing["Parsing and normalization"]
  node_config["Source format rules<br/>[config.py]"]
  node_upi["UPI parser<br/>[upi.py]"]
  node_bank["Bank statement parser<br/>[bank_statement.py]"]
  node_cdr["CDR parser<br/>[cdr.py]"]
  node_ipdr["IPDR parser<br/>[ipdr.py]"]
  node_device["Device extraction parser"]
  node_row_tools["Row parsing and dedupe<br/>[base.py]"]
  node_normalizers["Field normalizers<br/>[normalizers.py]"]
end

subgraph group_domain["Canonical records"]
  node_canonical["Canonical data contract<br/>[schemas.py]"]
  node_reconcile["Transaction reconciliation<br/>[pipeline.py]"]
  node_records["Parsed evidence records<br/>[pipeline.py]"]
end

subgraph group_service["API and storage"]
  node_api["Ingestion API<br/>[api.py]"]
  node_store[("SQLite evidence store<br/>[storage.py]")]
  node_api_results["Evidence and record APIs<br/>[api.py]"]
end

node_user(("Evidence submitter"))

node_user -->|"submits files"| node_api
node_api -->|"saves uploads"| node_evidence_files
node_api -->|"invokes ingestion"| node_pipeline
node_evidence_files -->|"scans files"| node_pipeline
node_pipeline -->|"uses format rules"| node_config
node_pipeline -->|"dispatches to"| node_upi
node_pipeline -->|"dispatches to"| node_bank
node_pipeline -->|"dispatches to"| node_cdr
node_pipeline -->|"dispatches to"| node_ipdr
node_pipeline -->|"dispatches to"| node_device
node_upi -->|"normalizes fields"| node_normalizers
node_bank -->|"normalizes fields"| node_normalizers
node_cdr -->|"normalizes fields"| node_normalizers
node_ipdr -->|"normalizes fields"| node_normalizers
node_device -->|"normalizes fields"| node_normalizers
node_upi -->|"consumes rows"| node_row_tools
node_bank -->|"consumes rows"| node_row_tools
node_cdr -->|"consumes rows"| node_row_tools
node_ipdr -->|"consumes rows"| node_row_tools
node_device -->|"consumes rows"| node_row_tools
node_upi -->|"builds records"| node_canonical
node_bank -->|"builds records"| node_canonical
node_cdr -->|"builds records"| node_canonical
node_ipdr -->|"builds records"| node_canonical
node_device -->|"builds records"| node_canonical
node_pipeline -->|"reconciles transactions"| node_reconcile
node_pipeline -->|"assembles results"| node_records
node_reconcile -->|"updates transactions"| node_records
node_api -->|"replaces stored data"| node_store
node_records -->|"persists results"| node_store
node_api -->|"reads records"| node_store
node_api -->|"serves endpoints"| node_api_results
node_store -->|"supplies stored results"| node_api_results

click node_api "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/api.py"
click node_pipeline "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py"
click node_config "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/config.py"
click node_upi "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/upi.py"
click node_bank "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/bank_statement.py"
click node_cdr "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/cdr.py"
click node_ipdr "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/ipdr.py"
click node_device "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/device_forensics.py"
click node_row_tools "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/base.py"
click node_normalizers "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/normalizers.py"
click node_canonical "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/schemas.py"
click node_reconcile "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py"
click node_records "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py"
click node_store "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/storage.py"
click node_api_results "https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/api.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_evidence_files,node_pipeline toneBlue
class node_config,node_upi,node_bank,node_cdr,node_ipdr,node_device,node_row_tools,node_normalizers toneAmber
class node_canonical,node_reconcile,node_records toneMint
class node_api,node_store,node_api_results toneRose
class node_user toneIndigo
```

## Components

### Evidence ingestion

- **Evidence files**
- [Ingestion pipeline](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py): `backend/ingestion/pipeline.py`

### Parsing and normalization

- [Source format rules](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/config.py): `backend/ingestion/config.py`
- [UPI parser](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/upi.py): `backend/ingestion/parsers/upi.py`
- [Bank statement parser](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/bank_statement.py): `backend/ingestion/parsers/bank_statement.py`
- [CDR parser](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/cdr.py): `backend/ingestion/parsers/cdr.py`
- [IPDR parser](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/ipdr.py): `backend/ingestion/parsers/ipdr.py`
- [Device extraction parser](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/device_forensics.py): `backend/ingestion/parsers/device_forensics.py`
- [Row parsing and dedupe](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/parsers/base.py): `backend/ingestion/parsers/base.py`
- [Field normalizers](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/normalizers.py): `backend/ingestion/normalizers.py`

### Canonical records

- [Canonical data contract](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/schemas.py): `backend/schemas.py`
- [Transaction reconciliation](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py): `backend/ingestion/pipeline.py`
- [Parsed evidence records](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/ingestion/pipeline.py): `backend/ingestion/pipeline.py`

### API and storage

- [Ingestion API](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/api.py): `backend/api.py`
- [SQLite evidence store](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/storage.py): `backend/storage.py`
- [Evidence and record APIs](https://github.com/dvcyberspace/truetrail/blob/phase-1/backend/api.py): `backend/api.py`

### Other components

- **Evidence submitter**

## Connections

- Evidence submitter → Ingestion API: submits files (evidence: `README.md`)
- Ingestion API → Evidence files: saves uploads (evidence: `backend/api.py`)
- Ingestion API → Ingestion pipeline: invokes ingestion (evidence: `backend/api.py`)
- Evidence files → Ingestion pipeline: scans files (evidence: `README.md`)
- Ingestion pipeline → Source format rules: uses format rules (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → UPI parser: dispatches to (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Bank statement parser: dispatches to (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → CDR parser: dispatches to (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → IPDR parser: dispatches to (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Device extraction parser: dispatches to (evidence: `backend/ingestion/pipeline.py`)
- UPI parser → Field normalizers: normalizes fields (evidence: `backend/ingestion/parsers/upi.py`)
- Bank statement parser → Field normalizers: normalizes fields (evidence: `backend/ingestion/parsers/bank_statement.py`)
- CDR parser → Field normalizers: normalizes fields (evidence: `backend/ingestion/parsers/cdr.py`)
- IPDR parser → Field normalizers: normalizes fields (evidence: `backend/ingestion/parsers/ipdr.py`)
- Device extraction parser → Field normalizers: normalizes fields (evidence: `backend/ingestion/parsers/device_forensics.py`)
- UPI parser → Row parsing and dedupe: consumes rows (evidence: `backend/ingestion/parsers/upi.py`)
- Bank statement parser → Row parsing and dedupe: consumes rows (evidence: `backend/ingestion/parsers/bank_statement.py`)
- CDR parser → Row parsing and dedupe: consumes rows (evidence: `backend/ingestion/parsers/cdr.py`)
- IPDR parser → Row parsing and dedupe: consumes rows (evidence: `backend/ingestion/parsers/ipdr.py`)
- Device extraction parser → Row parsing and dedupe: consumes rows (evidence: `backend/ingestion/parsers/device_forensics.py`)
- UPI parser → Canonical data contract: builds records (evidence: `backend/ingestion/parsers/upi.py`)
- Bank statement parser → Canonical data contract: builds records (evidence: `backend/ingestion/parsers/bank_statement.py`)
- CDR parser → Canonical data contract: builds records (evidence: `backend/ingestion/parsers/cdr.py`)
- IPDR parser → Canonical data contract: builds records (evidence: `backend/ingestion/parsers/ipdr.py`)
- Device extraction parser → Canonical data contract: builds records (evidence: `backend/ingestion/parsers/device_forensics.py`)
- Ingestion pipeline → Transaction reconciliation: reconciles transactions (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Parsed evidence records: assembles results (evidence: `backend/ingestion/pipeline.py`)
- Transaction reconciliation → Parsed evidence records: updates transactions (evidence: `backend/ingestion/pipeline.py`)
- Ingestion API → SQLite evidence store: replaces stored data (evidence: `backend/api.py`)
- Parsed evidence records → SQLite evidence store: persists results (evidence: `README.md`)
- Ingestion API → SQLite evidence store: reads records (evidence: `backend/api.py`)
- Ingestion API → Evidence and record APIs: serves endpoints (evidence: `backend/api.py`)
- SQLite evidence store → Evidence and record APIs: supplies stored results (evidence: `backend/api.py`)
