# codebyshambhavi/pramana-dfir architecture

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

- Interactive diagram: https://gitdiagram.com/codebyshambhavi/pramana-dfir
- Repository: https://github.com/codebyshambhavi/pramana-dfir

## Overview

PRAMANA is a local-first digital-forensics investigation platform: investigators intake artifacts, preserve their hashes and custody, extract normalized events, correlate and analyze those events, then review traceable findings and produce reports. The backend exposes case, evidence, analysis, integrity, graph and reporting capabilities; the React console presents the investigation workflow. The README documents the principal domain stages, while sampled source confirms key API, persistence, parser, intelligence and UI connections. Some router and frontend data wiring was not sampled, so those links are marked unverified or omitted.

Main entry points: [`backend/app/db/models.py`](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/models.py) (Normalized events), [`backend/app/main.py`](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/main.py) (REST API), [`backend/app/routers/evidence.py`](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/evidence.py) (Evidence API), [`evidence-engine/parsers`](https://github.com/codebyshambhavi/pramana-dfir/tree/main/evidence-engine/parsers) (Format parsers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Evidence intake"]
  node_hashing["SHA-256 intake<br/>[hashing.py]"]
  node_custody["Custody log<br/>[custody.py]"]
  node_parsers["Format parsers"]
  node_provenance["Event provenance<br/>[provenance.py]"]
  node_timestamps["Timestamp handling<br/>[timestamps.py]"]
  node_vocabulary["Event vocabulary<br/>[vocabulary.py]"]
end

subgraph group_analysis["Event analysis"]
  node_normalization["Event normalization<br/>[common.py]"]
  node_entities["Entity extraction<br/>[entities.py]"]
  node_correlation["Cross-source correlation<br/>[correlate.py]"]
  node_timeline["Timeline<br/>[timeline.py]"]
  node_claims_engine["Claim generation<br/>[claims.py]"]
  node_anomaly["Anomaly detection<br/>[anomalies.py]"]
  node_contradiction["Contradiction detection<br/>[contradictions.py]"]
  node_authenticity["Authenticity assessment<br/>[authenticity.py]"]
  node_hypotheses["Hypothesis engine<br/>[engine.py]"]
end

subgraph group_backend["Backend services"]
  node_evidence_api["Evidence API<br/>[evidence.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_events[("Normalized events<br/>[models.py]")]
  node_run_api["Analysis runs API<br/>[claims.py]"]
  node_run_service["Run orchestration<br/>[runs.py]"]
  node_run_store[("Run persistence<br/>[runs.py]")]
  node_claim_store[("Claim persistence<br/>[claims.py]")]
  node_case_api["Case management<br/>[cases.py]"]
  node_graph_builder["Evidence graph<br/>[builder.py]"]
  node_integrity_api["Integrity checks<br/>[integrity.py]"]
  node_finding_api["Finding review<br/>[findings.py]"]
  node_lineage["Evidence lineage<br/>[lineage.py]"]
  node_reporting["Investigation reports<br/>[export_pdf.py]"]
  node_api_entry["REST API<br/>[main.py]"]
end

subgraph group_console["Investigator console"]
  node_vault_ui["Evidence Vault<br/>[EvidenceVault.tsx]"]
  node_api_client["Typed API client<br/>[client.ts]"]
  node_workspace["Investigation workspace"]
end

node_investigator(("Investigator"))
node_artifact["Digital artifacts"]

node_investigator -->|"submits evidence"| node_vault_ui
node_artifact -->|"uploads"| node_evidence_api
node_vault_ui -.->|"requests intake"| node_evidence_api
node_evidence_api -->|"hashes evidence"| node_hashing
node_evidence_api -->|"records custody"| node_custody
node_evidence_api -.->|"extracts events"| node_parsers
node_parsers -->|"adds provenance"| node_provenance
node_parsers -->|"normalizes times"| node_timestamps
node_parsers -->|"maps vocabulary"| node_vocabulary
node_parsers -.->|"provides parsers"| node_pipeline
node_pipeline -.->|"persists events"| node_events
node_events -->|"supplies event data"| node_normalization
node_normalization -->|"normalizes input"| node_correlation
node_correlation -->|"extracts entities"| node_entities
node_events -->|"orders by time"| node_timeline
node_correlation -->|"generates claims"| node_claims_engine
node_events -->|"detects patterns"| node_anomaly
node_events -->|"checks conflicts"| node_contradiction
node_events -->|"assesses images"| node_authenticity
node_claims_engine -->|"evaluates explanations"| node_hypotheses
node_run_api -->|"creates runs"| node_run_service
node_run_service -->|"correlates events"| node_correlation
node_run_service -->|"evaluates hypotheses"| node_hypotheses
node_run_service -->|"stores run"| node_run_store
node_run_service -->|"stores claims"| node_claim_store
node_case_api -->|"serves case events"| node_events
node_events -->|"builds relationships"| node_graph_builder
node_integrity_api -->|"checks integrity"| node_custody
node_finding_api -->|"records review"| node_investigator
node_reporting -->|"includes lineage"| node_lineage
node_investigator -->|"reviews findings"| node_workspace
node_workspace -->|"requests analysis"| node_api_client
node_api_client -.->|"calls REST API"| node_api_entry
node_api_entry -->|"routes requests"| node_case_api
node_api_entry -->|"routes requests"| node_run_api
node_api_entry -->|"routes requests"| node_evidence_api
node_api_entry -->|"routes requests"| node_finding_api
node_api_entry -->|"routes requests"| node_integrity_api

click node_vault_ui "https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/pages/EvidenceVault.tsx"
click node_evidence_api "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/evidence.py"
click node_hashing "https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/intake/hashing.py"
click node_custody "https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/intake/custody.py"
click node_parsers "https://github.com/codebyshambhavi/pramana-dfir/tree/main/evidence-engine/parsers"
click node_provenance "https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/provenance.py"
click node_timestamps "https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/timestamps.py"
click node_vocabulary "https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/vocabulary.py"
click node_pipeline "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/services/pipeline.py"
click node_events "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/models.py"
click node_normalization "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/common.py"
click node_entities "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/entities.py"
click node_correlation "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/correlate.py"
click node_timeline "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/timeline.py"
click node_claims_engine "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/claims.py"
click node_anomaly "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/anomalies.py"
click node_contradiction "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/contradictions.py"
click node_authenticity "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/authenticity.py"
click node_hypotheses "https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/hyp/engine.py"
click node_run_api "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/claims.py"
click node_run_service "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/services/runs.py"
click node_run_store "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/runs.py"
click node_claim_store "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/claims.py"
click node_case_api "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/cases.py"
click node_graph_builder "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/graph/builder.py"
click node_integrity_api "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/integrity.py"
click node_finding_api "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/findings.py"
click node_lineage "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/reports/lineage.py"
click node_reporting "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/reports/export_pdf.py"
click node_api_entry "https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/main.py"
click node_api_client "https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/api/client.ts"
click node_workspace "https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/pages/InvestigationWorkspace.tsx"

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_hashing,node_custody,node_parsers,node_provenance,node_timestamps,node_vocabulary toneBlue
class node_normalization,node_entities,node_correlation,node_timeline,node_claims_engine,node_anomaly,node_contradiction,node_authenticity,node_hypotheses toneAmber
class node_evidence_api,node_pipeline,node_events,node_run_api,node_run_service,node_run_store,node_claim_store,node_case_api,node_graph_builder,node_integrity_api,node_finding_api,node_lineage,node_reporting,node_api_entry toneMint
class node_vault_ui,node_api_client,node_workspace toneRose
class node_investigator,node_artifact toneIndigo
```

## Components

### Evidence intake

- [SHA-256 intake](https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/intake/hashing.py): `evidence-engine/intake/hashing.py`
- [Custody log](https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/intake/custody.py): `evidence-engine/intake/custody.py`
- [Format parsers](https://github.com/codebyshambhavi/pramana-dfir/tree/main/evidence-engine/parsers): `evidence-engine/parsers`
- [Event provenance](https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/provenance.py): `evidence-engine/parsers/provenance.py`
- [Timestamp handling](https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/timestamps.py): `evidence-engine/parsers/timestamps.py`
- [Event vocabulary](https://github.com/codebyshambhavi/pramana-dfir/blob/main/evidence-engine/parsers/vocabulary.py): `evidence-engine/parsers/vocabulary.py`

### Event analysis

- [Event normalization](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/common.py): `intelligence/common.py`
- [Entity extraction](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/entities.py): `intelligence/entities.py`
- [Cross-source correlation](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/correlate.py): `intelligence/correlate.py`
- [Timeline](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/timeline.py): `intelligence/timeline.py`
- [Claim generation](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/claims.py): `intelligence/claims.py`
- [Anomaly detection](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/anomalies.py): `intelligence/anomalies.py`
- [Contradiction detection](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/contradictions.py): `intelligence/contradictions.py`
- [Authenticity assessment](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/authenticity.py): `intelligence/authenticity.py`
- [Hypothesis engine](https://github.com/codebyshambhavi/pramana-dfir/blob/main/intelligence/hyp/engine.py): `intelligence/hyp/engine.py`

### Backend services

- [Evidence API](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/evidence.py): `backend/app/routers/evidence.py`
- [Analysis pipeline](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [Normalized events](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Analysis runs API](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/claims.py): `backend/app/routers/claims.py`
- [Run orchestration](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/services/runs.py): `backend/app/services/runs.py`
- [Run persistence](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/runs.py): `backend/app/db/runs.py`
- [Claim persistence](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/db/claims.py): `backend/app/db/claims.py`
- [Case management](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/cases.py): `backend/app/routers/cases.py`
- [Evidence graph](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/graph/builder.py): `backend/app/graph/builder.py`
- [Integrity checks](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/integrity.py): `backend/app/routers/integrity.py`
- [Finding review](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/routers/findings.py): `backend/app/routers/findings.py`
- [Evidence lineage](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/reports/lineage.py): `backend/app/reports/lineage.py`
- [Investigation reports](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/reports/export_pdf.py): `backend/app/reports/export_pdf.py`
- [REST API](https://github.com/codebyshambhavi/pramana-dfir/blob/main/backend/app/main.py): `backend/app/main.py`

### Investigator console

- [Evidence Vault](https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/pages/EvidenceVault.tsx): `frontend/src/pages/EvidenceVault.tsx`
- [Typed API client](https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Investigation workspace](https://github.com/codebyshambhavi/pramana-dfir/blob/main/frontend/src/pages/InvestigationWorkspace.tsx): `frontend/src/pages/InvestigationWorkspace.tsx`

### Other components

- **Investigator**
- **Digital artifacts**

## Connections

- Investigator → Evidence Vault: submits evidence (evidence: `README.md`)
- Digital artifacts → Evidence API: uploads (evidence: `README.md`)
- Evidence Vault → Evidence API: requests intake
- Evidence API → SHA-256 intake: hashes evidence (evidence: `README.md`)
- Evidence API → Custody log: records custody (evidence: `README.md`)
- Evidence API → Format parsers: extracts events
- Format parsers → Event provenance: adds provenance (evidence: `evidence-engine/parsers/chat_json.py`)
- Format parsers → Timestamp handling: normalizes times (evidence: `evidence-engine/parsers/chat_json.py`)
- Format parsers → Event vocabulary: maps vocabulary (evidence: `evidence-engine/parsers/chat_json.py`)
- Format parsers → Analysis pipeline: provides parsers (evidence: `backend/app/services/pipeline.py`)
- Analysis pipeline → Normalized events: persists events
- Normalized events → Event normalization: supplies event data (evidence: `README.md`)
- Event normalization → Cross-source correlation: normalizes input (evidence: `intelligence/correlate.py`)
- Cross-source correlation → Entity extraction: extracts entities (evidence: `intelligence/correlate.py`)
- Normalized events → Timeline: orders by time (evidence: `README.md`)
- Cross-source correlation → Claim generation: generates claims (evidence: `intelligence/claims.py`)
- Normalized events → Anomaly detection: detects patterns (evidence: `README.md`)
- Normalized events → Contradiction detection: checks conflicts (evidence: `README.md`)
- Normalized events → Authenticity assessment: assesses images (evidence: `README.md`)
- Claim generation → Hypothesis engine: evaluates explanations (evidence: `README.md`)
- Analysis runs API → Run orchestration: creates runs (evidence: `backend/app/routers/claims.py`)
- Run orchestration → Cross-source correlation: correlates events (evidence: `backend/app/services/runs.py`)
- Run orchestration → Hypothesis engine: evaluates hypotheses (evidence: `backend/app/services/runs.py`)
- Run orchestration → Run persistence: stores run (evidence: `backend/app/services/runs.py`)
- Run orchestration → Claim persistence: stores claims (evidence: `backend/app/services/runs.py`)
- Case management → Normalized events: serves case events (evidence: `backend/app/routers/cases.py`)
- Normalized events → Evidence graph: builds relationships (evidence: `README.md`)
- Integrity checks → Custody log: checks integrity (evidence: `README.md`)
- Finding review → Investigator: records review (evidence: `README.md`)
- Investigation reports → Evidence lineage: includes lineage (evidence: `README.md`)
- Investigator → Investigation workspace: reviews findings (evidence: `README.md`)
- Investigation workspace → Typed API client: requests analysis (evidence: `frontend/src/pages/InvestigationWorkspace.tsx`)
- Typed API client → REST API: calls REST API
- REST API → Case management: routes requests (evidence: `backend/app/main.py`)
- REST API → Analysis runs API: routes requests (evidence: `backend/app/main.py`)
- REST API → Evidence API: routes requests (evidence: `backend/app/main.py`)
- REST API → Finding review: routes requests (evidence: `backend/app/main.py`)
- REST API → Integrity checks: routes requests (evidence: `backend/app/main.py`)
