# aannapoorani/adaptive-forensic-safety architecture

> Architecture diagram of the GitHub repository aannapoorani/adaptive-forensic-safety, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aannapoorani/adaptive-forensic-safety
- Repository: https://github.com/aannapoorani/adaptive-forensic-safety

## Overview

JOCKY is a multi-machine digital-forensics platform with an adaptive investigation workflow, evidence-integrity services, and a React management console. The principal flow is: an operator creates an investigation, the backend plans and runs collection rounds, analyzes evidence, and exposes results, timelines, reports, and chain verification. The README also documents a JOCKY DSL/compiler, polymorphic builds, evasion analysis, and CDN routing. Those capabilities are included, but their internal wiring is not inferred where source excerpts do not show it.

Main entry points: [`backend/app/services/investigation_service.py`](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/investigation_service.py) (Investigation Runner), [`backend/app/api/evasion.py`](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/evasion.py) (Evasion Routes), [`backend/app/api/investigations.py`](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/investigations.py) (Investigation Routes), [`backend/app/core/database.py`](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/core/database.py) (Relational Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Management Console"]
  node_app["Console Router<br/>[App.tsx]"]
  node_investigation_page["Investigation View"]
  node_api_client["API Client<br/>[api.ts]"]
end

subgraph group_investigation["Investigation Workflow"]
  node_api_server["FastAPI Routes<br/>[main.py]"]
  node_investigation_routes["Investigation Routes<br/>[investigations.py]"]
  node_investigation_service["Investigation Runner"]
  node_investigation_model["Investigation Records<br/>[investigation.py]"]
end

subgraph group_analysis["Collection And Analysis"]
  node_intent["Intent Profiles<br/>[intent_engine.py]"]
  node_evidence_graph["Evidence Graph<br/>[evidence_graph.py]"]
  node_workflow["Workflow Planner"]
  node_collectors["Collector Registry<br/>[registry.py]"]
  node_correlation["Correlation Engine"]
  node_machine_agent["Remote Agent<br/>[remote_agent.py]"]
  node_machine_model["Machine Records<br/>[machine.py]"]
  node_drivers["Driver Analysis<br/>[drivers.py]"]
end

subgraph group_integrity["Evidence Integrity"]
  node_evidence_model["Evidence Records<br/>[evidence.py]"]
  node_database[("Relational Store<br/>[database.py]")]
  node_chain_service["Chain Of Custody<br/>[chain_service.py]"]
  node_key_manager["Signing Keys<br/>[key_manager.py]"]
  node_verifier["Evidence Verifier"]
end

subgraph group_evasion["Evasion And DSL"]
  node_compiler["JOCKY Compiler<br/>[compiler.py]"]
  node_polymorphic["Polymorphic Engine<br/>[polymorphic.py]"]
  node_cdn["CDN Routing<br/>[cdn_routing.py]"]
  node_evasion_routes["Evasion Routes<br/>[evasion.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_app
node_app -->|"renders"| node_investigation_page
node_investigation_page -->|"requests data"| node_api_client
node_api_client -->|"calls endpoints"| node_investigation_routes
node_api_server -->|"registers routes"| node_investigation_routes
node_investigation_routes -->|"delegates"| node_investigation_service
node_investigation_service -->|"resolves intent"| node_intent
node_investigation_service -->|"builds graph"| node_evidence_graph
node_investigation_service -->|"plans steps"| node_workflow
node_investigation_service -->|"dispatches operations"| node_collectors
node_investigation_service -->|"correlates evidence"| node_correlation
node_investigation_service -->|"compiles scripts"| node_compiler
node_investigation_service -->|"persists rounds"| node_investigation_model
node_investigation_service -.->|"dispatches remotely"| node_machine_agent
node_machine_agent -.->|"manages machines"| node_machine_model
node_investigation_routes -.->|"exposes evasion APIs"| node_evasion_routes
node_evasion_routes -->|"builds variants"| node_polymorphic
node_evasion_routes -->|"runs driver probes"| node_drivers
node_evasion_routes -->|"configures routing"| node_cdn
node_investigation_service -.->|"records custody"| node_chain_service
node_chain_service -->|"stores provenance"| node_evidence_model
node_chain_service -->|"signs chain tip"| node_key_manager
node_verifier -->|"verifies artifacts"| node_evidence_model
node_investigation_service -->|"reads and writes"| node_database
node_database -->|"stores records"| node_investigation_model
node_database -->|"stores records"| node_evidence_model

click node_app "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/App.tsx"
click node_investigation_page "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/pages/InvestigationDetailPage.tsx"
click node_api_client "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/services/api.ts"
click node_api_server "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/main.py"
click node_investigation_routes "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/investigations.py"
click node_investigation_service "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/investigation_service.py"
click node_intent "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/intent_engine.py"
click node_evidence_graph "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/evidence_graph.py"
click node_workflow "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/workflow_planner.py"
click node_collectors "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/collectors/registry.py"
click node_correlation "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/correlation_engine.py"
click node_machine_agent "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/remote_agent.py"
click node_machine_model "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/machine.py"
click node_investigation_model "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/investigation.py"
click node_evidence_model "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/evidence.py"
click node_database "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/core/database.py"
click node_chain_service "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/chain_service.py"
click node_key_manager "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/core/key_manager.py"
click node_verifier "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/verifier_service.py"
click node_compiler "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/compiler.py"
click node_polymorphic "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/polymorphic.py"
click node_cdn "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/cdn_routing.py"
click node_evasion_routes "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/evasion.py"
click node_drivers "https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/collectors/drivers.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_investigation_page,node_api_client toneBlue
class node_api_server,node_investigation_routes,node_investigation_service,node_investigation_model toneAmber
class node_intent,node_evidence_graph,node_workflow,node_collectors,node_correlation,node_machine_agent,node_machine_model,node_drivers toneMint
class node_evidence_model,node_database,node_chain_service,node_key_manager,node_verifier toneRose
class node_compiler,node_polymorphic,node_cdn,node_evasion_routes,node_operator toneIndigo
```

## Components

### Management Console

- [Console Router](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Investigation View](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/pages/InvestigationDetailPage.tsx): `frontend/src/pages/InvestigationDetailPage.tsx`
- [API Client](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Investigation Workflow

- [FastAPI Routes](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/main.py): `backend/app/main.py`
- [Investigation Routes](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/investigations.py): `backend/app/api/investigations.py`
- [Investigation Runner](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/investigation_service.py): `backend/app/services/investigation_service.py`
- [Investigation Records](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/investigation.py): `backend/app/models/investigation.py`

### Collection And Analysis

- [Intent Profiles](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/intent_engine.py): `backend/app/intelligence/intent_engine.py`
- [Evidence Graph](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/evidence_graph.py): `backend/app/intelligence/evidence_graph.py`
- [Workflow Planner](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/workflow_planner.py): `backend/app/intelligence/workflow_planner.py`
- [Collector Registry](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/collectors/registry.py): `backend/app/collectors/registry.py`
- [Correlation Engine](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/intelligence/correlation_engine.py): `backend/app/intelligence/correlation_engine.py`
- [Remote Agent](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/remote_agent.py): `backend/app/services/remote_agent.py`
- [Machine Records](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/machine.py): `backend/app/models/machine.py`
- [Driver Analysis](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/collectors/drivers.py): `backend/app/collectors/drivers.py`

### Evidence Integrity

- [Evidence Records](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/models/evidence.py): `backend/app/models/evidence.py`
- [Relational Store](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Chain Of Custody](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/chain_service.py): `backend/app/services/chain_service.py`
- [Signing Keys](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/core/key_manager.py): `backend/app/core/key_manager.py`
- [Evidence Verifier](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/services/verifier_service.py): `backend/app/services/verifier_service.py`

### Evasion And DSL

- [JOCKY Compiler](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/compiler.py): `backend/app/jocky/compiler.py`
- [Polymorphic Engine](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/polymorphic.py): `backend/app/jocky/polymorphic.py`
- [CDN Routing](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/jocky/cdn_routing.py): `backend/app/jocky/cdn_routing.py`
- [Evasion Routes](https://github.com/aannapoorani/adaptive-forensic-safety/blob/main/backend/app/api/evasion.py): `backend/app/api/evasion.py`

### Other components

- **Operator**

## Connections

- Operator → Console Router: uses
- Console Router → Investigation View: renders (evidence: `frontend/src/App.tsx`)
- Investigation View → API Client: requests data (evidence: `frontend/src/pages/InvestigationDetailPage.tsx`)
- API Client → Investigation Routes: calls endpoints (evidence: `frontend/src/services/api.ts`)
- FastAPI Routes → Investigation Routes: registers routes (evidence: `backend/app/main.py`)
- Investigation Routes → Investigation Runner: delegates (evidence: `backend/app/api/investigations.py`)
- Investigation Runner → Intent Profiles: resolves intent (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Evidence Graph: builds graph (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Workflow Planner: plans steps (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Collector Registry: dispatches operations (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Correlation Engine: correlates evidence (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → JOCKY Compiler: compiles scripts (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Investigation Records: persists rounds (evidence: `backend/app/services/investigation_service.py`)
- Investigation Runner → Remote Agent: dispatches remotely
- Remote Agent → Machine Records: manages machines
- Investigation Routes → Evasion Routes: exposes evasion APIs
- Evasion Routes → Polymorphic Engine: builds variants (evidence: `backend/app/api/evasion.py`)
- Evasion Routes → Driver Analysis: runs driver probes (evidence: `backend/app/api/evasion.py`)
- Evasion Routes → CDN Routing: configures routing (evidence: `backend/app/api/evasion.py`)
- Investigation Runner → Chain Of Custody: records custody (evidence: `backend/app/services/investigation_service.py`)
- Chain Of Custody → Evidence Records: stores provenance (evidence: `backend/app/services/chain_service.py`)
- Chain Of Custody → Signing Keys: signs chain tip (evidence: `backend/app/services/chain_service.py`)
- Evidence Verifier → Evidence Records: verifies artifacts (evidence: `backend/app/services/verifier_service.py`)
- Investigation Runner → Relational Store: reads and writes (evidence: `backend/app/services/investigation_service.py`)
- Relational Store → Investigation Records: stores records (evidence: `backend/app/core/database.py`)
- Relational Store → Evidence Records: stores records (evidence: `backend/app/core/database.py`)
