# isuyildiz/forensicchain architecture

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

## Overview

ForensicChain manages evidence from role-gated upload through cryptographic proof, custody tracking, ledger review, and verifiable PDF reporting. The graph combines documented service workflows with UI routing shown in App.tsx. Several service internals and UI API modules were not excerpted, so their documented capabilities are represented without speculative implementation-level links; the gateway is omitted because it is not present in the supplied file tree.

Main entry points: [`forensic-ui/src/App.tsx`](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/App.tsx) (Route application), [`services/audit-reporter/routers/reports.py`](https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/routers/reports.py) (Audit reporter), [`services/evidence-collector/routers/evidence.py`](https://github.com/isuyildiz/forensicchain/blob/main/services/evidence-collector/routers/evidence.py) (Evidence collector), [`forensic-ui/src/pages/LoginPage.tsx`](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/LoginPage.tsx) (Login page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Forensic UI"]
  node_app["Route application<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_artifact_ui["Artifact pages"]
  node_upload_ui["Evidence upload"]
  node_ledger_ui["Ledger view<br/>[LedgerPage.tsx]"]
  node_report_ui["Report view<br/>[ReportPage.tsx]"]
  node_admin_ui["Admin console<br/>[AdminPage.tsx]"]
  node_auth_state["Token &amp; role state<br/>[useAuth.ts]"]
end

subgraph group_identity["Identity &amp; Cases"]
  node_auth_api["Authentication service<br/>[auth.py]"]
  node_auth_rbac["JWT and RBAC<br/>[internal.py]"]
  node_case_admin["Users &amp; cases<br/>[admin.py]"]
end

subgraph group_evidence["Evidence Integrity"]
  node_evidence_api["Evidence collector<br/>[evidence.py]"]
  node_hash_sign["Hash &amp; sign gRPC<br/>[servicer.py]"]
  node_hashing["Hash &amp; signature<br/>[hasher.py]"]
end

subgraph group_custody["Custody Events"]
  node_event_bus["RabbitMQ events"]
  node_custody_consumer["Custody consumer<br/>[consumer.py]"]
  node_custody_chain["Custody event chain<br/>[custody_chain.py]"]
  node_custody_api["Custody timeline API<br/>[custody.py]"]
end

subgraph group_audit["Ledger &amp; Reporting"]
  node_ledger_service["Immutable ledger<br/>[servicer.py]"]
  node_ledger_chain["Ledger hash chain<br/>[hash_chain.py]"]
  node_report_api["Audit reporter<br/>[reports.py]"]
  node_report_generator["PDF generator"]
  node_report_store[("Report records<br/>[models.py]")]
  node_ledger_rest["Ledger REST API<br/>[main.py]"]
end

node_user(("Forensic user"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_upload_ui
node_app -->|"routes to"| node_artifact_ui
node_app -->|"routes to"| node_ledger_ui
node_app -->|"routes to"| node_report_ui
node_app -->|"routes to"| node_admin_ui
node_login -.->|"stores token"| node_auth_state
node_login -.->|"logs in"| node_auth_api
node_auth_api -->|"issues JWT"| node_auth_rbac
node_auth_rbac -.->|"checks assignments"| node_case_admin
node_admin_ui -.->|"manages users &amp; cases"| node_case_admin
node_upload_ui -.->|"uploads evidence"| node_evidence_api
node_evidence_api -->|"requests signature"| node_hash_sign
node_hash_sign -->|"computes &amp; signs"| node_hashing
node_evidence_api -->|"appends proof"| node_ledger_service
node_evidence_api -->|"publishes events"| node_event_bus
node_event_bus -->|"delivers events"| node_custody_consumer
node_custody_consumer -.->|"chains events"| node_custody_chain
node_custody_api -.->|"reads timeline"| node_custody_chain
node_ledger_service -->|"chains records"| node_ledger_chain
node_report_api -->|"fetches metadata"| node_evidence_api
node_report_api -->|"fetches timeline"| node_custody_api
node_report_api -->|"fetches proof"| node_ledger_rest
node_report_api -->|"renders PDF"| node_report_generator
node_report_api -->|"stores report"| node_report_store
node_report_api -->|"anchors report hash"| node_ledger_service
node_ledger_ui -.->|"views chain"| node_ledger_rest
node_artifact_ui -.->|"views timeline"| node_custody_api
node_report_ui -.->|"requests report"| node_report_api

click node_app "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/App.tsx"
click node_login "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/LoginPage.tsx"
click node_artifact_ui "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ArtifactDetailPage.tsx"
click node_upload_ui "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ArtifactUploadPage.tsx"
click node_ledger_ui "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/LedgerPage.tsx"
click node_report_ui "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ReportPage.tsx"
click node_admin_ui "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/AdminPage.tsx"
click node_auth_state "https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/hooks/useAuth.ts"
click node_auth_api "https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/auth.py"
click node_auth_rbac "https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/internal.py"
click node_case_admin "https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/admin.py"
click node_evidence_api "https://github.com/isuyildiz/forensicchain/blob/main/services/evidence-collector/routers/evidence.py"
click node_hash_sign "https://github.com/isuyildiz/forensicchain/blob/main/services/hash-sign/servicer.py"
click node_hashing "https://github.com/isuyildiz/forensicchain/blob/main/services/hash-sign/crypto/hasher.py"
click node_ledger_service "https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/servicer.py"
click node_ledger_chain "https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/chain/hash_chain.py"
click node_custody_consumer "https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/consumer.py"
click node_custody_chain "https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/chain/custody_chain.py"
click node_custody_api "https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/routers/custody.py"
click node_report_api "https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/routers/reports.py"
click node_report_generator "https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/report_generator.py"
click node_report_store "https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/db/models.py"
click node_ledger_rest "https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/main.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_app,node_login,node_artifact_ui,node_upload_ui,node_ledger_ui,node_report_ui,node_admin_ui,node_auth_state,node_user toneBlue
class node_auth_api,node_auth_rbac,node_case_admin toneAmber
class node_evidence_api,node_hash_sign,node_hashing toneMint
class node_event_bus,node_custody_consumer,node_custody_chain,node_custody_api toneRose
class node_ledger_service,node_ledger_chain,node_report_api,node_report_generator,node_report_store,node_ledger_rest toneIndigo
```

## Components

### Forensic UI

- [Route application](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/App.tsx): `forensic-ui/src/App.tsx`
- [Login page](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/LoginPage.tsx): `forensic-ui/src/pages/LoginPage.tsx`
- [Artifact pages](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ArtifactDetailPage.tsx): `forensic-ui/src/pages/ArtifactDetailPage.tsx`
- [Evidence upload](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ArtifactUploadPage.tsx): `forensic-ui/src/pages/ArtifactUploadPage.tsx`
- [Ledger view](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/LedgerPage.tsx): `forensic-ui/src/pages/LedgerPage.tsx`
- [Report view](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/ReportPage.tsx): `forensic-ui/src/pages/ReportPage.tsx`
- [Admin console](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/pages/AdminPage.tsx): `forensic-ui/src/pages/AdminPage.tsx`
- [Token & role state](https://github.com/isuyildiz/forensicchain/blob/main/forensic-ui/src/hooks/useAuth.ts): `forensic-ui/src/hooks/useAuth.ts`

### Identity & Cases

- [Authentication service](https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/auth.py): `services/auth-service/routers/auth.py`
- [JWT and RBAC](https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/internal.py): `services/auth-service/routers/internal.py`
- [Users & cases](https://github.com/isuyildiz/forensicchain/blob/main/services/auth-service/routers/admin.py): `services/auth-service/routers/admin.py`

### Evidence Integrity

- [Evidence collector](https://github.com/isuyildiz/forensicchain/blob/main/services/evidence-collector/routers/evidence.py): `services/evidence-collector/routers/evidence.py`
- [Hash & sign gRPC](https://github.com/isuyildiz/forensicchain/blob/main/services/hash-sign/servicer.py): `services/hash-sign/servicer.py`
- [Hash & signature](https://github.com/isuyildiz/forensicchain/blob/main/services/hash-sign/crypto/hasher.py): `services/hash-sign/crypto/hasher.py`

### Custody Events

- **RabbitMQ events**
- [Custody consumer](https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/consumer.py): `services/chain-of-custody/consumer.py`
- [Custody event chain](https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/chain/custody_chain.py): `services/chain-of-custody/chain/custody_chain.py`
- [Custody timeline API](https://github.com/isuyildiz/forensicchain/blob/main/services/chain-of-custody/routers/custody.py): `services/chain-of-custody/routers/custody.py`

### Ledger & Reporting

- [Immutable ledger](https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/servicer.py): `services/immutable-ledger/servicer.py`
- [Ledger hash chain](https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/chain/hash_chain.py): `services/immutable-ledger/chain/hash_chain.py`
- [Audit reporter](https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/routers/reports.py): `services/audit-reporter/routers/reports.py`
- [PDF generator](https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/report_generator.py): `services/audit-reporter/report_generator.py`
- [Report records](https://github.com/isuyildiz/forensicchain/blob/main/services/audit-reporter/db/models.py): `services/audit-reporter/db/models.py`
- [Ledger REST API](https://github.com/isuyildiz/forensicchain/blob/main/services/immutable-ledger/main.py): `services/immutable-ledger/main.py`

### Other components

- **Forensic user**

## Connections

- Forensic user → Route application: uses (evidence: `README.md`)
- Route application → Login page: routes to (evidence: `forensic-ui/src/App.tsx`)
- Route application → Evidence upload: routes to (evidence: `forensic-ui/src/App.tsx`)
- Route application → Artifact pages: routes to (evidence: `forensic-ui/src/App.tsx`)
- Route application → Ledger view: routes to (evidence: `forensic-ui/src/App.tsx`)
- Route application → Report view: routes to (evidence: `forensic-ui/src/App.tsx`)
- Route application → Admin console: routes to (evidence: `forensic-ui/src/App.tsx`)
- Login page → Token & role state: stores token
- Login page → Authentication service: logs in
- Authentication service → JWT and RBAC: issues JWT (evidence: `README.md`)
- JWT and RBAC → Users & cases: checks assignments
- Admin console → Users & cases: manages users & cases
- Evidence upload → Evidence collector: uploads evidence
- Evidence collector → Hash & sign gRPC: requests signature (evidence: `README.md`)
- Hash & sign gRPC → Hash & signature: computes & signs (evidence: `services/hash-sign/servicer.py`)
- Evidence collector → Immutable ledger: appends proof (evidence: `README.md`)
- Evidence collector → RabbitMQ events: publishes events (evidence: `README.md`)
- RabbitMQ events → Custody consumer: delivers events
- Custody consumer → Custody event chain: chains events
- Custody timeline API → Custody event chain: reads timeline
- Immutable ledger → Ledger hash chain: chains records (evidence: `services/immutable-ledger/servicer.py`)
- Audit reporter → Evidence collector: fetches metadata
- Audit reporter → Custody timeline API: fetches timeline (evidence: `README.md`)
- Audit reporter → Ledger REST API: fetches proof (evidence: `README.md`)
- Audit reporter → PDF generator: renders PDF (evidence: `README.md`)
- Audit reporter → Report records: stores report (evidence: `README.md`)
- Audit reporter → Immutable ledger: anchors report hash (evidence: `README.md`)
- Ledger view → Ledger REST API: views chain
- Artifact pages → Custody timeline API: views timeline
- Report view → Audit reporter: requests report
