# h100envy/nerve architecture

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

- Interactive diagram: https://gitdiagram.com/h100envy/nerve
- Repository: https://github.com/h100envy/nerve

## Overview

NERVE is a memecoin DEX-trading protocol organized around a typed Impulse and a deterministic Spine. The primary workflow discovers pool observations, screens them, simulates a wallet round trip, evaluates a thesis, applies deterministic risk sizing, then executes and monitors trades; the Reporter summarizes the audited funnel. Paper and live execution share the protocol, while read-only reconciliation is a separate recovery workflow. The README documents all seven nodes and major CLI capabilities; some wiring beyond the sampled excerpts is represented only where documented.

Main entry points: [`src/nerve/spine.py`](https://github.com/h100envy/nerve/blob/main/src/nerve/spine.py) (Impulse spine), [`src/nerve/desk.py`](https://github.com/h100envy/nerve/blob/main/src/nerve/desk.py) (Trading desk), [`src/nerve/store.py`](https://github.com/h100envy/nerve/blob/main/src/nerve/store.py) (NerveStore), [`src/nerve/cli.py`](https://github.com/h100envy/nerve/blob/main/src/nerve/cli.py) (NERVE CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Desk and inputs"]
  node_cli["NERVE CLI<br/>[cli.py]"]
  node_desk["Trading desk<br/>[desk.py]"]
  node_source["Pool source<br/>[sources.py]"]
  node_chain_source["EVM pool adapter<br/>[adapters.py]"]
end

subgraph group_decision["Impulse decisions"]
  node_spine["Impulse spine<br/>[spine.py]"]
  node_scanner["Scanner<br/>[scanner.py]"]
  node_reflexes["Deterministic reflexes<br/>[reflexes.py]"]
  node_score["NERVE score<br/>[score.py]"]
  node_sentinel["SENTINEL<br/>[sentinel.py]"]
  node_analyst["Analyst<br/>[analyst.py]"]
  node_risk["Risk<br/>[risk.py]"]
end

subgraph group_execution["Execution and state"]
  node_executor["Executor<br/>[executor.py]"]
  node_execution_adapter["Execution adapters<br/>[execution.py]"]
  node_monitor["Position monitor<br/>[monitor.py]"]
  node_store[("NerveStore<br/>[store.py]")]
end

subgraph group_operations["Operations"]
  node_reporter["Operational reporter<br/>[reporter.py]"]
  node_reconcile["Reconciliation<br/>[reconcile.py]"]
  node_chainread["Read-only chain reader<br/>[chainread.py]"]
end

node_operator(("Trading operator"))
node_openai{{"OpenAI API"}}
node_rpc{{"EVM JSON-RPC"}}

node_operator -->|"invokes"| node_cli
node_cli -->|"runs desk"| node_desk
node_desk -->|"discovers pools"| node_source
node_source -->|"provides adapter"| node_chain_source
node_chain_source -->|"reads pools"| node_rpc
node_desk -->|"routes impulses"| node_spine
node_spine -->|"dispatches"| node_scanner
node_scanner -->|"scores metrics"| node_score
node_spine -->|"checks reflexes"| node_reflexes
node_spine -->|"dispatches"| node_sentinel
node_sentinel -->|"simulates round trip"| node_rpc
node_spine -->|"dispatches"| node_analyst
node_analyst -.->|"requests thesis"| node_openai
node_spine -->|"dispatches"| node_risk
node_spine -->|"dispatches"| node_executor
node_executor -->|"executes trade"| node_execution_adapter
node_execution_adapter -->|"quotes and sends"| node_rpc
node_executor -->|"records intent and position"| node_store
node_desk -->|"monitors positions"| node_monitor
node_monitor -->|"reads and updates"| node_store
node_monitor -->|"checks chain"| node_rpc
node_desk -->|"builds report"| node_reporter
node_reporter -->|"reads audit trail"| node_store
node_cli -->|"starts recovery"| node_reconcile
node_reconcile -->|"reads and resolves intents"| node_store
node_reconcile -->|"queries chain"| node_chainread
node_chainread -->|"reads nonce and balances"| node_rpc

click node_cli "https://github.com/h100envy/nerve/blob/main/src/nerve/cli.py"
click node_desk "https://github.com/h100envy/nerve/blob/main/src/nerve/desk.py"
click node_source "https://github.com/h100envy/nerve/blob/main/src/nerve/sources.py"
click node_chain_source "https://github.com/h100envy/nerve/blob/main/src/nerve/adapters.py"
click node_spine "https://github.com/h100envy/nerve/blob/main/src/nerve/spine.py"
click node_scanner "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/scanner.py"
click node_reflexes "https://github.com/h100envy/nerve/blob/main/src/nerve/reflexes.py"
click node_score "https://github.com/h100envy/nerve/blob/main/src/nerve/score.py"
click node_sentinel "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/sentinel.py"
click node_analyst "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/analyst.py"
click node_risk "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/risk.py"
click node_executor "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/executor.py"
click node_execution_adapter "https://github.com/h100envy/nerve/blob/main/src/nerve/execution.py"
click node_monitor "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/monitor.py"
click node_store "https://github.com/h100envy/nerve/blob/main/src/nerve/store.py"
click node_reporter "https://github.com/h100envy/nerve/blob/main/src/nerve/agents/reporter.py"
click node_reconcile "https://github.com/h100envy/nerve/blob/main/src/nerve/reconcile.py"
click node_chainread "https://github.com/h100envy/nerve/blob/main/src/nerve/chainread.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_cli,node_desk,node_source,node_chain_source toneBlue
class node_spine,node_scanner,node_reflexes,node_score,node_sentinel,node_analyst,node_risk toneAmber
class node_executor,node_execution_adapter,node_monitor,node_store,node_openai toneMint
class node_reporter,node_reconcile,node_chainread toneRose
class node_operator,node_rpc toneIndigo
```

## Components

### Desk and inputs

- [NERVE CLI](https://github.com/h100envy/nerve/blob/main/src/nerve/cli.py): `src/nerve/cli.py`
- [Trading desk](https://github.com/h100envy/nerve/blob/main/src/nerve/desk.py): `src/nerve/desk.py`
- [Pool source](https://github.com/h100envy/nerve/blob/main/src/nerve/sources.py): `src/nerve/sources.py`
- [EVM pool adapter](https://github.com/h100envy/nerve/blob/main/src/nerve/adapters.py): `src/nerve/adapters.py`

### Impulse decisions

- [Impulse spine](https://github.com/h100envy/nerve/blob/main/src/nerve/spine.py): `src/nerve/spine.py`
- [Scanner](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/scanner.py): `src/nerve/agents/scanner.py`
- [Deterministic reflexes](https://github.com/h100envy/nerve/blob/main/src/nerve/reflexes.py): `src/nerve/reflexes.py`
- [NERVE score](https://github.com/h100envy/nerve/blob/main/src/nerve/score.py): `src/nerve/score.py`
- [SENTINEL](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/sentinel.py): `src/nerve/agents/sentinel.py`
- [Analyst](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/analyst.py): `src/nerve/agents/analyst.py`
- [Risk](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/risk.py): `src/nerve/agents/risk.py`

### Execution and state

- [Executor](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/executor.py): `src/nerve/agents/executor.py`
- [Execution adapters](https://github.com/h100envy/nerve/blob/main/src/nerve/execution.py): `src/nerve/execution.py`
- [Position monitor](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/monitor.py): `src/nerve/agents/monitor.py`
- [NerveStore](https://github.com/h100envy/nerve/blob/main/src/nerve/store.py): `src/nerve/store.py`

### Operations

- [Operational reporter](https://github.com/h100envy/nerve/blob/main/src/nerve/agents/reporter.py): `src/nerve/agents/reporter.py`
- [Reconciliation](https://github.com/h100envy/nerve/blob/main/src/nerve/reconcile.py): `src/nerve/reconcile.py`
- [Read-only chain reader](https://github.com/h100envy/nerve/blob/main/src/nerve/chainread.py): `src/nerve/chainread.py`

### Other components

- **Trading operator**
- **OpenAI API**
- **EVM JSON-RPC**

## Connections

- Trading operator → NERVE CLI: invokes
- NERVE CLI → Trading desk: runs desk
- Trading desk → Pool source: discovers pools
- Pool source → EVM pool adapter: provides adapter
- EVM pool adapter → EVM JSON-RPC: reads pools
- Trading desk → Impulse spine: routes impulses
- Impulse spine → Scanner: dispatches
- Scanner → NERVE score: scores metrics
- Impulse spine → Deterministic reflexes: checks reflexes
- Impulse spine → SENTINEL: dispatches
- SENTINEL → EVM JSON-RPC: simulates round trip
- Impulse spine → Analyst: dispatches
- Analyst → OpenAI API: requests thesis
- Impulse spine → Risk: dispatches
- Impulse spine → Executor: dispatches
- Executor → Execution adapters: executes trade
- Execution adapters → EVM JSON-RPC: quotes and sends
- Executor → NerveStore: records intent and position
- Trading desk → Position monitor: monitors positions
- Position monitor → NerveStore: reads and updates
- Position monitor → EVM JSON-RPC: checks chain
- Trading desk → Operational reporter: builds report
- Operational reporter → NerveStore: reads audit trail
- NERVE CLI → Reconciliation: starts recovery
- Reconciliation → NerveStore: reads and resolves intents
- Reconciliation → Read-only chain reader: queries chain
- Read-only chain reader → EVM JSON-RPC: reads nonce and balances