# sarveshsonkusre02/nv-protocol architecture

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

## Overview

nvenv is a local-first credential vault and execution-time proxy: users store secrets, replace plaintext values with nv:// placeholders, then launch applications through an instrumented runner. The runner starts the TLS interception proxy; proxy requests are policy-checked, resolved from the encrypted vault, audited, and forwarded to external services. Separate CLI capabilities provide migration and vault management, Git credential lookup, and an MCP interface. Edges follow the supplied excerpts or explicit README statements; unsampled internals are not inferred.

Main entry points: [`py_wrapper/proxy.py`](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/proxy.py) (TLS proxy), [`py_wrapper/mcp_server.py`](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/mcp_server.py) (MCP server), [`py_wrapper/runner.py`](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/runner.py) (Runtime runner), [`py_wrapper/vault.py`](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/vault.py) (Encrypted vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI entry<br/>[cli.py]"]
  node_commands["Vault commands<br/>[nv.py]"]
  node_git_helper["Git helper<br/>[git.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_runtime["Execution runtime"]
  node_application["Application"]
  node_runner["Runtime runner<br/>[runner.py]"]
  node_proxy["TLS proxy<br/>[proxy.py]"]
  node_ca["Certificate authority<br/>[ca.py]"]
end

subgraph group_security["Secret controls"]
  node_policy["Policy engine<br/>[policy.py]"]
  node_audit["Audit logger<br/>[nv_audit.py]"]
  node_vault[("Encrypted vault<br/>[vault.py]")]
end

subgraph group_integrations["External integrations"]
  node_mcp_client(("AI agent"))
  node_git["Git"]
  node_api["External API"]
end

node_developer(("Developer"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_commands
node_commands -->|"manages secrets"| node_vault
node_commands -->|"starts runtime"| node_runner
node_developer -->|"uses placeholders"| node_application
node_application -->|"launched through"| node_runner
node_runner -->|"starts proxy"| node_proxy
node_runner -->|"creates CA"| node_ca
node_proxy -->|"signs certificates"| node_ca
node_proxy -->|"validates requests"| node_policy
node_proxy -->|"retrieves secrets"| node_vault
node_proxy -->|"logs requests"| node_audit
node_proxy -->|"forwards TLS"| node_api
node_developer -->|"configures helper"| node_git_helper
node_git -->|"requests credentials"| node_git_helper
node_git_helper -->|"looks up token"| node_vault
node_developer -->|"starts server"| node_mcp
node_mcp_client -->|"calls tools"| node_mcp
node_mcp -->|"lists keys"| node_vault
node_mcp -->|"checks policy"| node_policy

click node_cli "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/cli.py"
click node_commands "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/nv.py"
click node_git_helper "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/git.py"
click node_mcp "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/mcp_server.py"
click node_runner "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/runner.py"
click node_proxy "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/proxy.py"
click node_ca "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/ca.py"
click node_policy "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/policy.py"
click node_audit "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/nv_audit.py"
click node_vault "https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/vault.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_commands,node_git_helper,node_mcp toneBlue
class node_application,node_runner,node_proxy,node_ca toneAmber
class node_policy,node_audit,node_vault toneMint
class node_mcp_client,node_git,node_api toneRose
class node_developer toneIndigo
```

## Components

### User interfaces

- [CLI entry](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/cli.py): `py_wrapper/cli.py`
- [Vault commands](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/nv.py): `py_wrapper/nv.py`
- [Git helper](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/git.py): `py_wrapper/git.py`
- [MCP server](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/mcp_server.py): `py_wrapper/mcp_server.py`

### Execution runtime

- **Application**
- [Runtime runner](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/runner.py): `py_wrapper/runner.py`
- [TLS proxy](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/proxy.py): `py_wrapper/proxy.py`
- [Certificate authority](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/ca.py): `py_wrapper/ca.py`

### Secret controls

- [Policy engine](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/policy.py): `py_wrapper/policy.py`
- [Audit logger](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/nv_audit.py): `py_wrapper/nv_audit.py`
- [Encrypted vault](https://github.com/sarveshsonkusre02/nv-protocol/blob/main/py_wrapper/vault.py): `py_wrapper/vault.py`

### External integrations

- **AI agent**
- **Git**
- **External API**

### Other components

- **Developer**

## Connections

- Developer → CLI entry: runs commands (evidence: `README.md`)
- CLI entry → Vault commands: dispatches to (evidence: `py_wrapper/cli.py`)
- Vault commands → Encrypted vault: manages secrets (evidence: `py_wrapper/nv.py`)
- Vault commands → Runtime runner: starts runtime (evidence: `py_wrapper/nv.py`)
- Developer → Application: uses placeholders (evidence: `README.md`)
- Application → Runtime runner: launched through (evidence: `README.md`)
- Runtime runner → TLS proxy: starts proxy (evidence: `py_wrapper/runner.py`)
- Runtime runner → Certificate authority: creates CA (evidence: `py_wrapper/runner.py`)
- TLS proxy → Certificate authority: signs certificates (evidence: `py_wrapper/proxy.py`)
- TLS proxy → Policy engine: validates requests (evidence: `py_wrapper/proxy.py`)
- TLS proxy → Encrypted vault: retrieves secrets (evidence: `py_wrapper/proxy.py`)
- TLS proxy → Audit logger: logs requests (evidence: `py_wrapper/proxy.py`)
- TLS proxy → External API: forwards TLS (evidence: `README.md`)
- Developer → Git helper: configures helper (evidence: `README.md`)
- Git → Git helper: requests credentials (evidence: `README.md`)
- Git helper → Encrypted vault: looks up token (evidence: `py_wrapper/git.py`)
- Developer → MCP server: starts server (evidence: `README.md`)
- AI agent → MCP server: calls tools (evidence: `README.md`)
- MCP server → Encrypted vault: lists keys (evidence: `py_wrapper/mcp_server.py`)
- MCP server → Policy engine: checks policy (evidence: `py_wrapper/mcp_server.py`)
