# arjun-m-b/hydra architecture

> Architecture diagram of the GitHub repository arjun-m-b/hydra, 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/arjun-m-b/hydra
- Repository: https://github.com/arjun-m-b/hydra

## Overview

HYDRA protects synthetic medical records by encrypting them across two peer servers, with key shares held by each server and a client token. The main lifecycle is record preparation and initialization, encrypted storage and mirroring, anomaly detection, then breach-triggered key evolution, re-encryption, failover, isolation, and audit. Users operate the system through the CLI or dashboard; the dashboard also exposes monitoring, audit inspection, cryptography inspection, patient exploration, and breach simulation. README capabilities supplement the partial source excerpts, so uncertain internal wiring is omitted.

Main entry points: [`server_a/app.py`](https://github.com/arjun-m-b/hydra/blob/main/server_a/app.py) (Server A), [`server_b/app.py`](https://github.com/arjun-m-b/hydra/blob/main/server_b/app.py) (Server B), [`run.py`](https://github.com/arjun-m-b/hydra/blob/main/run.py) (System Launcher), [`client/cli.py`](https://github.com/arjun-m-b/hydra/blob/main/client/cli.py) (Command Line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Operations and Clients"]
  node_launcher["System Launcher<br/>[run.py]"]
  node_cli["Command Line<br/>[cli.py]"]
  node_token["Client Token<br/>[token.py]"]
  node_dashboard["Dashboard Core<br/>[app.js]"]
  node_dashboard_pages["Dashboard Views"]
end

subgraph group_records["Medical Records"]
  node_raw_data["Synthea Records"]
  node_preprocess["Record Preprocessing<br/>[preprocess.py]"]
  node_ready_records["Prepared Records<br/>[records.json]"]
end

subgraph group_servers["Dual Server Runtime"]
  node_server_a["Server A<br/>[app.py]"]
  node_server_b["Server B<br/>[app.py]"]
  node_store_a[("A Record Store<br/>[store.py]")]
  node_store_b[("B Record Store<br/>[store.py]")]
  node_heartbeat["Peer Heartbeat<br/>[heartbeat.py]"]
end

subgraph group_security["Security and Recovery"]
  node_breach_a["A Breach Detection<br/>[breach.py]"]
  node_breach_b["B Breach Detection<br/>[breach.py]"]
  node_ratchet["Key Ratchet<br/>[hkdf.py]"]
  node_reencrypt["Record Re-encryption<br/>[reencrypt.py]"]
  node_secret_sharing["Secret Sharing<br/>[shamir.py]"]
  node_proofs["Failover Proofs<br/>[zkp.py]"]
  node_cipher["Authenticated Encryption<br/>[xchacha20.py]"]
end

subgraph group_visibility["Monitoring and Audit"]
  node_audit["Hash-chain Audit<br/>[audit.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts system"| node_launcher
node_operator -->|"uses commands"| node_cli
node_operator -->|"views system"| node_dashboard
node_launcher -->|"starts"| node_server_a
node_launcher -->|"starts"| node_server_b
node_launcher -->|"creates shares"| node_secret_sharing
node_launcher -->|"loads records"| node_ready_records
node_raw_data -->|"normalizes"| node_preprocess
node_preprocess -->|"writes"| node_ready_records
node_cli -->|"calls API"| node_server_a
node_cli -.->|"fails over"| node_server_b
node_cli -->|"uses token"| node_token
node_dashboard -->|"polls API"| node_server_a
node_dashboard -->|"polls API"| node_server_b
node_dashboard_pages -->|"uses API"| node_dashboard
node_server_a -->|"reads and writes"| node_store_a
node_server_b -->|"reads and writes"| node_store_b
node_server_a -->|"mirrors records"| node_server_b
node_server_b -->|"syncs records"| node_server_a
node_heartbeat -->|"synchronizes"| node_server_a
node_heartbeat -->|"synchronizes"| node_server_b
node_server_a -->|"updates score"| node_breach_a
node_server_b -->|"updates score"| node_breach_b
node_server_a -->|"derives key"| node_ratchet
node_server_b -->|"derives key"| node_ratchet
node_server_a -->|"re-encrypts records"| node_reencrypt
node_server_b -->|"re-encrypts records"| node_reencrypt
node_server_a -->|"verifies promotion"| node_proofs
node_server_b -->|"proves share"| node_proofs
node_server_a -->|"encrypts records"| node_cipher
node_server_b -->|"encrypts records"| node_cipher
node_server_a -->|"records events"| node_audit
node_server_b -->|"records events"| node_audit

click node_launcher "https://github.com/arjun-m-b/hydra/blob/main/run.py"
click node_cli "https://github.com/arjun-m-b/hydra/blob/main/client/cli.py"
click node_token "https://github.com/arjun-m-b/hydra/blob/main/client/token.py"
click node_dashboard "https://github.com/arjun-m-b/hydra/blob/main/dashboard/app.js"
click node_dashboard_pages "https://github.com/arjun-m-b/hydra/tree/main/dashboard/pages"
click node_raw_data "https://github.com/arjun-m-b/hydra/blob/main/data/raw/synthea_patients.json"
click node_preprocess "https://github.com/arjun-m-b/hydra/blob/main/data/preprocess.py"
click node_ready_records "https://github.com/arjun-m-b/hydra/blob/main/data/processed/records.json"
click node_server_a "https://github.com/arjun-m-b/hydra/blob/main/server_a/app.py"
click node_server_b "https://github.com/arjun-m-b/hydra/blob/main/server_b/app.py"
click node_store_a "https://github.com/arjun-m-b/hydra/blob/main/server_a/store.py"
click node_store_b "https://github.com/arjun-m-b/hydra/blob/main/server_b/store.py"
click node_heartbeat "https://github.com/arjun-m-b/hydra/blob/main/heartbeat.py"
click node_breach_a "https://github.com/arjun-m-b/hydra/blob/main/server_a/breach.py"
click node_breach_b "https://github.com/arjun-m-b/hydra/blob/main/server_b/breach.py"
click node_ratchet "https://github.com/arjun-m-b/hydra/blob/main/core/hkdf.py"
click node_reencrypt "https://github.com/arjun-m-b/hydra/blob/main/reencrypt.py"
click node_secret_sharing "https://github.com/arjun-m-b/hydra/blob/main/core/shamir.py"
click node_proofs "https://github.com/arjun-m-b/hydra/blob/main/core/zkp.py"
click node_cipher "https://github.com/arjun-m-b/hydra/blob/main/core/xchacha20.py"
click node_audit "https://github.com/arjun-m-b/hydra/blob/main/core/audit.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_launcher,node_cli,node_token,node_dashboard,node_dashboard_pages toneBlue
class node_raw_data,node_preprocess,node_ready_records toneAmber
class node_server_a,node_server_b,node_store_a,node_store_b,node_heartbeat toneMint
class node_breach_a,node_breach_b,node_ratchet,node_reencrypt,node_secret_sharing,node_proofs,node_cipher toneRose
class node_audit,node_operator toneIndigo
```

## Components

### Operations and Clients

- [System Launcher](https://github.com/arjun-m-b/hydra/blob/main/run.py): `run.py`
- [Command Line](https://github.com/arjun-m-b/hydra/blob/main/client/cli.py): `client/cli.py`
- [Client Token](https://github.com/arjun-m-b/hydra/blob/main/client/token.py): `client/token.py`
- [Dashboard Core](https://github.com/arjun-m-b/hydra/blob/main/dashboard/app.js): `dashboard/app.js`
- [Dashboard Views](https://github.com/arjun-m-b/hydra/tree/main/dashboard/pages): `dashboard/pages`

### Medical Records

- [Synthea Records](https://github.com/arjun-m-b/hydra/blob/main/data/raw/synthea_patients.json): `data/raw/synthea_patients.json`
- [Record Preprocessing](https://github.com/arjun-m-b/hydra/blob/main/data/preprocess.py): `data/preprocess.py`
- [Prepared Records](https://github.com/arjun-m-b/hydra/blob/main/data/processed/records.json): `data/processed/records.json`

### Dual Server Runtime

- [Server A](https://github.com/arjun-m-b/hydra/blob/main/server_a/app.py): `server_a/app.py`
- [Server B](https://github.com/arjun-m-b/hydra/blob/main/server_b/app.py): `server_b/app.py`
- [A Record Store](https://github.com/arjun-m-b/hydra/blob/main/server_a/store.py): `server_a/store.py`
- [B Record Store](https://github.com/arjun-m-b/hydra/blob/main/server_b/store.py): `server_b/store.py`
- [Peer Heartbeat](https://github.com/arjun-m-b/hydra/blob/main/heartbeat.py): `heartbeat.py`

### Security and Recovery

- [A Breach Detection](https://github.com/arjun-m-b/hydra/blob/main/server_a/breach.py): `server_a/breach.py`
- [B Breach Detection](https://github.com/arjun-m-b/hydra/blob/main/server_b/breach.py): `server_b/breach.py`
- [Key Ratchet](https://github.com/arjun-m-b/hydra/blob/main/core/hkdf.py): `core/hkdf.py`
- [Record Re-encryption](https://github.com/arjun-m-b/hydra/blob/main/reencrypt.py): `reencrypt.py`
- [Secret Sharing](https://github.com/arjun-m-b/hydra/blob/main/core/shamir.py): `core/shamir.py`
- [Failover Proofs](https://github.com/arjun-m-b/hydra/blob/main/core/zkp.py): `core/zkp.py`
- [Authenticated Encryption](https://github.com/arjun-m-b/hydra/blob/main/core/xchacha20.py): `core/xchacha20.py`

### Monitoring and Audit

- [Hash-chain Audit](https://github.com/arjun-m-b/hydra/blob/main/core/audit.py): `core/audit.py`

### Other components

- **Operator**

## Connections

- Operator → System Launcher: starts system
- Operator → Command Line: uses commands
- Operator → Dashboard Core: views system
- System Launcher → Server A: starts
- System Launcher → Server B: starts
- System Launcher → Secret Sharing: creates shares
- System Launcher → Prepared Records: loads records
- Synthea Records → Record Preprocessing: normalizes
- Record Preprocessing → Prepared Records: writes
- Command Line → Server A: calls API
- Command Line → Server B: fails over
- Command Line → Client Token: uses token
- Dashboard Core → Server A: polls API
- Dashboard Core → Server B: polls API
- Dashboard Views → Dashboard Core: uses API
- Server A → A Record Store: reads and writes
- Server B → B Record Store: reads and writes
- Server A → Server B: mirrors records
- Server B → Server A: syncs records
- Peer Heartbeat → Server A: synchronizes
- Peer Heartbeat → Server B: synchronizes
- Server A → A Breach Detection: updates score
- Server B → B Breach Detection: updates score
- Server A → Key Ratchet: derives key
- Server B → Key Ratchet: derives key
- Server A → Record Re-encryption: re-encrypts records
- Server B → Record Re-encryption: re-encrypts records
- Server A → Failover Proofs: verifies promotion
- Server B → Failover Proofs: proves share
- Server A → Authenticated Encryption: encrypts records
- Server B → Authenticated Encryption: encrypts records
- Server A → Hash-chain Audit: records events
- Server B → Hash-chain Audit: records events