# joshua-song007/shellhacks architecture

> Architecture diagram of the GitHub repository joshua-song007/shellhacks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshua-song007/shellhacks
- Repository: https://github.com/joshua-song007/shellhacks

## Overview

T-Cell is a host threat-detection and containment system: Scout observes process behavior, validates and scores events, then suspends detected threats and wakes Soldier to evolve and apply a containment gene. Soldier can consult and commit genes to the Solana program; the Electron app supervises the daemons and presents status and controls. Separate capabilities include peer mesh coordination, signed incident advice, and offline trace capture. The README is empty, so the map relies on the supplied source excerpts and tree; unsampled subsystem wiring is shown only where the excerpts document it.

Main entry points: [`crates/scout/src/pipeline.rs`](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/pipeline.rs) (Event pipeline), [`crates/soldier/src/main.rs`](https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/main.rs) (Soldier daemon), [`advisor-service/server.js`](https://github.com/joshua-song007/shellhacks/blob/main/advisor-service/server.js) (Advisor service), [`frontend/electron/backend.cjs`](https://github.com/joshua-song007/shellhacks/blob/main/frontend/electron/backend.cjs) (Daemon supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection"]
  node_scout["Scout daemon<br/>[main.rs]"]
  node_eslogger["Event adapter<br/>[source_eslogger.rs]"]
  node_tes["TES validation<br/>[validate.rs]"]
  node_lineage["Lineage tracking<br/>[lineage.rs]"]
  node_scoring["Threat scoring<br/>[scoring.rs]"]
  node_pipeline["Event pipeline<br/>[pipeline.rs]"]
  node_suspension["Process suspension<br/>[pipeline.rs]"]
end

subgraph group_response["Response"]
  node_soldier["Soldier daemon<br/>[main.rs]"]
  node_replay["Trace replay<br/>[replay_target.rs]"]
  node_search["Allele search<br/>[allele_search.rs]"]
  node_compile["Gene compile/apply<br/>[gene_compile.rs]"]
  node_trace_capture["Trace capture<br/>[main.rs]"]
end

subgraph group_ledger["On-chain ledger"]
  node_ledger_client["Ledger client<br/>[client.rs]"]
  node_program["T-Cell program<br/>[instructions.rs]"]
  node_registry[("Genome registry<br/>[state.rs]")]
end

subgraph group_coordination["Coordination"]
  node_mesh["Mesh daemon<br/>[meshd.rs]"]
end

subgraph group_experience["App and advice"]
  node_backend["Daemon supervisor<br/>[backend.cjs]"]
  node_electron["Electron interface<br/>[main.cjs]"]
  node_renderer["T-Cell dashboard<br/>[main.js]"]
  node_advisor_client["Advisor client<br/>[data.js]"]
  node_advisor["Advisor service<br/>[server.js]"]
  node_postgres[("Incident database")]
  node_spaces[("Raw incident storage")]
end

node_os(("Host events"))
node_peer(("Paired devices"))
node_model["Narration model"]
node_solana["Solana RPC"]
node_operator(("Operator"))
node_sandbox["Isolated host"]

node_os -->|"emits events"| node_scout
node_scout -->|"feeds events"| node_pipeline
node_pipeline -->|"maps lines"| node_eslogger
node_pipeline -->|"validates events"| node_tes
node_pipeline -->|"tracks processes"| node_lineage
node_pipeline -->|"scores lineage"| node_scoring
node_pipeline -->|"suspends threat"| node_suspension
node_scout -->|"reports detections"| node_backend
node_backend -->|"delivers wake"| node_soldier
node_soldier -->|"replays traces"| node_replay
node_soldier -->|"searches alleles"| node_search
node_search -->|"evaluates target"| node_replay
node_soldier -->|"compiles and applies"| node_compile
node_soldier -->|"checks and commits"| node_ledger_client
node_ledger_client -->|"sends RPC transactions"| node_solana
node_solana -->|"dispatches instructions"| node_program
node_program -->|"reads and writes"| node_registry
node_operator -->|"uses"| node_electron
node_electron -->|"starts and controls"| node_backend
node_electron -->|"loads interface"| node_renderer
node_backend -->|"forwards events"| node_renderer
node_renderer -->|"requests review"| node_advisor_client
node_advisor_client -.->|"sends signed incident"| node_advisor
node_advisor -->|"stores incidents"| node_postgres
node_advisor -->|"stores raw data"| node_spaces
node_advisor -.->|"requests narration"| node_model
node_advisor -.->|"returns review"| node_advisor_client
node_operator -->|"pairs and commands"| node_mesh
node_mesh -->|"exchanges messages"| node_peer
node_operator -->|"starts capture"| node_trace_capture
node_trace_capture -->|"runs atomic"| node_sandbox
node_trace_capture -->|"normalizes trace"| node_tes

click node_scout "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/main.rs"
click node_eslogger "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/source_eslogger.rs"
click node_tes "https://github.com/joshua-song007/shellhacks/blob/main/crates/tes/src/validate.rs"
click node_lineage "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/lineage.rs"
click node_scoring "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/scoring.rs"
click node_pipeline "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/pipeline.rs"
click node_suspension "https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/pipeline.rs"
click node_backend "https://github.com/joshua-song007/shellhacks/blob/main/frontend/electron/backend.cjs"
click node_soldier "https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/main.rs"
click node_replay "https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/replay_target.rs"
click node_search "https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/allele_search.rs"
click node_compile "https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/gene_compile.rs"
click node_ledger_client "https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-client/src/client.rs"
click node_program "https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-program/programs/t_cell/src/instructions.rs"
click node_registry "https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-program/programs/t_cell/src/state.rs"
click node_mesh "https://github.com/joshua-song007/shellhacks/blob/main/crates/mesh/src/bin/meshd.rs"
click node_trace_capture "https://github.com/joshua-song007/shellhacks/blob/main/crates/trace-capture/src/main.rs"
click node_electron "https://github.com/joshua-song007/shellhacks/blob/main/frontend/electron/main.cjs"
click node_renderer "https://github.com/joshua-song007/shellhacks/blob/main/frontend/src/main.js"
click node_advisor_client "https://github.com/joshua-song007/shellhacks/blob/main/frontend/src/data.js"
click node_advisor "https://github.com/joshua-song007/shellhacks/blob/main/advisor-service/server.js"

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_scout,node_eslogger,node_tes,node_lineage,node_scoring,node_pipeline,node_suspension toneBlue
class node_soldier,node_replay,node_search,node_compile,node_trace_capture toneAmber
class node_ledger_client,node_program,node_registry toneMint
class node_mesh toneRose
class node_backend,node_electron,node_renderer,node_advisor_client,node_advisor,node_postgres,node_spaces,node_os,node_peer,node_model,node_solana,node_operator,node_sandbox toneIndigo
```

## Components

### Detection

- [Scout daemon](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/main.rs): `crates/scout/src/main.rs`
- [Event adapter](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/source_eslogger.rs): `crates/scout/src/source_eslogger.rs`
- [TES validation](https://github.com/joshua-song007/shellhacks/blob/main/crates/tes/src/validate.rs): `crates/tes/src/validate.rs`
- [Lineage tracking](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/lineage.rs): `crates/scout/src/lineage.rs`
- [Threat scoring](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/scoring.rs): `crates/scout/src/scoring.rs`
- [Event pipeline](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/pipeline.rs): `crates/scout/src/pipeline.rs`
- [Process suspension](https://github.com/joshua-song007/shellhacks/blob/main/crates/scout/src/pipeline.rs): `crates/scout/src/pipeline.rs`

### Response

- [Soldier daemon](https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/main.rs): `crates/soldier/src/main.rs`
- [Trace replay](https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/replay_target.rs): `crates/soldier/src/replay_target.rs`
- [Allele search](https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/allele_search.rs): `crates/soldier/src/allele_search.rs`
- [Gene compile/apply](https://github.com/joshua-song007/shellhacks/blob/main/crates/soldier/src/gene_compile.rs): `crates/soldier/src/gene_compile.rs`
- [Trace capture](https://github.com/joshua-song007/shellhacks/blob/main/crates/trace-capture/src/main.rs): `crates/trace-capture/src/main.rs`

### On-chain ledger

- [Ledger client](https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-client/src/client.rs): `crates/ledger-client/src/client.rs`
- [T-Cell program](https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-program/programs/t_cell/src/instructions.rs): `crates/ledger-program/programs/t_cell/src/instructions.rs`
- [Genome registry](https://github.com/joshua-song007/shellhacks/blob/main/crates/ledger-program/programs/t_cell/src/state.rs): `crates/ledger-program/programs/t_cell/src/state.rs`

### Coordination

- [Mesh daemon](https://github.com/joshua-song007/shellhacks/blob/main/crates/mesh/src/bin/meshd.rs): `crates/mesh/src/bin/meshd.rs`

### App and advice

- [Daemon supervisor](https://github.com/joshua-song007/shellhacks/blob/main/frontend/electron/backend.cjs): `frontend/electron/backend.cjs`
- [Electron interface](https://github.com/joshua-song007/shellhacks/blob/main/frontend/electron/main.cjs): `frontend/electron/main.cjs`
- [T-Cell dashboard](https://github.com/joshua-song007/shellhacks/blob/main/frontend/src/main.js): `frontend/src/main.js`
- [Advisor client](https://github.com/joshua-song007/shellhacks/blob/main/frontend/src/data.js): `frontend/src/data.js`
- [Advisor service](https://github.com/joshua-song007/shellhacks/blob/main/advisor-service/server.js): `advisor-service/server.js`
- **Incident database**
- **Raw incident storage**

### Other components

- **Host events**
- **Paired devices**
- **Narration model**
- **Solana RPC**
- **Operator**
- **Isolated host**

## Connections

- Host events → Scout daemon: emits events
- Scout daemon → Event pipeline: feeds events
- Event pipeline → Event adapter: maps lines
- Event pipeline → TES validation: validates events
- Event pipeline → Lineage tracking: tracks processes
- Event pipeline → Threat scoring: scores lineage
- Event pipeline → Process suspension: suspends threat
- Scout daemon → Daemon supervisor: reports detections
- Daemon supervisor → Soldier daemon: delivers wake
- Soldier daemon → Trace replay: replays traces
- Soldier daemon → Allele search: searches alleles
- Allele search → Trace replay: evaluates target
- Soldier daemon → Gene compile/apply: compiles and applies
- Soldier daemon → Ledger client: checks and commits
- Ledger client → Solana RPC: sends RPC transactions
- Solana RPC → T-Cell program: dispatches instructions
- T-Cell program → Genome registry: reads and writes
- Operator → Electron interface: uses
- Electron interface → Daemon supervisor: starts and controls
- Electron interface → T-Cell dashboard: loads interface
- Daemon supervisor → T-Cell dashboard: forwards events
- T-Cell dashboard → Advisor client: requests review
- Advisor client → Advisor service: sends signed incident
- Advisor service → Incident database: stores incidents
- Advisor service → Raw incident storage: stores raw data
- Advisor service → Narration model: requests narration
- Advisor service → Advisor client: returns review
- Operator → Mesh daemon: pairs and commands
- Mesh daemon → Paired devices: exchanges messages
- Operator → Trace capture: starts capture
- Trace capture → Isolated host: runs atomic
- Trace capture → TES validation: normalizes trace